doxygen 1.11.0 使用详解（六）——支持 Markdown

Markdown support was introduced in doxygen version 1.8.0. It is a plain text formatting syntax written by John Gruber, with the following underlying design goal:

The design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

In the next section the standard Markdown features are briefly discussed. The reader is referred to the Markdown site for more details.

Some enhancements were made, for instance PHP Markdown Extra, and GitHub flavored Markdown. The section Markdown Extensions discusses the extensions that doxygen supports.

Finally section Doxygen specifics discusses some specifics for doxygen’s implementation of the Markdown standard.

标准 Markdown

Paragraphs

Even before doxygen had Markdown support it supported the same way of paragraph handling as Markdown: to make a paragraph you just separate consecutive lines of text by one or more blank lines.

Headers

Just like Markdown, doxygen supports two types of headers

Level 1 or 2 headers can be made as the follows

This is a level 1 header
========================

This is a level 2 header
------------------------

A header is followed by a line containing only ='s or -'s. Note that the exact amount of ='s or -'s is not important as long as there are at least two.

Alternatively, you can use #'s at the start of a line to make a header. The number of #'s at the start of the line determines the level (up to 6 levels are supported). You can end a header by any number of #'s.

Here is an example:

# This is a level 1 header

### This is level 3 header #######

Block quotes

Block quotes can be created by starting each line with one or more > 's, similar to what is used in text-only emails.

> This is a block quote
> spanning multiple lines

Lists and code blocks (see below) can appear inside a quote block. Quote blocks can also be nested.

Note that doxygen requires that you put a space after the (last) > character to avoid false positives, i.e. when writing

0 if OK\n
>1 if NOK

the second line will not be seen as a block quote.

Lists

Simple bullet lists can be made by starting a line with -, +, or ∗ .

- Item 1
  More text for this item.

- Item 2
  + nested list item.
  + another nested item.
- Item 3

List items can span multiple paragraphs (if each paragraph starts with the proper indentation) and lists can be nested. You can also make a numbered list like so

1. First item.
2. Second item.

Code Blocks

Preformatted verbatim blocks can be created by indenting each line in a block of text by at least 4 extra spaces

This a normal paragraph

    This is a code block

We continue with a normal paragraph again.

Doxygen will remove the mandatory indentation from the code block. Note that you cannot start a code block in the middle of a paragraph (i.e. the line preceding the code block must be empty).

How doxygen handles indentation as this is slightly different than standard Markdown.

Horizontal Rulers

A horizontal ruler will be produced for lines containing at least three or more hyphens, asterisks, or underscores. The line may also include any amount of whitespace.

Examples:

- - -
______

Note that using asterisks in comment blocks does not work.

Note that when using hyphens and the previous line is not empty you have to use at least one whitespace in the sequence of hyphens otherwise it might be seen as a level 2 header.

Emphasis

To emphasize a text fragment you start and end the fragment with an underscore or star. Using two stars or underscores will produce strong emphasis.
Examples:

*single asterisks*
_single underscores_
**double asterisks**
__double underscores__

Strikethrough

To strikethrough a text fragment you start and end the fragment with two tildes.
Examples:

~~double tilde~~

code spans

To indicate a span of code, you should wrap it in backticks ( ` ). Unlike code blocks, code spans appear inline in a paragraph. An example:

Use the `printf()` function.

To show a literal backtick or single quote inside a code span use double backticks, i.e.

To assign the output of command `ls` to `var` use ``var=`ls```.

To assign the text ’text’ to `var` use ``var