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.
Table of Contents
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.adocpandoc asciidoc-and-alternatives-for-writing.html -f html -t docx -s -o asciidoc_awesomeness.docxThe 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 AsciiDocDoc
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.
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..
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
When you send it to someone, they might not have the software required to view, nor edit it. Creating further headaches and problems.
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. Asciidoctor can be exported via the commandline as shown in the documentation. The blogging system I’ve developed and which runs on this website converts asciidoctor to HTML automatically.