AsciiDoc syntax

Overview

GitLab supports use of AsciiDoc syntax in addition to Markdown in GitLab Wikis. AsciiDoc describes itself as:

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

AsciiDoc syntax is much more powerful than Markdown, but that comes somewhat at the expense of human readability.

This AsciiDoc Cheat sheet gives a good example of AsciiDoc markup.

When to use AsciiDoc

In general, Markdown provides a lower barrier to entry than AsciiDoc which is important when creating a community-sourced document like a Wiki. The one time to consider use of AsciiDoc is if you are using the Wiki as a tool to develop for material that will be put into The Open Group publication process. We now have a Gitlab project with The Open Group Standards Template, along with a CI/CD toolchain for automatically generating and publishing standards documents in AsciiDoc format.

Please talk to a member of staff if you are considering use of AsciiDoc for the development of standards.