This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Docs-as-Code

1 - Asciidoc

Syntax

Since AsciiDoc is offered as a “complete system,” including both language and interpreter, there is a central syntax. Unlike Markdown, AsciiDoc has no variants or dialects.

Comments

AsciiDoc code can be commented, just like any other source code. This means that comments are not taken into account during the interpretation of the source text (e.g., when converting to PDF). This allows documents or parts of text to be commented on, or notes to be left.


This is arbitrary text in AsciiDoc.

// This line will not be interpreted.

This line will be displayed.

Paragraphs/Lines

AsciiDoc does not require special specifications for line breaks and paragraphs. The text is rendered as it was written. However, it is possible to force a line break using a plus symbol. Alternatively, the attribute [%hardbreaks] can be prepended.


This is line number one.
This is line number two.

And now another paragraph.

This line will be +
hard broken.

[%hardbreaks]
These lines will be 
displayed as they are.

Text Formatting

Bold, Italic, Highlight, Code

To display text as bold, italic, or code, there are two possibilities, depending on whether the text to be formatted stands alone or is located in the middle of a text.

A single word can be enclosed in single asterisks, underscores, hashtags, or grave accents.


This text is *bold*.
This text is _italic_.
This text is `code`.
This text is #highlighted#.

If you want to format a part of text in the middle of a sentence, this is achieved by using double asterisks, underscores, hashtags, or grave accents. If this were attempted with single characters, the formatting rule would be ignored.


The "tt" in Mi**tt**ag are bold.
The "tt" in Mi*tt*ag are not bold.

The "tt" in Mi__tt__ag are italic.
The "tt" in Mi_tt_ag are not italic.

The "tt" in Mi``tt``ag are code.
The "tt" in Mi`tt`ag are not code.

The "tt" in Mi##tt##ag are highlighted.
The "tt" in Mi#tt#ag are not highlighted.

Underlined, Strikethrough

To underline or strikethrough text, hashtags with an attribute are used.


This text is [.underline]#underlined#.
This text is [.line-through]#strikethrough#.

Superscript, Subscript, and Smart Quotes

Using superscript and subscript, parts of text can be raised or lowered. For this, the text parts are placed between single carets/circumflexes (superscript) or tildes (subscript).


This is a ~low~point.
This is a ^high^point.

Here is the completed AsciiDoc text with content for the empty chapters (starting from “Links”), based on the official AsciiDoc syntax and common best practices:

Here is the revised version of your AsciiDoc documentation — now with a short, concise explanation for each chapter before the syntax examples come. This keeps it clear, understandable, and useful for beginners.

Explanation:
AsciiDoc supports both external web links and internal references within the document (anchors) as well as links to local files. The syntax is simple and intuitive — ideal for documentation that needs to be linked.

https://www.asciidoc.org[AsciiDoc Website]

[[section1]]
== First Section

See also <<section1>>.

link:manual.pdf[Download Manual]

Document Header

Explanation:
The document header contains metadata such as title, author, date, and global attributes. It is optional but recommended for structured documents — especially for PDF or book exports.

= Document Title
Author Name <author@example.com>
:doctype: book
:author: Author Name
:revdate: 2026-02-09

Automatic Table of Contents

Explanation:
A table of contents (TOC) is automatically generated as soon as the attribute :toc: is set. It can be placed on the left, right, or anywhere else — helpful for longer documents.

:toc: left

= Main Title

== Chapter 1
Content...

== Chapter 2
Further content...

Includes

Explanation:
With include::, you can embed external AsciiDoc files or parts of them. Practical for reusable sections (e.g., footnotes, notes, chapters).

include::chapter1.adoc[]

include::../shared/footnotes.adoc[tag=section2]

Lists

Explanation:
AsciiDoc supports bulleted lists (*), numbered lists (.), and definition lists (::). Indentation determines the hierarchy — simple and clearly structured.

Bulleted Lists

* Point 1
* Point 2
  * Subpoint

Numbered Lists

. First point
. Second point
.. Subpoint

Definitions

Term::
  Definition of the term.

Images

Explanation:
Images are embedded using image::. You can control size, alt text, and scaling. Works in HTML, PDF, and EPUB — depending on the backend.

image::logo.png[Logo, 200, 100]

image::diagram.svg[Diagram, scaledwidth=50%]

Audio

Explanation:
Audio files (e.g., voice messages) can be embedded directly in the document. Useful for tutorials or multimedia documentation.

audio::voicemessage.mp3[Voice Message, autoplay]

Videos

Explanation:
Videos are embedded using video::. You can enable controls like autoplay, controls, or loop — ideal for instructions or presentations.

video::tutorial.mp4[Tutorial, width=640, height=360, autoplay, controls]

Keyboard, Button, Menu Macros

Explanation:
With kbd: and menu:, you can clearly highlight keyboard shortcuts and menu paths — particularly useful in instructions or software documentation.

Keyboard Shortcuts

Press kbd:[Ctrl+C] to copy.

Go to menu:File[Save As...].

Source Code

Explanation:
Code blocks with syntax highlighting are introduced with [source]. You can specify languages like Python, Bash, or HTML — helpful for developer documentation.

