AsciiDoc

Metadata and attributes

Each page can define various variables (attributes) that you can use to affect, for example, the page title, appearance, and so on.

A sample page may look as follows:

= Annotation 1
:toc: 2
:imagesdir: ./media/ 3
:course-guarantor: doc. Kevin Flynn 4

The course covers the fundamental principles of life.
The course guarantor is link:{course-guarantor}[]. 5

For more information, see the official documentation.

Headings

Headings are an integral part of the page. Among other things, they are used to automatically generate content. More on this is shown in Metadata and attributes.

You can assign any ID to headings. This will then appear in the URL when you click on the heading. It also makes it easy to link to it; see the example.

[#video]
== Lecture recordings

On this page you will find a list of lecture recordings.

All lectures within this course are <<+++video+++, recorded>>.

For more information, see the official documentation.

Text formatting

A part of a word, not the whole word (see the following example), can be formatted using the so-called unconstrained formatting pair.

To highlight only part of a word, you need to use two asterisks instead of one.

See the official documentation for more.

Links

Inside the square brackets at the end of a link, you can specify custom text under which the link will be displayed.

For more information, see the official documentation.

Images

Store images in the designated folder[1]. Otherwise, the image would be automatically added as a separate page in the side navigation.

Optional[2] – In the page header, specify the folder in which AsciiDoc should look for images. Do this using :imagesdir: <relative path to the folder>. See point 3 of the Metadata and attributes section.

Examples of inserting images:

.This is a caption that will be displayed together with the image
image::image.jpg[Alternative text]

Other attributes that can be used to modify image rendering include:

For more information, see the official documentation.

Files

Lists

To force separation of adjacent lists, use //-.

* This is an unordered list
* This is its second item
** Another list level
* Another item

. This is an ordered list
. This is its second item
.. Another list level
. Another item

[loweralpha, start=5]
. This is an ordered list
. It is numbered with lowercase letters
** Second list level
** It is unordered
. Another item

* This is an item.
+
With multiple lines.

* This is its second item

For more information, see the official documentation.

Code

Code can be written on a single line – for example, `text` will be rendered as text.

For multi-line code, see the following example:

[source, c]
----
airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));

long int j = 0;
for (long int i = 0; i < n; i++)
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j++;
----

It will be rendered as:

airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));

long int j = 0;
for (long int i = 0; i < n; i++)
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j++;

The [source, <language>] line handles syntax highlighting. Any language can be substituted for <language>. Omitting this line will disable syntax highlighting for the code.

For more information, see the official documentation.

[source, c]
-----
airplane_t *strip = NULL; // <1>
strip = (airplane_t *) malloc(n * sizeof(*strip)); // <1>

long int j = 0;
for (long int i = 0; i < n; i) // <2>
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j;
-----

<1> Declaration of variables.
<2> Loop that runs exactly n times.

airplane_t *strip = NULL; 1
strip = (airplane_t *) malloc(n * sizeof(*strip)); 1

long int j = 0;
for (long int i = 0; i < n; i++) 2
    if (abs(P[i].x - midPoint.x) < d)
        strip[j] = P[i], j++;

Collapsible blocks

The following code can be used to create collapsible blocks.

[%collapsible]
.Solution to homework 1
====
Here is the solution to the homework.
====

It will be rendered as:

Comments

Comments are not part of the final page.

// Single-line comment

You can also write multi-line comments.

////
Comment that has

multiple lines.
////

For more information, see the official documentation.

Tabbed navigation

The following code can be used to create a tabbed navigation bar.

[tabbed] 1
Arch Linux:: 2
+
The first line of the Arch Linux tab.
+
The second line.
3
Debian / Ubuntu::
+
The first line of the Debian / Ubuntu tab.
+
The second line.

Fedora::
+
The first line of the Fedora tab, which also contains source code:
+
[source, c]
----
airplane_t *strip = NULL;
strip = (airplane_t *) malloc(n * sizeof(*strip));
----

openSUSE::
+
The first line of the openSUSE tab.
+
The second line.

It will be rendered as:

. Fill in the following fields:
+
[tabbed]
Incoming mail server::
* Protocol: `IMAP`
* Server: `{mail-imap}`
* Port: `{mail-port-imap}`
* Connection security: `SSL/TLS`
* Authentication method: `OAuth2`

