A few weeks ago I started thinking about writing an eBook. While searching for the best tools to write ebooks I found this thing I didn't know: AsciiDoc.
For developers as myself, Markdown is the first thing we think when considering writing technical documents. But, at least for me, and maybe for many other developers, AsciiDoc was a total mystery.
By reading what AsciiDoc goal was, I realized I have never really thought what Markdown was good at. The response was disappointing: not very much apart of simple basic formatting of text.
As you can see in this screenshot of https://dev.to post editor's sidebar, the most common Markdown syntax is quite concise:
titles, italics, bold, links, lists and blocks. That's it.
Those are the most used features. And they are also the most common commonly provided by text editors.
If you want more features, like footnotes, tables or definition lists, you need to use extensions. The problem with this is that those extensions are not supported everywhere and you need to ensure the editor you use has support for the features you want. This makes Markdown not transferable between different editors as they most likely support different extensions.
But that's not the worst, there are things that are not even possible to do with Markdown. For example, asides, table of contents, cross-references, admonitions, sidebars and equations and formulas, to list some, are imposible to write if you are creating a book.
You may say, and you'll be right, that not everyone needs those features. If you are writing a blog post in Wordpress or a Pull Request in GitHub you'll never need those features.
But I wanted to write an eBook and do needed those features. Additionally, as a developer, I always prefer writing plain text files. Those can be be version tracked in git or transformed into some output format using some tool. You can't do that with a WYSIWYG editor like Word or Google Docs.
So for my use case, Markdown was not enough.
Reading a little more I found that AsciiDoc was designed from the very beginning to be able to produce complex products like fully featured books from plain text files.
AsciiDoc basic syntax is equivalent to Markdown so there is no really a learning curve to overcome.
As you can see in the official syntax comparison, they are very similar.
But the fact that you can use AsciiDoc to generate complex tables, asides, definition lists, sidebars and table of contents, while writing everything in simple text files puts AsciiDoc miles ahead of Markdown.
So I was sold. I started learning how to use AsciiDoc to write my eBook and how to use AsciiDoctor to process my source file and produce many output formats like PDF, ePub or HTML from it very easily.
After that everything went out of control 😆 and I ended writing a guide to setup AsciiDoc to write eBooks 😊.
With the help of the #gumroad community I published my eBook and after a couple of days I sold 2 copies and I earned my membership to the "earn my first dollar online" club 🕺🕺🕺!
In summary, if you want to write an eBook and you're a developer, use AsciiDoc to write it.
About
I'm Miguel Cobá. I write about Elixir, Elm, Software Development, and eBook writing.
- Follow me on Twitter
- Subscribe to my newsletter
- Read all my articles on my blog
- Get my books:
Top comments (2)
Just bought your book. Thanks for sharing what you learned!
Thank you very much for your support, Jack. You made my day. Hope the info helps you create your own fantastic books.