AsciiDoc | Working with adoc Studio

6.1. What is AsciiDoc?

AsciiDoc is a simplified markup language that makes it easier to create texts in various document formats. AsciiDoc files can be converted into HTML, PDF, ePub, and other formats.

Compared to XML-based document formats like DocBook, AsciiDoc offers the advantage of being easy to learn and remaining readable as plain text. More information can be found on Wikipedia.

6.2. Writing Text

Simply write your text as you are accustomed to. You can write everything continuously, like in other programs, which is often referred to as continuous text. Alternatively, you can write the text line by line, placing each sentence on a new line. The formatted text will always look the same.

Create a new paragraph by inserting a blank line between paragraphs.

The Preamble

The first paragraph of a document is called the preamble or sometimes the abstract. This paragraph automatically appears slightly larger than the regular text and is often used as an introduction to the document.

To make other paragraphs larger as well, you can prepend a [.lead].

Example 1. Including an Abstract or Preamble in the Middle of the Text

[.lead]
This paragraph is displayed slightly larger than all other paragraphs. With the “Optima” product style, the paragraph even gets an initial, a large decorative first letter.

Result:

This paragraph is displayed slightly larger than all other paragraphs. With the “Optima” product style, the paragraph even gets an initial, a large decorative first letter.

Avoid this effect in the first paragraph by prepending a [.nolead]. This way, your text starts immediately in the regular font size.

You can find more information about paragraphs on the AsciiDoc website.

6.3. Formatting

As with any markup language, you can format individual words in bold, italic, or other styles. This makes transitioning easier. The editor menu in adoc Studio also provides all important formatting options for quick access with the mouse or keyboard.

The editor menu in adoc Studio provides all important formatting options for quick access with the mouse or keyboard.

Table 6. Direct Formatting in the Editor Menu
Command	*Keyboard Shortc	Markup in Text	Result in Preview
Bold	`⌘`+`B`	bold	bold
Italic	`⌘`+`I`	_italic_	italic
Marked	`⌘`+`#`	#marked#	marked
Fixed Width	`⇧`+`⌘`+`#`	`fixed width`	`fixed width`
Underlined	`⌘`+`U`	[.underline]#underlined#	underlined
Strikethrough	`⇧`+`⌘`+`X`	[.line-through]#strikethrough#	strikethrough
Overlined	`⌥`+`⇧`+`⌘`+`X`	[.overline]#overlined#	overlined
Superscript	`⌥`+`⇧`+`⌘`+`+`	^superscript^	^superscript
Subscript	`⌥`+`⇧`+`⌘`+`-`	~subscript~	_subscript

AsciiDoc can do much more. You can freely combine different formatting options.

**##Super##cali[underline]##fragilist__ic##[red]##expiali__docious##** 😀

Result in preview:

Supercalifragilisticexpialidocious 😀

You can find more information about text formatting on the AsciiDoc website.

6.4. Headings

You can define headings and their levels by using a number of = or # symbols. The latter makes it easier to transition from Markdown to AsciiDoc. However, it’s advisable to get accustomed to the = symbol, as it offers more flexibility.

Here are all the headings in the source text:

= Document Title
== Heading 1
=== Heading 2
==== Heading 3
===== Heading 4
====== Heading 5

Additional Headings

If the six levels plus the document title are not enough, you can set a paragraph title by preceding a line with a .:

.Additional Headings

You can find more information about heading levels on the AsciiDoc website.

Special features of document titles

A document should have a title =. This is usually the first heading in the document.

A subtitle can optionally be added to a document title. This is separated from the title by a :. However, a self-defined string can also be specified as a separator using [separator=STRING] before the title or in the document header as an attribute (:title-separator: STRING).

In the AsciiDoc standard, the subtitle is only output in PDF and not in HTML.
In adoc Studio, this works in both formats.

6.5. Table of Contents

When setting headings, consider including a table of contents. To create a table of contents in adoc Studio, simply create the headings (referred to as Section Title in AsciiDoc).

If you insert :toc: at the beginning of the document, a table of contents will be automatically generated. By default, it includes two levels of headings and is placed above the document. The table of contents is updated automatically.

