Asciidoctor as the solution for writing anything, articles, documentation, books

Show table of contents

Asciidoctor is the solution for writing anything. Be it articles, books, documents, or technical documentation. Asciidoctor provides the toolkit for distraction free writing which will enhance your writing productivity. Not only that, but it’s future proof, meaning you can use it

What you’ll learn:
  • ✓ Why you should adopt Asciidoctor for writing anything even if you’re non-technical.

  • ✓ The benefits will change the way you think, write and produce anything creatively.

Writing in Asciidoctor

Writing needs to be easy, fast and distraction free

These promises are a reality when using asciidoctor to write.

What is Asciidoctor and why use it?

Asciidoctor provides a simple syntax with which you can write anything including technical documentation, articles, books.

I’m using it to write blog posts, keep notes and It’s the main vehicle behind organizing my courses and writing!

You do this by writing in a plaintext document using easy symbols. It somewhat resembles Markdown, yet it provides powerfull text processing capabilities and a publishing toolchain.

This means you can write in any text editor (GEdit, Geany, VIM, emacs, notepad, Notepad\++, whatever) [1]

All you need to start a new file and save it with an .adoc, .asc or .txt extension.

Asciidoctor gives you the benefit that you can write, edit.. anywhere, anytime without being interrupted by the complexity of modern text editors. Plus, it’s archive friendly. Being a simple text file means you can access it in 100 years and still be able to understand the text written!

But wait, there’s more! Exporting to any format

Not only that, you can export your document to ANY format available.

This means you write it once and export it to any format your heart desires.

Asciidoctor allows you to export to the following formats:
  • HTML5

  • PDF

  • manpage

  • LaTeX

  • docbook

  • epub3

If the above formats aren’t enough there is a simple and effective way to have even more. By using pandoc, you can actually convert your asciidoc file to any other format.

The only downside of pandoc is that it doesn’t support reading from an asciidoctor file input file. However, it has full support for HTML5. Which means you can use HTML or another format such as latex as an intermediary format to convert your documents.

Am example of how to use asciidoctor and pandoc in converting a asciidoc file to html to docx
asciidoctor asciidoc-and-alternatives-for-writing.adoc
pandoc asciidoc-and-alternatives-for-writing.html -f html -t docx -s -o asciidoc_awesomeness.docx

The above can be automated easily to generate pdf or anything required by a 3rd party. The next time someone asks you for a PDF, docx or whatever format don’t even bother installing and or using specialized programs which sip away your mental energy. You can write in Asciidoctor and then export to a desired format

By using pandoc to export to an Asciidoc file if you want to convert your existing documentation/files.

Let’s see a simple example of how asciidoc looks like
= Introduction to AsciiDoc
Doc Writer <doc@example.com>

A preface about https://asciidoc.org[AsciiDoc].

== First Section

* item 1
* item 2

[source,elixir]
IO.puts "Hello, World!"

This is plain text which makes it simple and easy to write in.

There is an amazing writers guide which details everything you need to know to get started. It also explains why asciidoctor allows you to just focus on writing and leaving things like formatting out of the equation.

The Problems of Modern Word Processors

Word Processors bring with them quite a few technical problems. Let’s explore just a few of them together and you’ll get the idea of why you will want to adopt AsciiDoctor even if you’re not technical minded.

  1. They’re extremely complicated, and you waste vast amounts of time trying to learn every feature.

    • Instead if you learned to program you could more easily do what you wanted..

  2. You may need to purchase a license

    • Making it often difficult to upgrade or switch to something else.. because "you paid for it"

    • Backward compatibility is not ensured

  3. When you send it to someone, they might not have the software required to view, nor edit it. Creating further headaches and problems.

  4. The file format might not exist in 10 years if the company no longer functions

    • AsciiDoctor is future proof (it’s plaintext and open source) for years to come. This can’t be said of other formats. It’s perfect for Archiving!

Contrasting it with the power of AsciiDoctor which is plaintext. All of the above problems are automatically resolved when you use AsciiDoctor! You can’t go wrong!

Plus, there is one extra benefit which is often overlooked yet it’s provided out of the box!

You can now use a versioning control system like git or fossil to manage changes!

Adopt Asciidoctor

Of course there are many more things to say about asciidoctor. I’d recommend going to the official https://asciidoctor.org/ website and reading about it. Install asciidoctor and start using it NOW! Let asciidotor help you improve your writing flow.


1. This blog post was written in Asciidoctor with the Visual Studio Code editor. Using the VIM and Asciidoc extensions.

Subscribe to my newsletter

NOTE:You will need to confirm your e-mail address in order to fully complete the subscription process.

The comments section is closed.

You might enjoy these similar articles: