Documentation » How to document your code » Markdown markup

dox++ expects documentation to be marked up using the common Markdown format. dox++parse inserts Markdown formatting into the documentation for some commands (such as \‍ref and \‍see).

dox++html uses Python-Markdown to convert the Markdown-formatted text into HTML with a small set of extensions:

• Standard extensions admonition, attr_list, codehilite, fenced_code, and tables to add features.
• Standard extensions md_in_html, sane_lists, and smarty to improve standard formatting.
• Andrew Pinkham’s markdown_subscript_extension, and markdown_superscript_extension to add sub- and superscripts.
• Cris Luengo’s mdx_math_svg to render equations.
• Sascha Cowley’s mdx_headdown for internal purposes.
• Some dox++-specific extensions to allow it to correct internal links and retrieve information from the Markdown parser.

Thus, the documentation text is parsed as John Gruber’s Markdown, with some modifications that improve it and some additions that are useful for code documentation. This page describes the formatting you can use, the links above might be useful for obtain more details.

Basic formatting

Write documentation text as you would write any comment in your code, within the comment sections as described in How to document your code). Newlines are ignored within a paragraph. An empty line indicates a new paragraph.

Format your text using the following syntax:

Note that the \ character can be used to escape any character that might otherwise be interpreted as Markdown formatting:

• \ backslash
• ` backtick
• * asterisk
• _ underscore
• {} curly braces
• [] square brackets
• () parentheses
• # hash mark
• + plus sign
• - minus sign (hyphen)
• . dot
• ! exclamation mark
• $ dollar sign

It is possible to create headers using Markdown formatting, but this will prevent dox++ from linking to them from other documentation blocks and from generating indexes. You should always use \section, \subsection and \subsubsection instead (see Documentation commands).

Insert a line break by adding two spaces at the end of a line. Because many code editors will remove trailing spaces, the command \n will be replaced by two trailing spaces by dox++parse.

Links

Links are inserted using the following syntax: [link text](URL) or [link text](URL "title"), or simply <URL>. URL can be a full URL (https://foo.com), a local resource (pages.html) or #id to reference an ID on the current page.

To link to other parts of the documentation, one would normally use the \‍ref command (see Documentation commands), but it is possible to use a simple Markdown link if one knows the ID of the referenced documentation element. For example, [ns::foo](#ns-foo-int--double-) would be equivalent to \‍ref ns::foo if there existed a function declared as int ns::foo(int, double). Note that dox++parse inserts links like this for each \‍ref and each \‍see command.

Code blocks

There are two ways to format code blocks: using “fences”, and using indentation.

The standard method is to use 4 spaces of indentation:

    // This is code
    foo(bar);

A fenced code block looks like this (fenced_code):

```
// This is code
foo(bar);
```

Both will be rendered in the same way:

We use the codehilite extension to apply syntax highlighting to the code. This uses Pygments to identify the language and apply highlighting. We recommend that you don’t leave the language identification to chance (we see above that identification failed for this short snippet), and specify the language explicitly:

    :::cpp
    // This is code
    foo(bar);

or

```cpp
// This is code
foo(bar);
```

These are rendered as

To identify the language (the “cpp” string in the examples above), use the “short name” as listed in the Pygments documentation. Specifically, use “text” to turn off syntax highlighting:

```text
// This is code
foo(bar);
```

Lists

To create a list, start each list item with a -, + or *. Create numbered lists by starting each line with a number followed by a period. The first number in the list is meaningful, but other list items simply follow it:

* list item 1
* list item 2

7. numbered list item 7
2. numbered list item 8
2. numbered list item 9

will be rendered as

It is important to separate the list items from a preceding paragraph with an empty line.

It is not possible to mix numbered and unnumbered list items in the same list.

Note that if you separate list items with an empty line, list items will be rendered with paragraph separation, as you would expect:

* list item 1

* list item 2

* list item 3

will be rendered as

A list item can contain multiple paragraphs, code blocks, other lists, etc. Simply indent the additional blocks by 4 spaces:

* list item 1
    * sublist item 1.1
    * sublist item 1.2

* list item 2

    Another paragraph in list item 2

* list item 3

        :::cpp
        // A C++ code block in list item 3
        foo(bar);

Note that fenced code blocks cannot be indented, so it is necessary to use the other code block format.

We use the sane_lists extension to improve the standard Markdown list implementation.

Blockquotes

Insert an > as the first character on the first line of a paragraph (or on each line of the paragraph). Block quotes can be nested:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

will be rendered as

It is possible to put other Markdown elements inside a blockquote, including lists, code and links.

Tables

We use the tables extension to allow producing tables. The syntax requires adding pipe characters (|) in between cells, and lines formed by dashes (-) in between the header row and the rest of the table, as follows:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

This is rendered as

It is possible to add a pipe character at the beginning and end of each line as well.

Cell content can contain Markdown formatting.

To align columns add colons (:) at the beginning and/or end of the dashed lines that separate the header from the rest of the column:

Left aligned | Center aligned | Rigt aligned
:----------- |:--------------:| ------------:
Text         | Text           | Text
Other text   | Other text     | Other text

This is rendered as

To span columns, add a colspan property to the cell as described in Attributes. For example,

First Header  | Second Header | Third Header
------------- | ------------- | -------------
This is one long sentence that should span all cells { colspan="3" } ||
Content Cell  | Content Cell  | Content Cell

is rendered as

Boxes

Boxes can be generated using the “admonition” syntax from reST (implemented here through the admonition extension).

!!! note "Box title"
    Paragraph 1

    Paragraph 2

is rendered as a box like this one:

The syntax is !!! type "optional title". Type indicates what the color of the box will be, and what the default title will be. It is always possible to specify a custom title. Using "" for the title will cause there to not be a title at all.

These are the types and the corresponding default title and CSS classes currently implemented:

Note that most of these correspond to Doxygen commands to generate boxes.

It is possible to add additional CSS classes after type: !!! type class1 class2 "optional title"

By default, the class ‘m-note’ is used for admonitions. This class renders a colored box as shown above. If ‘m-block’ is added as an additional class, then that one is used instead of ‘m-note’. For example,

!!! note m-block "Box title"
    Paragraph 1

    Paragraph 2

is rendered as a “block” like this one:

Equations

Equations are rendered as embedded SVG. They are written as LaTeX (with amsmath and amssymb packages loaded). For inline math mode, enclose the LaTeX in:

• dollar signs ($ ... $), or
• LaTeX inline math delimiters \( ... \).

For display math mode, enclose the LaTeX in:

• double dollar signs ($$ ... $$),
• LaTeX display math delimiters \[ ... \], or
• any LaTeX environment that starts math mode (\begin{<env>} ... \end{<env>}, with an appropriate <env>).

The single dollar sign is “smart”, in that it requires there be no spaces on the inside of the signs, between the signs and the LaTeX content. This makes it possible to write things like “I have $3.00 and you have $5.00” without worrying about triggering math mode. For example,

Let's assume that $x$ is positive, then $f(x) = -x$ is negative. But $ x $ is not
rendered in math mode!

is rendered as:

One can always escape the dollar sign if needed: \$x$ is rendered as $x$.

Display equations must have an empty line above and below, and must not contain empty lines.

Given $x$, we can determine

$$ y = e^{-x^2 / \sigma^2} $$

with the constraint that

\begin{align*}
    0 &< x \\
    a &\geq x^2
\end{align*}

is rendered as:

By assigning appropriate attributes (as described in Attributes), it is possible to e.g. change the size of the equations and colorize them:

Given $x$, we can determine $y = e^{-x^2 / \sigma^2}${ .m-text .m-small .m-danger }.

is rendered as:

Images

To inert an image, use the syntax ![Alt text](/path/to/image_file.jpg "Optional title"). The “Alt text” is the text that is rendered instead of the image if the image file cannot be opened (or if image display is disabled in the browser). The “Optional title” is the text shown when hovering over the image. This optional title can be left out: ![Alt text](/path/to/image_file.jpg). Note how the syntax is identical to a link, but with a ! prepended.

Images can appear inside other elements, including links. For example,

[![Manuals](manuals.png "The most ridiculous offender of all is the sudoers man page,
which for 15 years has started with a 'quick guide' to EBNF, a system for defining the
grammar of a language. 'Don't despair', it says, 'the definitions below are annotated.'
")](https://xkcd.com/1343/)

is rendered as

Attributes

One can add CSS attributes to an element by adding the following syntax:

{ #someid .someclass somekey='some value' }

This is implemented through the attr_list extension. someid will be the ID of the element, someclass will be added the list of classes, and the (somekey/some value) pair will be added directly to the element. Note that the spaces inside the braces are required. It is allowed to add a colon right after the opening brace, for compatibility with other Markdown parsers: {: ... }.

To add the CSS attributes to a block element, put them in a line by themselves at the end of the block element:

This is a paragraph.
{ .m-text .m-small }

will be rendered as

To add the attributes to inline elements, add them right after the element, with no space in between:

This is a **paragraph**{ .m-text .m-small }.

will be rendered as

Note that it is not possible to assign attributes to a single word, unless it is wrapped in an element as above.

For code blocks, use the fences syntax and apply the attributes to the opening fences:

``` { .cpp .m-text .m-small }
// This is code
foo(bar);
```

The first class name is interpreted as the language, the remaining ones are CSS classes.

For tables cells, put the attributes after the cell contents, separated with at least one space. Without a space, the attributes would be applied to the element they’re connected to. There is no way to apply the attributes to a table row or the whole table.

Note that there are many limitations to this system, see the attr_list documentation. If you don’t manage to set required attributes this way, use HTML instead.

HTML tags

It is possible to include HTML code into your documentation. Everything enclosed in HTML tags is copied as-is into the generated HTML pages. That is, the text marked up using HTML is not parsed by the Markdown parser:

This is a paragraph **with some bold text**.

<p>This is a paragraph without **any** bolding.</p>

will be rendered as

The md_in_html extension allows the content of HTML blocks to be parsed by Markdown:

This is a paragraph **with some bold text**.

<p markdown="1">This is a paragraph with **some** bolding.</p>

will be rendered as

This can be useful to add a CSS class to a portion of the text, for example:

<div markdown="1" class="m-text m-small">

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

</div>

will create a table with a small font:

Since we can only add attributes to individual cells of a table, not the table itself, this is the only way to add special styling to a whole table. It is also the only way to add special styling to lists.

Examine the CSS style sheets as well as the generated HTML to learn what classes exist. You can modify the default CSS style sheets as well, see Configuring the dox++ tools.