Human-readable markup language Works with AsciiDoc markups
AsciiDoc is currently the most interesting lightweight markup language – with more features than industry leader Markdown and very good tooling. For technical documentation, but also simple blogs, the format has much to offer.
Company about the topic
AsciiDoc in Visual Studio Code.
(Image: Lang / AsciiDoc)
AsciiDoc falls under the category of lightweight markup languages, i.e. human-readable markup languages. The language already exists since 2002, the year of birth of several similar projects. The current attention for AsciiDoc is always to be considered in the context of the Asciidoctor project, which now manages the official AsciiDoc specification, as a processor is the reference implementation and offers a complete toolchain.
We have recently presented a comparison of several award languages to you, so here is only a brief comparison to Markdown: The quasi-standard focuses in its pure form on the most important awards and their conversion into HTML. Over time, users ‘ demands grew and variants of Markdown developed – so that there is no more general Markdown code today.
AsciiDoc, on the other hand, was designed in advance to be extended in the core and offers some features and tags more. This is mainly due to the fact that AsciiDoc should be a pure text alternative to DocBook-and DocBook tools can be used via the corresponding converter. DocBook, for its part, has been developed since 1991 and is used in large projects such as KDE and Gnome.
Working with AsciiDoc
The actual work with Asciidoctor is trivial: AsciiDoc content can be converted from the command line, and an API is also available. The standard version is a Ruby application, in addition, GitHub offers all kinds of AsciiDoc tools: Java bindings, a JavaScript port, converter for PDF, Bespoke.js, EPUB and DocBook, diagram extensions, plugins for Visual Studio Code, IntelliJ IDEA, Maven, Gradle and Jekyll, as well as for the browsers Chrome, Firefox, Edge and Opera, Docker images and a parser for AsciiMath.
The most important aspect is, of course, the actual AsciiDoc document. And this differs not only in the syntax of Markdown, but also in the features – there are also hints of a scripting language here. The following are the most important possibilities apart from the pure formatting of content.
- Attributes and Header: Entire documents and individual elements can be attributed. For example, you can set paths for images, set meta information as headers, enable features such as the automatic table of contents, or configure its levels.
- Replacement: AsciiDoc can handle text modules in two ways. On the one hand, simple substitutions can be used directly in the document via attributes, here a simple syntax like “:ml: Mirco Lang” suffices to have the initials replaced by the name as soon as the document runs through the processor. On the other hand, external content can be obtained via include statement. With such an include, however, not only content can be reused, but also global attributes can be set – a feature that goes far beyond the Markdown concept alone.
- Conditionals: Simple if statements can be used to evaluate attributes and include or exclude content blocks accordingly.
Especially for Markdown changers there are also some interesting features in the syntax itself. For example, AsciiDoc has special instructions for awards within words, simply over duplicate tags – for example, for italic:
_alles kursiv_
nur __teil__kursiv
Another Highlight is the automatic numbering in lists In Markdown with “1. foo 2. bar 3. Foobar“ created in AsciiDoc is sufficient:
. foo . bar . foobar
The big advantage: you can insert elements afterwards without having to change all numbers manually. The exact syntax for all these features can be found in the basically very good AsciiDoc documentation, which still has gaps in some places.
In some aspects, it is easy to feel that the much simpler knitted Markdown is somewhat more mature. On WordPress.com if, for example, only an outdated backend plug-in can be found, there are at least some converters/publishers for the command line on GitHub. Nevertheless, AsciiDoc should catch up strongly here in the near future, at the latest when the standardization efforts of the AsciiDoc charter of the Eclipse Foundation bear fruit.
AsciiDoc in VS Code and IntelliJ
AsciiDoc in Visual Studio Code.
(Image: Lang / AsciiDoc)
Microsoft Visual Studio Code makes things easy for you, you can simply install the Asciidoctor plug-in from the Visual studio marketplace. This gives you syntax highlighting, live preview and the ability to use snippets. In VSC, simply open the input with “CTRL + P” and install via
ext install asciidoctor.asciidoctor-vscode
There is also an AsciiDoc plug-in with similar functionality for the IntelliJ development environment.
AsciiDoc in Notepad++
For Notepad++ there is unfortunately no real plugin, here a small detour has to be made. First, you have to set up the syntax highlighting, so simply import the XML file linked here into Notepad++ via the language manager.
For preview in the browser, you can use one of the official browser extensions. After installation, you must call the plug-in once to grant the necessary approvals. Optionally, you can also store your own CSS files here.
Of course, the preview is not live, but is updated in an adjustable cycle – so the document must first be saved in Notepad++. Working with the browser plugins works very well in and of itself, but there are problems with the correct implementation of AsciiDoc features in some places, such as some formatting of tables.
AsciiDoc in Vim
The Asciidoctor plugin in the Chrome browser.
(Image: Lang / AsciiDoc)
In Vim it becomes easy again: the syntax highlighting is already available by default and the preview runs naturally over the browser, so that you only have to open the current file in such a way, what from Vim itself about with …
:!start chrome.exe %:p
… works.
AsciiDoc in Vim with preview in Asciidoctor theme.
(Image: Lang / AsciiDoc)
In contrast to Notepad++, however, you can also use the folding, i.e. the folding and unfolding of hierarchical levels – also without a plug – in. You can simply enter the code from the blog post of Emmanuel Bernard in the”~/.vimrc ” and then open and close all layers introduced with equal signs using the usual Vim folding commands. And if you are not used to them: the commands always start with “z” (because the Z should look like something folded …), followed by “o” for opening the layer under the curser or “c” for closing – and that in command mode directly in the text, not with”: “in the prompt!
If you have the taste for blood and a few first steps with AsciiDoc and ASCII doctor want to start with asciidoc live, an Editor with preview directly in the Browser. At home in the terminal, a simple Asciidoctor installation is sufficient …
gem install asciidoctor
… and the instruction …
asciidoctor foobar.asciidoc
… creates an HTML5 version of the specified AsciiDoc file in the same path. The browser plug-in is even easier to use, with one major advantage: its settings contain a whole range of predefined themes/stylesheets that you can easily try out.
(ID:47330459)