The :toc: attribute can also include parameters:

left: Positions the table of contents to the left of the text.
right: Positions the table of contents to the right of the text.
preamble: Positions the table of contents after the preamble.
macro: Inserts the table of contents at a desired location using the macro toc::[].
auto: Same as without parameters.

Additionally, the :toclevels: 3 attribute is noteworthy. By specifying a number after the toclevels attribute, you determine how many levels of headings should be displayed in the table of contents. This attribute must be set at the beginning of the document. By default, two levels are shown.

You can find more information about table of contents on the AsciiDoc website.

6.6. Links

There are two types of links:

Hyperlinks to the internet
Cross-references within the document

Hyperlinks to the Internet

The simplest link consists of a written-out address. In the preview, it immediately becomes a clickable URL. Clicking it opens the corresponding page in the browser: https://adoc-studio.app. This works for the main URL schemes:

http
https
ftp
irc
mailto

You can also output links as a macro: https://www.adoc-studio.app[]. You can optionally insert a text between the brackets to be displayed instead of the URL.

https://www.adoc-studio.app[{app-name} website] will be converted to adoc Studio website.

You can find more information about Hyperlinks on the AsciiDoc website.

Cross-references within the Document

To jump to other positions in the same document (standalone document and collection document), insert a cross-reference.

<<Reference>>

The reference corresponds to an automatically generated ID of a heading or an anchor.

Use automatic generated IDs sparingly. If you change a heading that you access via cross-reference, the cross-reference may become invalid.

It is always better to set an anchor before a heading.