Outgoing mail server::
* Protocol: `SMTP`
* Server: `{mail-smtp}`
* Port: `{mail-port-smtp}`
* Connection security: `STARTTLS`
* Authentication method: `OAuth2`

+
If the authentication method menu does not include `OAuth2`, first click btn:[Retest].
Then continue with btn:[Done].

. In the pop-up window, log in with `<username>@**cvut.cz**` and xref:../../accounts/index.adoc[the CTU password].

Blocks (admonitions)

Below is an example of a single-line block. Instead of NOTE, you can substitute any block type, see the names above.

Blocks can also be multi-line; instead of IMPORTANT, you can substitute any block type, see the names above.

Likewise, a block can have its own title.

For more information, see the official documentation.

Collision with page contents

If an admonition block is used at the top of the page together with the page contents (ToC), a collision may occur (see the following image).

In such a case, the collision can be disabled using the noclear class.

[.noclear]
TIP: Enter which grading system you use (for example, https://grades.fit.cvut.cz[Grades/Classification]).

Footnotes

A footnote can be written using footnote:[Footnote text.] at the desired place in the text. AsciiDoc handles the numbering automatically.

The result will look as follows.[7]

For more information, see the official documentation.

Tables

AsciiDoc provides comprehensive support for creating tables, including cell merging, different alignment options, or loading data from a CSV file.[8]

Example of a simple table without formatting:

The following can be modified in tables:

For more information, see the official documentation.

Mathematical expressions

To use mathematical expressions and formulas entered using La/TeX syntax on the page, we must correctly set the document’s stem attribute to latexmath. This can be easily done as follows:

= Page with mathematical expressions 1
:stem: latexmath 2

Courses use KaTeX to render mathematical expressions in the final output. This is a tool that allows mathematical expressions written in La/TeX syntax to be displayed on the web. It was originally created for Khan Academy. KaTeX does not support absolutely all mathematical features and packages known from La/TeX or AMSTeX, but its capabilities are fully sufficient for most users and problems. The exact list of supported macros and environments is given in the KaTeX documentation.

For example, we might want to discuss the properties of the function stem:[f(x) = \sin(x)]
or talk about the sequence stem:[(n+1)_{n=1}^\infty].

stem:[\sqrt[3\]{2}] 1

[stem] 1
++++ 2
  \sum_{k=1}^\infty k = -\frac{1}{12}\,, 3
++++ 4

[stem]
++++
\begin{aligned} 1
  2x + 3y &= 4, \\ 2
  5x + 6y &= 7.
\end{aligned}
++++

[stem]
++++
\begin{gathered} 1
  (x + y)^n = \sum_{k=0}^n \dbinom{n}{k} x^{n-k} y^k = \\ 2
  = \dbinom{n}{0} x^n + \dbinom{n}{1} x^{n-1} y + \dbinom{n}{2} x^{n-2} y^2
  + \cdots + \dbinom{n}{n-1} x y^{n-1} + \dbinom{n}{n} y^n\,.
\end{gathered}
++++

[#eq1]
[stem]
++++
  \tag{1}
  \int_{a}^{b} f(x)\,\mathrm{d}x = \big[ F(x) \big]_{a}^{b}\,.
++++

[stem]
++++
  \underbrace{ 1
  \begin{pmatrix}
    a & b \\
    c & d
  \end{pmatrix}^{-1}
  }_{\triangle}
  =
  \frac{1}{\color{red}ad-bc} \begin{pmatrix} 2
    d  & -b \\
    -c & a
  \end{pmatrix}.
++++

.Fundamental Theorem of Algebra 1
[#Veta1] 2
____ 3
Every polynomial of degree stem:[n \in \mathbb{N}] has at most stem:[n] complex roots.
____

Diagrams

The course-pages generator integrates the Kroki diagram generator. This allows it to render many different kinds of diagrams, such as WaveDrom, Graphviz, and many others.

Just as with source code, the diagram code must be placed in a block, and the diagram type must be placed in square brackets above the block.

Example of rendering a graph using Graphviz:

[graphviz]
....
digraph G {
    "Node 1" -> "Node 2";
    "Node 2" -> "Node 3";
}
....

Result:

Example of rendering a graph using WaveDrom:

[wavedrom]
....
{
  signal: [
    { name: 'Clock', wave: 'P......' },
    { name: 'Data',  wave: 'x.345x', data: ['D0', 'D1', 'D2', 'D3'] },
    { name: 'Enable', wave: '0.1..0' }
  ]
}
....

Result: