Markdown, Textile, AsciiDoc, and reStructuredText 4 free Markup languages for documentation
Developers are not just faced with the choice of a programming language. You also have to choose a language for the documentation – pure HTML has long since become obsolete here.
Companies on the topic
If you want to create a manual software documentation like a manual, you have better alternatives than pure HTML.
The documentation of software projects is often divided into two parts: API and source documentation on the one hand and manuals for users, operators and possibly developers on the other. The technical part is usually implemented automatically and output in some form of HTML.
This is about the manually written manuals: these too end up mostly as HTML in the browser, but also in formats such as PDF or LaTeX in order to produce print editions. Markdown is probably the most common lightweight markup language for online content today. With the very simple syntax, even laypeople can quickly write properly formatted articles.
A large part of all WordPress articles on the net, if not written with the internal WYSIWYG editor, may have been produced with Markdown; and GitHub also supports the free standard-in its own variant with additional features, which leads to probably the biggest Markdown problem, more on that.
But there are also alternatives that should also be briefly presented here: AsciiDoc as the expected successor and most powerful language, reStructuredText, which also masters the technical documentation, and finally textile, which could offer itself as a minimalist variant. All languages are open formats.
Markdown
Markdown already exists since 2004 and is characterized by three things: a very simple syntax, enormous distribution and several splits / extensions. Markdown code is simply translated into HTML and in its original form is designed to use the most important HTML elements in a simplified form.
So Markdown makes it possible to write articles without HTML knowledge or WYSIWYG editors in normal word processing, content management systems and so on. The idea gained ground and led to the problem that Markdown faces today: there is basically no ” one ” Markdown.
On the one hand, there are variants such as GitHub Flavored Markdown, which bring additional features. On the other hand, there are hundreds of tools that implement Markdown for CMS, convert it to other formats, allow more notations, and so on. The advantage: in the Markdown universe, pretty much every wish can be fulfilled. The disadvantage: it is the famous Rabbit Hole, at some point you have assembled a huge tool stack, which wants to be serviced in several places.
From time to time there are tentative standardization efforts, but this is also only from third parties, original developer John Gruber comments: “Different sites (and people) have different needs. No one syntax would make all happy.”This is also matched by licensing in the permissive BSD style, which makes re-use extremely easy.
This again shows the advantage that there is a solution for everything, and the disadvantage that Markdown code no longer works after a tool change, such as a CMS addon. For large documentation projects, Markdown has its appeal, but if you want to use features outside the base, it is to be enjoyed with caution. For blog texts and the like, Markdown is still the first choice-and that’s why it was launched!
Textile
Textile appears again and again in discussions about lightweight markup languages, so here too-but only very briefly: Compared with Markdown, you can quickly see that syntax and scope are so similar that it initially seems interchangeable. Why, quickly becomes clear. Textile has been around since 2002, so it’s older than Markdown.
In his contribution to the first release of Markdown, developer John Gruber also refers directly to textile and the similarity to Markdown. Because at Textile everything originally ran through an online editor, through which you could write textile markup, convert it to HTML and then use it in your own projects via copy&paste.
Markdown then implemented such a conversion as a stand-alone Perl tool with a syntax based on textile, among other things. PHP and Python implementations exist for the Textile specification. For larger projects, textile may only be relevant in exceptional cases, Markdown is very similar in its basis, but ultimately much more powerful and, above all, more widespread.
AsciiDoc
AsciiDoc also dates back to 2002 and was originally written in Python, but not only for web pages or as a pure HTML translator, but as a document format for all purposes, translatable into HTML, PDF, EPUB and man page, among others. The AsciiDoc definition is now officially supported by the Asciidoctor project, which provides a complete toolchain for converting AsciiDoc to HTML, DocBook and other formats.
Asciidoctor is aware of Markdown’s prominent role: “The defacto lightweight markup language is Markdown.“ And here AsciiDoc offers itself as the better Alternative: On the syntactic side, AsciiDoc is simple enough to be used as a 1:1 replacement for the typical Markdown purposes. Technically, AsciiDoc, or the Asciidoctor toolchain, offers some possibilities itself, which would have to be implemented with Markdown via third-party tools (such as importable properties, text replacements or plugins).
On a conceptual level, AsciiDoc also relies on extensible syntax and features as core elements – so there is room for growth, where Markdown remains rather static and relies on variants and third-party tools. And since 2019, there have also been standardization efforts under the auspices of the Eclipse Foundation. All points, but especially the prospect of real standards, speak clearly for the preference of AsciiDoc when it comes to larger documentation projects.
In terms of syntax, the differences are not great, but in detail AsciiDoc can score points. For example, many awards are kept shorter, there are explicit tags for awards within words, links are much more readable, numbering in lists happens dynamically and so on. A feature that offers enormous advantages: external content can be included via the include tag!
When it comes to support in development environments, browsers and so on, AsciiDoc is also well-supported, prominent IDEs such as Microsoft Visual Studio are supported, there are preview extensions for all major browsers and editors such as Vi, Emacs or Notepad++ are also provided with extensions.
Nevertheless, Markdown is still an advantage here in case of doubt – even in many comment fields of websites, Markdown syntax works by default. But AsciiDoc / Asciidoctor is probably the most exciting project in the field of simple markup languages.
reStructuredText
reStructuredText, you won’t be surprised, is from the Markup wonder year 2002 and belongs to the Docutils project. reST, as it is often referred to briefly, is often mentioned in this context as well as Textile, but does not really do justice to the comparison with AsciiDoc and Markdown.
However, it is interesting because reStructuredText is not just a specification for manually written texts, even if you could use it on GitHub and Bitbucket, for example. Essentially, reST is designed for technical documentation, for example, the Linux kernel is automatically documented via Sphinx in reST format-after Markdown and then AsciiDoc have been discarded.
Summary
For manual documentation, Markdown is still standard, but AsciiDoc has the potential to change this in a fairly short time – not to underestimate the acceptance and spread of the market leader through its use in WordPress and on GitHub. Textile, on the other hand, is likely to be relevant in exceptional cases. reStructuredText is rather to be found in the automated technical documentation and for manuals therefore probably only in interaction with this really exciting – whereby the syntax itself is very easy to write.
Whatever you choose, all major languages can basically be converted back and forth, using many specialized tools, but also the universal converter Pandoc.
(ID:47324931)