[source,python]
----
def hello():
    print("Hello World")
----

Notes, Text Blocks

Explanation:
With NOTE:, TIP:, WARNING:, etc., you can highlight important information. Quotes with ____ are ideal for quotations or excerpts from external sources.

Notes

NOTE: This is important information.

TIP: Here's how to do it faster.

Quotes

____
"This is a quote."
— Author
____

Tables

Explanation:
Tables are defined with |===. Each cell is separated by |. You can control column count, borders, and captions — perfect for comparisons or data.

|===
| Column 1 | Column 2
| Value A  | Value B
| Value C  | Value D
|===

IDs, Roles, and Options

Explanation:
With [[id]], you set anchors for internal links. With [.role], you can assign CSS classes. With [%option], you control block behavior (e.g., unnumbered).

IDs

[[chapter2]]
== Chapter 2

Roles

[.note]
This text has a role.

Options

[%unnumbered]
== This section has no number.

Attributes and Special Characters

Explanation:
Attributes (:name: value) enable reuse of text or values. Special characters like + or \\ may need to be escaped to avoid being interpreted as formatting.

Attributes

:version: 1.0

The version is {version}.

Special Characters

+ for plus, \\ for backslash, &#x27; for apostrophe.

Bibliography

Explanation:
A bibliography can be created manually or via bibliography::. Useful for scientific or referenced documents.

[bibliography]
== Literature

- Author, Title, Publisher, Year

Footnotes

Explanation:
Footnotes are inserted with footnote:[Text] or [footnote:]. They appear at the end of the document or page — ideal for supplementary information.

This is a sentence with a footnote.footnote:[This is the footnote.]

Another sentence with [footnote:2]Footnote 2[footnote:2].

Conclusion

Advantages

A major advantage of AsciiDoc is certainly its wide range of functions, which even allows complex documents with tables of contents and bibliographies. The include function and possible comments also facilitate handling large amounts of text and many files; collaborative editing is thus also easy. Since AsciiDoc is not just a language but also comes with an application, productive work can be done without much detour. Apart from a text editor for the text files, nothing else is needed.

Disadvantages

AsciiDoc is by far not as widely used as Markdown. Productive tools like note-taking apps, wikis, or static site generators rarely support AsciiDoc, and if they do, usually only via plugins. Those who work a lot with such tools will not get around using Markdown and AsciiDoc in parallel.

Further Information

Literature

Tools for Using AsciiDoc

Text Editors

Static Site Generators

Transformation Tools

2 - Markdown

Markdown is certainly the most widespread simple markup language.

Syntax

Basic Syntax

These are the basic commands that Markdown offers and should fundamentally work in every tool.

Headings

To display headings, one or more hashtags are placed before the heading title, depending on the level.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Note: It is best to always insert a blank line before a heading, as interpretations may otherwise be incorrect.

Paragraphs/Lines

There are no real notations for line breaks and paragraphs; the text is displayed as written. To support a line break, two spaces can be added at the end of the line, or alternatively, the HTML tag <br> can be used.


First line with two spaces at the end.  
And now the next line.

First line with the HTML tag at the end.<br>
And now the next line.

Text Formatting

By default, Markdown offers the ability to display text as bold and/or italic.

To display text in bold, the corresponding text part is written between double stars or underscores.


I also have **bold text**.

I also have __bold text__.

And here is **bold text** in the middle.

To display text in italics, the corresponding text part is written between single stars or underscores.


I also have *italic text*.

I also have _italic text_.

And here is *italic text* in the middle.

Of course, these can also be combined:

To display text in bold and italic, the corresponding text part is written between triple stars or underscores.


I also have ***bold and italic text***.

I also have ___bold and italic text___.

And here is ***bold and italic text*** in the middle.

Blockquotes

To quote text as a block, simply place a “greater than” sign before the line.


> This text is in a blockquote.

If the blockquote is to span multiple lines, the “greater than” sign must be placed at the beginning of each line (including empty lines).


> This text represents the first line in the blockquote.
> 
> And here is the next line.

Quotes can also be nested; in this case, an additional “greater than” sign is added for the next level or indentation.


> This text is in a blockquote.
> 
>> This text is nested.

Lists

Lists are just as simple and are written directly in the text. If the list goes to another level, this is enabled by indentation (4 spaces or 1 tab).

Ordered List

Ordered lists are generated by simply placing the corresponding number followed by a period before the line.


1. First item
2. Second item
3. Third item
    1. first indentation
    2. second indentation
4. Fourth item
Unordered List

Unordered lists are generated by simply placing a hyphen before the line.


- First item
- Second item
- Third item
    - first indentation
    - second indentation
- Fourth item

To display a link, the link text is placed in square brackets, followed by the URL within parentheses.

Ordered lists are generated by simply placing the corresponding number followed by a period before the line.


