`, ``, ``, etc. —
> must be separated from surrounding content by blank lines,
> and the start and end tags of the block should not be indented
> with tabs or spaces.
Doxygen does not have this requirement, and will also process
Markdown formatting inside such HTML blocks. The only exception is
`
` blocks, which are passed untouched (handy for ASCII art).
Doxygen will not process Markdown formatting inside verbatim or code blocks,
and in other sections that need to be processed without changes
(for instance formulas or inline dot graphs).
\subsection mddox_code_blocks Code Block Indentation
Markdown allows both a single tab or 4 spaces to start a code block.
Since doxygen already replaces tabs by spaces before doing Markdown
processing, the effect will only be same if TAB_SIZE in the configuration file
has been set to 4. When it is set to a higher value spaces will be
present in the code block. A lower value will prevent a single tab to be
interpreted as the start of a code block.
With Markdown any block that is indented by 4 spaces (and 8 spaces
inside lists) is treated as a code block. This indentation amount
is absolute, i.e. counting from the start of the line.
Since doxygen comments can appear at any indentation level
that is required by the programming language, it
uses a relative indentation instead. The amount of
indentation is counted relative to the preceding paragraph.
In case there is no preceding paragraph (i.e. you want to start with a
code block), the minimal amount of indentation of the whole comment block
is used as a reference.
In most cases this difference does not result in different output.
Only if you play with the indentation of paragraphs the difference
is noticeable:
text
text
text
code
In this case Markdown will put the word code in a code block,
whereas doxygen will treat it as normal text, since although the absolute
indentation is 4, the indentation with respect to the previous paragraph
is only 1.
Note that list markers are not counted when determining the
relative indent:
1. Item1
More text for item1
2. Item2
Code block for item2
For Item1 the indentation is 4 (when treating the list marker as whitespace),
so the next paragraph "More text..." starts at the same indentation level
and is therefore not seen as a code block.
\subsection mddox_emph_spans Emphasis and strikethrough limits
Unlike standard Markdown and Github Flavored Markdown doxygen will not touch internal underscores or
stars or tildes, so the following will appear as-is:
a_nice_identifier
Furthermore, a `*` or `_` only starts an emphasis and a `~` only starts a strikethrough if
- it is followed by an alphanumerical character, and
- it is preceded by a space, newline, or one the following characters `<{([,:;`
An emphasis or a strikethrough ends if
- it is not followed by an alphanumerical character, and
- it is not preceded by a space, newline, or one the following characters `({[<=+-\@`
Lastly, the span of the emphasis or strikethrough is limited to a single paragraph.
\subsection mddox_code_spans Code Spans Limits
Note that unlike standard Markdown, doxygen leaves the following untouched.
A `cool' word in a `nice' sentence.
In other words; a single quote cancels the special treatment of a code span
wrapped in a pair of backtick characters. This extra restriction was
added for backward compatibility reasons.
In case you want to have single quotes inside a code span, don't use
one backtick but two backticks around the code span.
\subsection mddox_lists Lists Extensions
With Markdown two lists separated by an empty line are joined together into
a single list which can be rather unexpected and many people consider it to
be a bug. Doxygen, however, will make two separate lists as you would expect.
Example:
- Item1 of list 1
- Item2 of list 1
1. Item1 of list 2
2. Item2 of list 2
With Markdown the actual numbers you use to mark the list have no
effect on the HTML output Markdown produces. I.e. standard Markdown treats the
following as one list with 3 numbered items:
1. Item1
1. Item2
1. Item3
Doxygen however requires that the numbers used as marks are in
strictly ascending order, so the above example would produce 3 lists
with one item. An item with an equal or lower number than
the preceding item, will start a new list. For example:
1. Item1 of list 1
3. Item2 of list 1
2. Item1 of list 2
4. Item2 of list 2
will produce:
1. Item1 of list 1
3. Item2 of list 1
2. Item1 of list 2
4. Item2 of list 2
Historically doxygen has an additional way to create numbered
lists by using `-#` markers:
-# item1
-# item2
\subsection mddox_stars Use of asterisks
Special care has to be taken when using *'s in a comment block
to start a list or make a ruler.
Doxygen will strip off any leading *'s from the comment before doing
Markdown processing. So although the following works fine
@verbatim
/** A list:
* * item1
* * item2
*/
@endverbatim
When you remove the leading *'s doxygen will strip the other stars
as well, making the list disappear!
Rulers created with *'s will not be visible at all. They only work
in Markdown files.
\subsection mddox_limits Limits on markup scope
To avoid that a stray * or _ matches something many paragraphs later,
and shows everything in between with emphasis, doxygen limits the scope
of a * and _ to a single paragraph.
For a code span, between the starting and ending backtick only two
new lines are allowed.
Also for links there are limits; the link text, and link title each can
contain only one new line, the URL may not contain any newlines.
\section markdown_debug Debugging of problems
When doxygen parses the source code it first extracts the comments blocks,
then passes these through the Markdown preprocessor. The output of the
Markdown preprocessing consists of text with \ref cmd_intro "special commands"
and \ref htmlcmds "HTML commands".
A second pass takes the output of the Markdown preprocessor and
converts it into the various output formats.
During Markdown preprocessing no errors are produced. Anything that
does not fit the Markdown syntax is simply passed on as-is. In the subsequent
parsing phase this could lead to errors, which may not always be obvious
as they are based on the intermediate format.
To see the result after Markdown processing you can run doxygen with the
`-d Markdown` option. It will then print each comment block before and
after Markdown processing.
\htmlonly
Go to the next section or return to the
index.
\endhtmlonly
*/