[#my_anchor]
== My Heading

Set the cross-reference in the text with:

<<my_anchor>>

In the rendered document, the heading is displayed. Optionally, you can also specify a text to appear instead of the heading:

<<my_anchor, Jump here>>

You can find more information about Cross-references on the AsciiDoc website.

Footnotes

The macro footnote:[] automatically generates footnotes. The footnote text is inserted in square brackets after the macrso:

footnote:[Here is the text of the footnote]

AsciiDoc currently only supports footnotes displayed as endnotes. Therefore, both footnote and endnote are implemented in adoc Studio. To ensure compatibility with existing documents, the attribute :footnotes-position: can be used.

You can find more information about Footnotes on the AsciiDoc website.

Bibliography

The bibliography directory in AsciiDoc is very similar to endnotes. If you do not want to use an external bibliography database, you can create a free but formatted list. Define a section with the class [bibliography] in your document, usually at the end. Add your entries here as an unsorted list with three square brackets ([]) for each entry.

Sample:

[bibliography]
== My Bibliography

* [[[blome-merlin]]] Frank Blome, Antoni Nadir Cherif. Projektmanagement mit Merlin – Das offizielle Handbuch. Carl Hanser Verlag, Munich 2009. ISBN 978-3-446-41927-8.  
* [[[bruening-illenberger-pwpat]]] Brüning, Kai & Illenberger, Frank. Method and system for syncing data structures. US20160055226A1, n.d. https://patents.google.com/patent/US20160055226A1/en.

In the text, you refer to it with a simple link: <<blome-merlin>>

You can find more information about Bibliographie on the AsciiDoc website.

6.7. Images

In the introduction, we briefly discussed images and their paths. Now, we will delve into how to incorporate images into the AsciiDoc text.

You can insert images in two ways: as block images or as inline images.

Block Images

The basic syntax is:

image::image.png[]

The text should be on its own line. The brackets can contain many options, with adoc Studio’s autocomplete menu being helpful, as shown in the example "Embedding an Image in the Text". Three important options are:

width: The width of the image.
align: The alignment of an image.
float: The float property of the image.

Inline Images

The syntax for inline images is very similar to that of block images, with the difference that one colon : is omitted:

image:image.png[]

An image embedded in the flow of the text is inserted as follows:

Please press image:reload.svg[] to reload the page.

Results in:
Please press to reload the page.

Placing images side by side can also be easily achieved with inline images:

hello hello hello

You can find more information about Images on the AsciiDoc website.

6.8. Lists

To create an unordered list, use the following syntax:

A list starts with a *.
- use ** to go one level deeper.
  - And with each additional asterisk,
    
    it goes one level deeper.
  - or
- up again.

If you are familiar with Markdown, you can also use the following syntax for list items:

Markdown lists start with a -.
this works
in adoc Studio too

Ordered lists are just as easy to create:

one
two
three

You also have the option to specify numbers:

one
two
three
Incorrect numbering will be ignored. In this case, it won’t show 7 as in the editor, but rather 4.

In adoc Studio, the numbering is always created automatically.

When lists need to be a bit more complex, follow the same concept as with the unordered list:

Step 1
1. Step 1a
2. Step 1b
Step 2
Step 3

Checklists are also possible:

to do
done
also done
and can be mixed with other entries.

You can find more information about Lists on the AsciiDoc website.

6.9. Block Elements

Block elements, often simply referred to as blocks, are extremely versatile in AsciiDoc. They can be used in a variety of ways and forms. Some common uses include:

Admonitions
Marginal notes
Source code and listings
Equations
Pass-throughs
Quotes

Blocks can be used in various forms:

In a short form, which is usually one line long.
In a paragraph, which can also contain several lines.
With many paragraphs, which can also contain blank lines.

quote completion

After the text "quote", the completion menu opens with the three options shown:

Quote (short form) is displayed in the text as follows:

.Title
"Text"
-- Author,Work

Quote (one paragraph) is displayed in the text as follows:

.Title
[quote,Author,Work]
Text

Quote (multiple paragraphs) is displayed in the text as follows:

.Title
[quote,Author,Work]
____
Text
____

The texts are always formatted as placeholders. When the placeholder is selected and appears blue, you can replace the

. If you do not want to use the placeholder, simply press Enter or Delete.

It’s important to know that blocks—unless they’re like, for example, the Admonitions that are represented on a single line—always have two delimiters: the block start and end. There are many different characters for this purpose, as seen in the following quote example:

"Learning is experience. Everything else is just information."

— Albert Einstein

You can find more information about Text and other blocks on the AsciiDoc website.

Source code with comments

If you are documenting source code or programming in general, the source block provides a flexible block element. The formatting rules of AsciiDoc are overridden between the two lines with ----. You can even optimise this formatting by specifying that the block is source. Optionally, the language can also be specified: [source,c]. For this purpose, we use highlightjs.org as a library, which currently recognises over 190 languages.

The attribute :source-highlighter: highlight.js frequently used in AsciiDoc is implicitly set in adoc Studio v3.

Brian Kernighan: Hello World

#import <standardio.h>

main()
{
   printf ("Hello World\n");
}

You can find more information about Source Blocks on the AsciiDoc website.

If you want to document your source code, AsciiDoc uses the concept of callouts. To do this, simply write a comment character followed by a number in angle brackets at the end of a line (see below). Repeat the numbers in angle brackets below the source block with the desired comment.

line of code 1
line of code 2
line of code 3
line of code 4

1	A callout behind a line comment for C-style languages.
2	A callout behind a line comment for Ruby, Python, Perl, etc.
3	A callout behind a line comment for Clojure.
4	A callout behind a line comment for XML or SGML languages like HTML.

You can find more information about Callouts on the AsciiDoc website.

Admonitions

In particular, this area is worth examining in different styles. We put a lot of effort into the little icons.

Make sure that at the beginning of your document, the attribute :icons: font is set. Otherwise, instead of symbols, only text will appear.

NOTE provides additional information to the reader.

TIP suggests a trick or special tip to the reader.

WARNING alerts the reader to a danger.

CAUTION warns the reader of a pitfall.

IMPORTANT draws the reader’s attention to an important point.

And here’s a practical tip:

You can find more information about Admonitions on the AsciiDoc website.

Equations and Formulas (STEM)

The acronym STEM stands for Science, Technology, Engineering & Math. In (technical) documentation, both aim to output equations and formulas. And that is exactly what AsciiDoc can do.

You can either use the huge range of functions offered by \(\mathrm{\LaTeX}\) in the asciimath or latexmath variant. Enter the expressions in your document as either block or inline elements (example from above: latexmath:[\mathrm{\LaTeX}]).

[latexmath] 
++++ 
Life = \huge \int_ {birth}^{death} \normalsize \frac{happiness}{time} \Delta time
++++

\[Life = \huge \int_ {birth}^{death} \normalsize \frac{happiness}{time} \Delta time\]

Or you can use the simplified form of asciimath:

[asciimath]
++++
sqrt(4) = 2
++++

\{sqrt(4) = 2\}

You can find more information about STEM on the AsciiDoc website.

More about passthrough blocks

When \(\mathrm{\LaTeX}\) is integrated into AsciiDoc, it is done in passthrough blocks. We have translated them as passthrough blocks. Of course, other code – such as SVG – can also be passed through.

:my_colour: red

[subs=attributes]
++++
<svg width="100" height="100">
  <rect width="100" height="100" fill="{my_colour}" />
</svg>
++++

This allowed us to quickly change the different colours.

6.10. Tables

Tables in AsciiDoc are quite versatile, similar to block elements. You can start with simple tabular representations like this:

|===
| One | Two | Three
|===

The result:

One

Two

Three

A second line is added in exactly the same way.

|===
| One | Two | Three
| Four | Five | Six
|===

The result:

One

Two

Three

Four

Five

Six

Add a header row by inserting a blank line after the first row:

|===
| Title 1 | Title 2 | Title 3

| One | Two | Three
| Four | Five | Six
|===

The result:

Title 1	Title 2	Title 3
One	Two	Three
Four	Five	Six

Title 1

Title 2

Title 3

One

Two

Three

Four

Five

Six

Here is a complex example, as found on the AsciiDoc website:

|===
| Column 1 | Column 2

2+>m|This content spans two columns (2*) and is aligned to the right edge of the cell (>).

The text is rendered in a monospace font (`m`).

.3+^.>s|This cell spans 3 rows (`3+`).
The content is centered horizontally (`+^+`), aligned to the bottom edge of the cell (`.>`), and rendered in strong formatting (`s`).
e|This content is rendered in italics (`e`).

m|This content is rendered in a monospace font (m).

s|This *content* is bold (`s`), except for the word _content_.
|===

The result:

Column 1 Column 2

Column 1	Column 2
`This content spans two columns (2*) and is aligned to the right edge of the cell (>).` `The text is rendered in a monospace font (m).`
This cell spans 3 rows (`3+`). The content is centered horizontally (`^`), aligned to the bottom edge of the cell (`.>`), and rendered in strong formatting (`s`).	This content is rendered in italics (`e`).
`This content is rendered in a monospace font (m).`
This content** is bold (`s`), except for the word content.**

This content spans two columns (2*) and is aligned to the right edge of the cell (>).

The text is rendered in a monospace font (m).

This cell spans 3 rows (3+). The content is centered horizontally (^), aligned to the bottom edge of the cell (.>), and rendered in strong formatting (s).

This content is rendered in italics (e).

This content is rendered in a monospace font (m).

This content is bold (s), except for the word content.

You can find more information about Tables on the AsciiDoc website.

6.11. User Interface

In technical documentation, descriptions of the user interface (GUI) or simply the UI (User Interface) are commonplace. There are three particularly important areas:

Keyboard Shortcuts

With the kbd:[] macro, you can create keyboard shortcuts in your manual. For example, ⌘+S quickly saves the document.

A special feature of the kbd:[] macros is shown in the use of the arrow keys in this document.

Menus

The menu:[] macro helps in describing menu entries. For example, you start the product export via File Export Products …

Buttons

The btn:[] macro is responsible for displaying all types of buttons. For example, you have a OK button available.

You can find more information about UI Macros on the AsciiDoc website.

6.12. Comments

Especially when viewing this document as source code in adoc Studio, it’s worth looking at the editor. After all, comments are only displayed here.

At the beginning of a line, you can mark the following text as a comment using //.

// This text is a comment and will not be displayed in the document.

You can define entire sections as comments by using //// at the beginning and end of the block:

Why should you insert comments that do not appear in the final document? Here are some reasons:

// TODO:: Pending tasks such as optimizations, improvements, and corrections.
Formatting instructions for the text.
Justifications and explanations for specific content.
Internal version notes about changes and revisions.
Notes for editors.
Additional contextual information that is helpful for understanding the source text in the editor but not needed in the final document.

You can find more information about Comments on the AsciiDoc website.

6.13. Attributes

Using attributes can elevate your documentation to a whole new level.

The term "attribute" is used in adoc Studio in various ways. Essentially, they allow you to:

Define values for later use in the text
Customize settings in the document

Using Attributes as Variables

In many cases, certain words, URLs, and other information repeat throughout the text. Some terms change depending on the version of the document, while others, such as URLs, are so long that it’s advisable to enter them only once to avoid errors.

To reuse attributes anywhere in the document, define them as follows:

Example 2. Using an attribute as a variable

Definition

:app-version: 1.2.3.4

Input

This document is based on version {app-version}.

Output

This document is based on version 1.2.3.4.

This already opens up extensive possibilities. Every time the name adoc Studio appears in this documentation, the attribute {app-name} is used. Here are some other attributes used in this document:

:app-name: adoc Studio
:lang: en
:url-website: https://www.adoc-studio.app
:url-roadmap: https://adoc-studio.canny.io 
:url-styles: https://styles.adoc-studio.app 
:url-forum: https://forum.adoc-studio.app

In adoc Studio, there are a number of standard attributes that are already prepared, as they are needed in (almost) every document. However, these must be entered at the beginning of your document in the document header:

Author information (:author:)
Version attributes (:revnumber:, :revdate:, and :revmark:)
Metadata (:description:, :keywords:)

An example for this document might look like this:

:author: Frank Blome
:revnumber: 1.0
:revdate: {docdate}
:description: This document introduces you to working with {app-name}.
:keyword: {app-name}, AsciiDoc, technical documentation, manuals, and more

You can abbreviate a standard title as follows:

= The Manual for {app-name}
Frank Blome <frank@projectwizards.net>
1.0, {docdate}

In this case, the information for :author:, :email:, :revnumber:, and :revdate: is automatically retrieved from the context after the document title (=) and can later be used as attributes with {}.`.

Attributes for Document Settings

Another purpose of attributes is to control the settings of your document. Each document contains various name-value pairs referred to as document attributes.

These attributes allow you to configure the backend processor and specify document metadata. You can use pre-existing built-in attributes or define your own.

Always set document attributes at the beginning of a line!

Built-in Attributes

Built-in attributes actively support the configuration and control of the document. Their effect often unfolds only when they are placed in a line at the beginning of the document.

Attributes can:

Provide access to document information.
Define document metadata.
Enable or disable built-in functions
Configure built-in functions
Specify the location of assets, such as images.
Store content for reuse in a document.

Examples

You set attributes either by just the plain entry: :beta:.
You set attributes with additions: :beta-version: 23.
You set attributes with an exclamation mark to disable or negate them: :!beta: or :beta!:.

In adoc Studio, accessing all built-in attributes is extremely user-friendly. Simply press the ESC key at the beginning of a line and select Attributes from the text completion menu. You will then find all available built-in attributes listed.

textmenu textmenuattributes

You can find more information about built-in attributes on the AsciiDoc website.

Deviations from AsciiDoc

Even though adoc Studio adheres to the AsciiDoc standard, there are a few small but subtle differences where we have gone our own way in development. In most cases, we wanted to fix errors in AsciiDoc rather than copy them. And in some cases, we have extended features to make them easier or more comprehensive to use.

These are discussed in detail in the notes on AsciiDoc compatibility.

Custom Attributes

Custom attributes are those defined by the author and are not reserved by the AsciiDoc language or an extension. They are usually used to replace text. With these attributes, you can define named and reusable content. Instead of repeating text throughout the document, such as a product name, this text can be set in an attribute and referenced by its name in the document. This method helps you make the document more efficient and apply the "Don’t Repeat Yourself" (DRY) principle.

When naming attributes, please note that only lowercase letters and underscores may be used. Everything else will be ignored.

An example used regularly in the documentation for mp 32 Merlin Project:

:mp-mpe-features: https://www.projectwizards.net/merlin-project/features
:not-in-mpe: CAUTION: This feature is not included in Merlin Project Express.  Please compare your requirements with the {mp-mpe-features}[feature comparison] table.

Becomes:

This feature is not included in Merlin Project Express. Please compare your requirements with the feature comparison table.

This method saves a lot of work because you don’t have to copy and paste the text repeatedly. If you need to change the text, a single adjustment at one place in the document is enough.

You can find more information about document attributes on the AsciiDoc website.

6.14. Conditional Statements

Conditional statements are control structures in programming where a section of code is executed only under certain conditions. Similarly, this can be applied to texts in adoc Studio. Here are the conditional statements you can use:

ifdef: The content is included only if the specified attribute exists.
ifndef: The content is included only if the specified attribute does not exist.
ifeval: The content is included only if the expression within the square brackets of the ifeval directive evaluates to true.

When the processor encounters one of these conditions, it evaluates the specified condition. This is based on the presence or value of one or more document attributes. If the condition evaluates to true, the enclosed lines are included; otherwise, they are skipped.

You can find more information about conditional statements on the AsciiDoc website.

6.15. Includes

One of the core features of AsciiDoc is managing split files instead of creating a single endlessly long file. You divide the text into many individual files and then assemble them according to certain rules.

In adoc Studio, a specific concept was already introduced in the section The Project Navigator.

For instance, if you are collaborating with authors who cannot use adoc Studio, using the include command is advisable. This way, chapters available in the AsciiDoc format can be included sequentially.

Medium wurde nicht gefunden.
Medium wurde nicht gefunden.
Medium wurde nicht gefunden.

Includes in adoc Studio

Within adoc Studio, using the include command can be beneficial. Suppose you face the challenge that not all features of your product can be documented at once. In such cases, you need a placeholder.

For this project, a placeholder named comingSoon.adoc is defined in the file list. To ensure this file is not included in the compiled document, the corresponding checkbox is unchecked in the file information. More details can be found here.

Whenever a feature is not yet described, place the following text:

:the_feature: important features
include::comingSoon.adoc[]

This will be output as follows:

The important features are not yet described. A detailed documentation will be available as soon as possible.

The trick lies in the content of the comingSoon.adoc file:

ifdef::the_feature[]

CAUTION: The _{the_feature}_ are not yet described. A detailed documentation will be available as soon as possible.

:!the_feature: 

endif::[]

When you include the file using the include command, a text is first assigned to the the_feature attribute. In this case, "important features".
Then, the comingSoon.adoc file is included at the current position.
Next, it checks whether the attribute contains a text.
If it does, a warning is issued.
After that, the attribute is cleared.

You can find more information about Includes on the AsciiDoc website.

6.16. Docinfo

Docinfo is a feature of AsciiDoc that allows you to insert custom content into the head, header, or footer of the output document. This custom content is read from files known as docinfo files by the converter. Docinfo files are intended as convenient way to supplement the output produced by a converter. Examples include injecting auxiliary metadata, stylesheets, and scripting logic not already provided by the converter.

You can find more information about Docinfo on the AsciiDoc website.

6. AsciiDoc

6.1. What is AsciiDoc?

6.2. Writing Text

The Preamble

6.3. Formatting

6.4. Headings

Special features of document titles

6.5. Table of Contents

6.6. Links

Hyperlinks to the Internet

Cross-references within the Document

Footnotes

Bibliography

6.7. Images

Block Images

Inline Images

6.8. Lists

6.9. Block Elements

Source code with comments

Admonitions

Equations and Formulas (STEM)

More about passthrough blocks

6.10. Tables

6.11. User Interface

6.12. Comments

6.13. Attributes

Using Attributes as Variables

Attributes for Document Settings

Built-in Attributes

Deviations from AsciiDoc

Custom Attributes

6.14. Conditional Statements

6.15. Includes

6.16. Docinfo