My favorite search engine is [Swisscows](https://swisscows.com/en).

A title can also be added to the link as a tooltip.


My favorite search engine is [Swisscows](https://swisscows.com/en "The Swiss search engine").

As a shorthand, a URL can also simply be written within angle brackets.


My favorite search engine is <https://swisscows.com/en>.

Extended Syntax

Tables

Tables are defined using vertical bars (|) and hyphens (-). The first line contains the column headers, the second line defines the alignment (optional).

| Left aligned | Centered      | Right aligned |
| :----------- | :-----------: | ------------: |
| Cell 1       | Cell 2        | Cell 3        |
| Cell 4       | Cell 5        | Cell 6        |

Note: The number of hyphens in the separator line is arbitrary; only the : for alignment matters.

Code Blocks

For multi-line code, a code block is created with three backticks (```) or with four spaces per line. Optionally, the language can be specified to activate syntax highlighting.

```python
def hello():
    print("Hello, World!")


---

#### Footnotes

Footnotes are inserted in the text with `[^identifier]` and defined at the end of the file with `[^identifier]:`.

```markdown
Here is a text with a footnote.[^1]

[^1]: This is the explanation for the footnote.

Note: Not all Markdown parsers support footnotes – e.g., Hugo requires goldmark with the option enabled.

IDs for Headings

Headings can be provided with an ID to link to them directly (e.g., for tables of contents or anchor links).

## Heading with ID {#my-id}

[Link to heading](#my-id)

Note: In Hugo, enableInlineShortcodes = true must be activated in the configuration.

Task Lists

Task lists (checklists) are created with - [ ] for unchecked and - [x] for checked items.

- [x] Task completed
- [ ] To do
- [ ] Do later

Note: Often used in GitHub, GitLab, or note apps like Obsidian.

Strikethrough

Strikethrough text is enclosed with double tildes (~~).

This text is ~~strikethrough~~.

Emojis

Emojis can be inserted directly (e.g., 😊) or with shortcodes like :smile: (depending on the parser).

I'm in a good mood today 😊

Note: In Hugo, emojis must be explicitly activated (enableEmoji = true).

Highlighting Text

Some parsers (e.g., Hugo with Goldmark) support highlighting with ==:

This text is ==highlighted==.

Note: Not standardized – does not work everywhere.

Sub-/Superscript

Subscript (H₂O) and superscript (x²) are represented with ~ and ^ respectively – but only in some extensions like Pandoc or Hugo with a special parser.

Water is H~2~O.  
x^2^ is x squared.

Note: Not part of the CommonMark standard – Works, for example, in Hugo with goldmark and the option enabled.

Usage

Markdown does not represent a system of its own but stands purely for an open and freely available syntax. One could compare Markdown to an embeddable scripting language. This is certainly also the reason why so many systems support Markdown and the language is thus so versatile.

Wiki Systems

Wiki systems such as Mediawiki (on which Wikipedia is based), dokuWiki, or integrated wiki functions like those in GitHub or GitLab standardly use Markdown for content management.

Wikis are primarily there to present content, in the Git area documentation for the offered software. Thanks to the simple syntax, these can also be created and managed by non-techies.

Notes

The widely available note apps (or sometimes also called desktop wikis) also rely on Markdown for content management. Often an integrated WYSIWYG editor is provided, but it uses Markdown in the background. There is usually also the possibility to switch to the source text and edit directly there. Examples include Zim, Zettlr, QOwnNotes, and Logseq in the open-source area, or popular variants like Evernote, Obsidian, or Joplin.

Websites

In the area of websites, Markdown appears in two ways. On the one hand, well-known Content Management Systems (such as WordPress and Drupal) often offer plugins/modules to publish content in Markdown. But besides CMS, there are also SSGs, so-called Static Site Generators, such as Hugo or Jekyll. In addition, there are similar systems specialized in technical documentation like MKDocs, Sphinx, or Docusaurus. Here too, all content is created in Markdown and then converted into static websites using a preprocessor, which can then be published.

Presentations/Courses

Besides websites, presentations can also be created with Markdown. However, these are not PowerPoint presentations but are dynamically converted into web elements using preprocessors. Examples include Marp, remarkJS, or Cleaver. Specifically for online courses, the Markdown extension LiaScript is suitable.

Documents

Markdown certainly lacks some functionalities that a word processor like MS Word or LibreOffice Writer can offer, but it is perfectly sufficient for simple documents such as letters.

Conclusion

Advantages

Markdown has a simple and clear syntax and is therefore easy to learn. Markdown documents also have the advantage of being easily readable even in source text. They are thus both machine-readable and human-readable. The latter thanks to the simple and straightforward syntax without overhead. The wide distribution of Markdown and its integration into so many tools also speaks for itself.

Disadvantages

Besides the clear advantages, there is unfortunately also negative news about Markdown.

Markdown is very suitable for articles and notes that are not structured too complexly. If one wants to create more, e.g., large and complex documents, such as entire books, useful functions like a table of contents or the possibility to nest files using “Include” are missing.

Although there is a Markdown standard with CommonMark, the strong distribution has nevertheless led to many “dialects,” as many tools extend the standard syntax with their own commands. As a result, Markdown documents from different systems are not necessarily compatible with each other.

Further Information

Tools for Using Markdown

Desktop Wikis

Text Editors

Static Site Generators

Transformation Tools