Open source fans and official API libraries often use Doxygen to add code comments, which can generate documents out of code. That means, users only need to maintain one code file, and the situation where documents don't match the code at all can be effectively avoided.

The shortcoming of Doxygen is also very apparent though. The comment syntax is too complex to understand, thus is not suitable for professional documents.

For many times, we wished to generate documents both good-looking and easy to understand for common people without complex syntax. Is it possible?

Yes! We have Markdown! Users can focus on the content of the documents and don't need to worry about the form, which the Markdown editor will take care of.

Here is an official description of Markdown:

PHILOSOPHY

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. 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 — including Setext, atx, Textile, reStructuredText, Grutatext, and EtText — the single biggest source of inspiration for Markdown's syntax is the format of plain text email.

To this end, Markdown's syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like emphasis. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you've ever used email.

Looks great! Right? In fact, many documents in github are written in Markdown syntax.

Since Markdown is so useful, it would be even better if it can be used in Doxygen, so we can not only comment the code conveniently but also write a large professional document without code. We can also use other Markdown editor instead of Doxygen.

Let's see how to use Markdown in Doxygen then.

Note: Please make sure you are familiar with basic operation and frequently-used syntax of Doxygen before you read further. If you have never known anything about Doxygen before, please read the Getting started guide of Doxygen first.

THE FIRST TRY

Create a new folder named, let's say, Markdown, and create a new file named readme.md in the folder, with following content:

Description {#mainpage}
=======================

## INTRODUCTION

This is the firt Markdown file we write.

## What to do next?

Let's learn in detail the Markdown syntax and the cautions in Doxygen introduction.

Configure the file with Doxygen settings by default, compile it in current directory, and open the corresponding HTML file, as shown in the figure below:

This is how we create the first Markdown file in doxygen:

1. Create a new *.md file
2. Write text obedient to Markdown syntax in it
3. Compile and output an HTML file

It's easy, isn't it?

Note: Please make sure that the encoding format of the readme.md file is UTF-8

STANDARD MARKDOWN

Now that we know how to use Markdown in Doxygen, let's learn in detail the basic syntax of Markdown.

1. Headers

Markdown supports two types of headers, Setext-type and Atx-type.

Setext-type uses a line under the header containing only ='s (for level 1 header) or -'s (for level 2 header). For example:

Example 1

This is an H1
=============

This is an H2
-------------

Note that the exact amount of ='s or -'s is not important.

Atx-type use one to six #'s at the start of a line to make a header from level 1 to level 6. For example:

Example 2

# This is an H1

## This is an H2

###### This is an H6

You can end a header by any number of #'s, just to make it look good.

Example 3

# This is an H1 #

## This is an H2 ##

### This is an H3 ######

Will produce

Example 1

This is an H1

This is an H2

Example 2

This is an H1

This is an H2

This is an H6

Example 3

This is an H1

This is an H2

This is an H3

Cautions

1. For the exact amount of ='s or -'s under Setext-type headers, standard Markdown requires at least one, while Doxygen requires at least two

2. Doxygen has a special requirement for level 1 headers, please refer to Markdown Extensions for the details.

2. Paragraphs and Line Breaks

A Markdown paragraph consists of one or more consecutive lines of text, wrapped by at least one blank line.

Note: A line containing nothing but spaces, tabs or carriage returns is considered blank.

There are two ways for a line break:

1) Insert <br/> in any place of the paragraph 2) Insert more than two spaces at the end of the line

For example

Original Markdown text

This is a paragraph

This is also a paragraph

This is a paragraph
This is a sentence among the paragraph

This is a paragraph line-broken via spaces  
This is a paragraph line-broken via spaces  
This is a paragraph line-broken via spaces  
This is a paragraph line-broken via spaces  

This is a paragraph with no line breaks,
This is a paragraph with no line breaks,
This is a paragraph with no line breaks,
This is a paragraph with no line breaks,
This is a paragraph with no line breaks

Output HTML

This is a paragraph

This is also a paragraph

This is a paragraph This is a sentence among the paragraph

This is a paragraph line-broken via spaces
This is a paragraph line-broken via spaces
This is a paragraph line-broken via spaces
This is a paragraph line-broken via spaces

This is a paragraph with no line breaks, This is a paragraph with no line breaks, This is a paragraph with no line breaks, This is a paragraph with no line breaks, This is a paragraph with no line breaks

Cautions

1. Common paragraphs should not be indented by spaces or tabs, or it will be treated as "pre-formatted text" by compiler.

2. Doxygen doesn't support breaking a line by ending a line with two or more spaces. When you do need to break a line in the middle of a paragraph, you can insert a <br/>.

3. Blockquotes

Markdown uses email-style > characters for blockquoting. If you're familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a > before every line:

Example 1
> A Thai satellite has detected some 300 objects in an area of 
> the southern Indian Ocean being searched for missing Malaysia 
> Airlines flight MH370.
> 
> The image was taken by the Thaichote satellite on 24 March, 
> a day after images from a French satellite purported to show 
> 122 floating objects.
> 
> Flight MH370 disappeared on 8 March with 239 people on board. 
> No debris has been recovered from the ocean so far.

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph:

Example 2
> A Thai satellite has detected some 300 objects in an area of 
the southern Indian Ocean being searched for missing Malaysia 
Airlines flight MH370.

> The image was taken by the Thaichote satellite on 24 March, 
a day after images from a French satellite purported to show 
122 floating objects.

> Flight MH370 disappeared on 8 March with 239 people on board. 
No debris has been recovered from the ocean so far.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of >:

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

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:

Example 4
> ## This is a header
> 
> 1.   This is first item
> 2.   This is second item
> 
> Here, Show code snippet for you:
>     return shell_exec("echo $input | $markdown_script");

Will produce

Example 1

A Thai satellite has detected some 300 objects in an area of the southern Indian Ocean being searched for missing Malaysia Airlines flight MH370.

The image was taken by the Thaichote satellite on 24 March, a day after images from a French satellite purported to show 122 floating objects.

Flight MH370 disappeared on 8 March with 239 people on board. No debris has been recovered from the ocean so far.

Example 2

A Thai satellite has detected some 300 objects in an area of the southern Indian Ocean being searched for missing Malaysia Airlines flight MH370.

The image was taken by the Thaichote satellite on 24 March, a day after images from a French satellite purported to show 122 floating objects.

Flight MH370 disappeared on 8 March with 239 people on board. No debris has been recovered from the ocean so far.

Example 3

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

Example 4

This is a header

1. This is first item
2. This is second item

Here, Show code snippet for you:

return shell_exec("echo $input | $markdown_script");

Cautions

1. Doxygen doesn't support omitting > as in Example 2, you need to make sure that each line of the blockquote is started with a >.

2. In Doxygen, if you want to insert a Markdown code block in a blockquote, you need to guarantee at least one blank line between the blocks. The code below won't take effect in Doxygen due to lack of blank lines:

> Here, Show code snippet for you:
>     return shell_exec("echo $input | $markdown_script");

4. Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks (*), pluses (+), and hyphens (-) — interchangeably — as list markers:

Example 1

*   Red
*   Green
*   Blue
OR
+   Red
+   Green
+   Blue    
OR
-   Red
-   Green
-   Blue

Ordered lists use numbers followed by periods:

Example 2

1.  Bird
2.  McHale
3.  Parish

It's important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

If you instead wrote the list in Markdown like this:

Example 3

1.  Bird
1.  McHale
1.  Parish

or even:

Example 4

3. Bird
1. McHale
8. Parish

you'd get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don't have to.

If you do use lazy list numbering, however, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists at an arbitrary number.

List markers typically start at the left margin, but may be indented by up to three spaces. List markers must be followed by one or more spaces or a tab.

To make lists look nice, you can wrap items with hanging indents:

Example 5

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    Suspendisse id sem consectetuer libero luctus adipiscing.

But if you want to be lazy, you don't have to:

Example 6

*   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
*   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.

If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output. For example, this input:

Example 7

*   Bird
*   Magic

will turn into:

<ul>
<li>Bird</li>
<li>Magic</li>
</ul>

But this:

Example 8

*   Bird

*   Magic

will turn into:

<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab:

Example 9

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:

Example 10

*   This is a list item with two paragraphs.

    This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit.

*   Another item in the same list.

To put a blockquote within a list item, the blockquote's > delimiters need to be indented:

Example 11

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

To put a code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs:

Example 12

*   A list item with a code block:

        extern int main(void);

It's worth noting that it's possible to trigger an ordered list by accident, by writing something like this:

1986. What a great season.

In other words, a number-period-space sequence at the beginning of a line. To avoid this, you can backslash-escape the period:

1986\. What a great season.

Will produce

Example 1

• Red
• Green
• Blue

Example 2, 3, and 4

1. Bird
2. McHale
3. Parish

Example 5 and 6

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
• Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Example 7

• Bird
• Magic

Example 8

• Bird

• Magic

Example 9

1. This is a list item with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

   Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

2. Suspendisse id sem consectetuer libero luctus adipiscing.

Example 11

• A list item with a blockquote:

  This is a blockquote inside a list item.

Example 12

• A list item with a code block:

  extern int main(void);
  

Cautions

In Doxygen, things are different:

• Doxygen will treat two list items separated by a blank line as one list item
• For an ordered list, Doxygen will handle it in strict accordance with an ascending order. Any same sequence or descending order will start a new ordered list.
• The actual numbers you use to mark the list have no effect on the HTML output Markdown produces.

5. CODE BLOCKS

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both <pre> and <code> tags.

To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

This is a normal paragraph:

    This is a code block.

Markdown will generate:

<p>This is a normal paragraph:</p>

<pre><code>This is a code block.
</code></pre>

One level of indentation — 4 spaces or 1 tab — is removed from each line of the code block. For example, this:

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

will turn into:

<p>Here is an example of AppleScript:</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (&) and angle brackets (< and >) are automatically converted into HTML entities. This makes it very easy to include example HTML source code using Markdown — just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets. For example, this:

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

will turn into:

<pre><code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>

Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it's also easy to use Markdown to write about Markdown's own syntax.

Cautions

"To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab."

Note 2 points:

1. Take care when using tabs

Doxygen and some Markdown editor will replace a tab with a certain number of spaces before processing it, at that time only spaces stand for an indentation.

In this case, it's really important how many spaces a tab equals to (TAB = N Space). When N equals 4, everything is normal, and the result matches the expectation; When N is more than 4, the editor will remove 4 spaces, and handle the rest spaces as part of the code; When N is less than 4, the editor will remove all the spaces first and handle the rest part as common text.

Note: You can set the number of spaces in a tab by modifying the value of TAB_SIZE in Doxygen project configuration file.

# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen
# uses this value to replace tabs by spaces in code fragments.
# Minimum value: 1, maximum value: 16, default value: 4.

TAB_SIZE               = 4

Suggestion: Don't use TAB in your document, and set a tab as 4 spaces in your editor, in this way many potential problems can be avoided.

2. What is the indentation of 4 spaces relative to?

The standard Markdown syntax only states that a code block should be indented by 4 spaces, but does not say what the indentation is relative to. It's relative to the leftmost row of the document by default. We call the indentation relative to the leftmost row, in spaces, as absolute offset.

Generally the threshold value of absolute offset is 4. If the absolute offset of a paragraph is no more than 4, it will be handled as a common paragragh. When the absolute offset is over 8, check first if the paragraph is in a list. If yes, treat the part as a code block in a list, if not, treat the part as a common code block.

We can see that the absolute offset plays a very important role in standard Markdown editors.

Is it the same in Doxygen? No. Because Doxygen handles not only pure Markdown text, but also some Markdown text inserted in code comment, and comment can has any indentation, which can lead to a problem if there is no special treatment. Therefore, Doxygen uses relative offset instead of absolute offset, re:

The offset of current paragraph is relative to last paragraph

Note: The relative offset in a list does not include the list symbols.

Generally the Doxygen method won't cause any mistake to the text written in Markdown, unless you write it as below:

text     indented by 0 space relative to the last paragraph; indented by 0 space relative to the leftmost row.

 text    indented by 1 space relative to the last paragraph; indented by 1 space relative to the leftmost row.

  text   indented by 1 space relative to the last paragraph; indented by 2 spaces relative to the leftmost row.

    code indented by 2 spaces relative to the last paragraph; indented by 4 spaces relative to the leftmost row.

In this condition, Markdown editors will treat the code line as code while Doxygen won't, because there is only 2 spaces' relative indentation.

6. HORIZONTAL RULES

You can produce a horizontal rule tag by placing three or more hyphens, asterisks, or underscores on a line by themselves.

Example 1

***

---
___

Spaces are allowed to insert between hyphens or asterisks like this:

Example 2

*  *  *
-  -  -    

Will produce

Example 1:Below are 3 horizontal rule tags.

Example 2:Below are 2 horizontal rule tags.

[Caution]

1. Standard Markdown Editors support all above standards, but Doxygen requires a horizontal rule tag to be in a single line wrapped by blank lines. Other editors also have this requirement.

Therefore, we recommend you to use the horizontal rule tag in a single line and wrap it with blank lines, like this:

This is a paragraph

***

This is also a paragraph, followed by 3 horizontal rule tags

---

***

___

instead of this (please pay special attention to the last 3 horizontal rule tags):

This is a paragraph

***

This is also a paragraph, followed by 3 horizontal rule tags

---
***
___

2. For Doxygen, horizontal rule tags will only work in Markdown files. They won't work in code comments.

For example:

/** A list:
 *  * item1
 *  *******
 *  * item2
 */

There will be no horizontal rule tag between item1 and item2

7. LINKS

Markdown supports two style of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular parentheses immediately after the link text's closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

Example 1

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Will produce:

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

If you're referring to a local resource on the same server, you can use relative paths:

See my [About](/about/) page for details.   

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

Example 2

This is [an example][id] reference-style link.

You can optionally use a space to separate the sets of brackets:

This is [an example] [id] reference-style link.

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/  "Optional Title Here"

That is:

• Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
• followed by a colon;
• followed by one or more spaces (or tabs);
• followed by the URL for the link;
• optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)

NOTE: There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.

The link URL may, optionally, be surrounded by angle brackets:

[id]: <http://example.com/>  "Optional Title Here"

You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.

Link definition names may consist of letters, numbers, spaces, and punctuation — but they are not case sensitive. E.g. these two links:

[link text][a]
[link text][A]

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — e.g., to link the word "Google" to the google.com web site, you could simply write:

[Google][]

And then define the link:

[Google]: http://google.com/

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

Visit [Daring Fireball][] for more information.

And then define the link:

[Daring Fireball]: http://daringfireball.net/

Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they're used, but if you want, you can put them all at the end of your document, sort of like footnotes.

Here's an example of reference links in action:

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"

Using the implicit link name shortcut, you could instead write:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"

Both of the above examples Will produce the following HTML output:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

For comparison, here is the same paragraph written using Markdown's inline link style:

I get 10 times more traffic from [Google](http://google.com/ "Google")
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
[MSN](http://search.msn.com/ "MSN Search").

The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it's 176 characters; and as raw HTML, it's 234 characters. In the raw HTML, there's more markup than there is text.

With Markdown's reference-style links, a source document much more closely resembles the final output, as rendered in a browser. By allowing you to move the markup-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose.

[The examples Will produce]

Example 1

This is an example inline link.

This link has no title attribute.

Example 2

This is an example reference-style link.

[Caution]

1. Reference-style links can be used to create links in a document, like this:

*   [Overview](#overview)
*   [Installation](#installation)

<h2 id="overview">Overview</h2>
<h2 id="philosophy">Installation</h2>

2. The URL must contain http:// forehead in the link, or the link redirection will fail.

3. Some Markdown editors doesn't support a title enclosed in single quotes, please use enclose the title with double quotes.

8. EMPHASIS

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML <em> tag; double *'s or _'s will be wrapped with an HTML <strong> tag. E.g., this input:

Example 1

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

Will produce:

<em>single asterisks</em>

<em>single underscores</em>

<strong>double asterisks</strong>

<strong>double underscores</strong>

You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.

Emphasis can be used in the middle of a word:

Example 2

un*frigging*believable

But if you surround an * or _ with spaces, it'll be treated as a literal asterisk or underscore.

Example 3

This is a single asterisk * .

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:

Example 4

\*this text is surrounded by literal asterisks\*

[The examples Will produce]

Example 1

single asterisks

single underscores

double asterisks

double underscores

Example 2

unfriggingbelievable

Example 3

This is a single asterisk * .

Example 4

*this text is surrounded by literal asterisks*

Cautions

1. Some editors may not support the Markdown syntax in Example 2

Example 2

un*frigging*believable    

To use * for emphasis, please ensure a space before the opening asterisk and after the closing asterisk, like this:

Example 2 revised version

un *frigging* believable

un *frigging believable* Flag

un **frigging** believable

un **frigging believable** Flag

To emphasize a word within a word, please directly use <em> or <strong>, like this:

un<em>frigging</em>believable 

un<strong>frigging</strong>believable 

2. Doxygen can't use * to emphasize Chinese characters, please directly use <em> or <strong> instead.

3. Some Markdown editors allow line breaks in text, as shown below:

Some Markdown editors allow line breaks

**Line1
Line2
Line3**

While many compilers don't. In the meantime, almost all editors don't support line breaks.

Asterisks can't be used to emphasize multiple paragraphs.

**Line1

Line2

Line3**

4. In Doxygen, headers are emphasized by default, no extra *'s are needed.

5. In Doxygen, only text enclosed in the *'s which meet following conditions would be processed as emphasis:

Opening asterisk:

Followed by: a letter or a number
Follows: a space, a blank line, or any of the characters < { ( [ , : ;

Closing asterisk:

Followed by: neither a letter nor a number
Follows: neither a space, a blank line, nor any of the characters ( { [ < = + - \ @

6. In Doxygen, * and _ only work within a normal paragraph.

9. CODE

To indicate a span of code, wrap it with backtick quotes (`).

Note: The backtick character is located on left side of the number 1 and on top of Tab on the keyboard. Don't mix it up with the single quote.

For example:

Example 1

Use the `printf()` function.

Will produce:

<p>Use the <code>printf()</code> function.</p>

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

Example 2

``There is a literal backtick (`) here.``

which Will produce this:

<p><code>There is a literal backtick (`) here.</code></p>

The backtick delimiters surrounding a code span may include spaces — one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

Example 3

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

Will produce:

<p>A single backtick in a code span: <code>`</code></p>

<p>A backtick-delimited string in a code span: <code>`foo`</code></p>

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:

Example 4

Please don't use any `<pre>` tags.

into:

<p>Please don't use any <code>&lt;pre&gt;</code> tags.</p>

[The examples Will produce]

Example 1

Use the printf() function.

Example 2

There is a literal backtick (`) here.

Example 3

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

Example 4

Please don't use any <pre> tags.

Cautions

1. Code span is suitable for inserting a small amount of code.

2. Editors provide extra processing methods to insert a big amount of code. Below are some common methods:

A. Insert 3 literal backtick characters

```

Here is your code

```

Note: GFM (GitHub Flavored Markdown) adopts this method. And you can use some indicators after ``` to highlight the code.

B. Insert more than 3 wave lines

~~~

Here is your code

~~~

3. Doxygen has special commends for code blocks, please refer to Markdown Extensions for the details.

4. Doxygen can't handle code which includes single quotes like this:

A `cool' word in a `nice' sentence.

Please use code block instead.

10. IMAGES

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline image syntax looks like this:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

That is:

• An exclamation mark: !;
• followed by a set of square brackets, containing the alt attribute text for the image;
• followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in double or single quotes.

Note: The path can be a relative path or an absolute URL

Reference-style image syntax looks like this:

![Alt text][id]

Where "id" is the name of a defined image reference. Image references are defined using syntax identical to link references:

[id]: url/to/image  "Optional title attribute"

For example

Example 1:Image from website

![CooCox Logo](http://www.coocox.org/images/logo.jpg "CooCox Logo")

Will produce:

Example 2:Local image

![Beautiful Girl](/images/CH7/LocalPic.jpg "Beautiful Girl")

Will produce

Cautions

1. Markdown only provide image link mechanism rather than image management. In Doxygen, if the document includes any link to the local image, you must copy the image to HTML output folder manually to make the image show normally.

2. Please make sure the characters, alt text, and URL are in the same line, otherwise it won't be recognized by Markdown analyzer.

11. AUTOMATIC LINKS

Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets.

The code below

Example 1

<http://www.google.com.cn>

<[email protected]>

Will produce HTML like this:

<p><a href="http://www.google.com">http://www.google.com</a></p>

<p><a href="mailto:[email protected]">[email protected]</a></p>

[The example Will produce]

Example 1

http://www.google.com.cn

[email protected]

Cautions

The website must be complete and valid, including http:// or https://. The code below won't generate correct links:

<www.google.com.cn>
<google.com.cn>

12. INLINE HTML

If you are familiar with HTML, simply use HTML itself. There's no need to preface it or delimit it to indicate that you're switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, 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. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

For example, to add an HTML table to a Markdown article:

Example 1:Add an HTML table to a Markdown article

This is a regular paragraph.

<table>
    <tr>
        <td>1</td>
        <td>2</td>
        <td>3</td>
    </tr>
    <tr>
        <td>4</td>
        <td>5</td>
        <td>6</td>
    </tr>
    <tr>
        <td>7</td>
        <td>8</td>
        <td>9</td>
    </tr>
</table>

This is another regular paragraph.

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use Markdown-style *emphasis* inside an HTML block.

Span-level HTML tags — e.g. <span>, <cite>, or <del> — can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you'd prefer to use HTML <a> or <img> tags instead of Markdown's link or image syntax, go right ahead.

Example 2:Color a word with HTML to emphasize it 

This is <strong>in bold</strong>，This is <font color="red">in red</font>

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

[The examples Will produce]

Example 1:Add an HTML table to a Markdown article

This is a regular paragraph.

This is a regular paragraph.

Example 2:Color a word with HTML to emphasize it

This is in bold，This is in red

Cautions

1. Doxygen doesn't have such limitation,

The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, 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.

you can place the block-level HTML elements as you like.

2. Doxygen doesn't translate the content within <code> and </code>, but eliminate the lead spaces of the code and make the typesetting a mess. If you want to insert formatted code in comments or Markdown, use <pre>``</pre> tags or indent the code with 4 spaces.

3. Doxygen only support a few common tags, it processes JavaScript code or other tags like button as pure text, and escape all special JavaScript characters, therefore invalidate the inserted code.

For example, if we insert a button in Markdown:

<button type="input" title="Test Button">Button</button>

Doxygen will translate it into:

<button type="input" title="Test Button">Button</button>

To reach what we expect, we need to add JavaScript to avoid escape. Replace the code with this:

<script type="text/javascript" src="jquery.js"></script>

<script>
$(document).ready(function(e) {
    $('p').each(function(index, element) {
        var text = $(this).html();
        text = text.replace('$BEGIN$','');
        text = text.replace('$END$','');
        text = text.replace('&lt;','<');
        text = text.replace('&gt;','>');
        $(this).html(text);
    });
});
</script>

We need to rewrite the HTML code like this for sure:

$BEGIN$
<button type="input" title="Test Button">Button</button>
$END$

Doxygen--Markdown Extensions

Tables

Doxygen supports simple tables in PHP style, like this:

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

The seperator lines of the table consist of - and |, used to separate the columns and rows. The first line is called a header line. Each table has only one header line, and each other line is a separate row, in which different items are separated by |. The table above Will produce:

Here is a bit more complex example:

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

Will produce:

To make it look good, you can add | before the first and after the last column, and the output will stay the same:

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

Column alignment can be controlled via one or two colons at the header separator line:

  Align left       Align center    Align right

| First Header  | Second Header | Third Header |
| :------------ | :------------:| -----------: |
| Content Cell  | Content Cell  | Content Cell |
| Content Cell  | Content Cell  | Content Cell |
| Content Cell  | Content Cell  | Content Cell |

It will output this:

The syntax is easy to understand and the explanation will be saved.

Cautions

1: Doxygen only supports simple tables. If you want to use complex tables, do as follows:

Create and edit a table in word, transfer it into HTML code, and copy the code to Markdown article.

or other methods.

Fenced Code Blocks

Besides using backtick quotes to insert code, common Markdown editors also provide extra commands to support inserting a whole code block, and a common command is like this:

```

Here Is Your Code

```

Differently, Doxygen supports code blocks by surrounding the code with a pair of "fence lines". Such a line consists of 3 or more tilde (~) characters on a line. Here is an example:

Example 1

~~~

Here Is Your Code

~~~

Note that the end of the block should have the same number of tildes. For example, the command below is wrong:

~~~    There are tildes

You Code is here

~~~~~~ There are 5 tildes

Meanwhile, you can also make the code block appear with syntax highlighting. For example:

~~~{.programming language}

You Code is here

~~~

Or

~~~programming language

You Code is here

~~~

The code below is used to highlight a code block in C:

Example 2

~~~{.c}

int func(int a,int b)
{
    return a*b; 
}

~~~

For programming language supported by Doxygen, please refer here

[The examples Will produce]

Example 1: A normal code block

Example 2: Highlight the C code

Header Id Attributes

Standard Markdown has no support for labeling headers, which is a problem if you want to link to a section.

Generally, we use HTML syntax to create an ID for the header, like this:

*   [Overview](#overview)
*   [Installation](#installation)

<h1 id="overview">Overview</h1>
<h2 id="install">Installation</h2>

But it isn't obedient to Markdown philosophy, so PHP Markdown Extra allows you to label a header by adding the following to the header:

Overview                {#overview}
========

## Installation ##          {#installation}

Having the header ID, we can link the header to corresponding section in the artible, like this:

Example 1

*   [Overview](#overview)
*   [Installation](#installation)

Overview                {#overview}
========

## Installation ##          {#install}

Doxygen supports a special link marker [TOC] which can be placed in a page to produce a table of contents at the start of the page, listing all sections. For details, please refer to next section.

[The example Will produce]

Cautions

1. Note the header ID only works for the headers of level 1 to 4.

2. When using #, the header must be surrounded by the pound signs, e.g. the following command is wrong:

## Installation          {#installation}

3. To link to a section in the same article or comment block you can use [Link text](#labelid). To link to a section in general, use # instead of @ like this:

[Link text](@labelid)

4. To put a Markdown article on the main page of the output file, please set the configuration of the first header in the Markdown article as indexor mainpage.

Table of Contents

Doxygen supports a special link marker [TOC] which can be placed in a page to produce a table of contents at the start of the page, listing all sections. For example:

Example 1

*   [Overview](#overview)
*   [Installation](#installation)

Overview                {#overview}
========

## Installation ##          {#installation}

Will produce

Example 1: Create a catalog

Cautions

0. [TOC] must be put at the start of the article.

Below is a wrong usage:

Overview        {#Overview}
========

## Installation ##  {#Installation}

[TOC]

1. Markdown headers must have ID attributes, otherwise Doxygen doesn't generate a catalog.

Below is a wrong usage:

[TOC]

Overview 
========

## Installation ##

Link to external Markdown file

Many times, we need to link to another Markdown file in a Markdown file. There are 2 ways:

1）Link to the Markdown file name directly
2）Link to the Markdown file name ID

To be specific:

Link to the Markdown file name directly

Doxygen allows using a complete Markdown path (file name included) in a normal link to link to external Markdown file, like this:

[Link text](The complete path to the Markdown file)

The complete path here can be a relative path or a absolute path.

Note: If the file and the file to be linked are in the same directory, use the file name directly, like this:

[This ](The complete path to the Markdown file)

Link to the Markdown file name ID

By default, Doxygen uses the linked Markdown file name as the name shown in the document. Meanwhile, Doxygen allows users to define the shown name of the file:

This is shown name of the file.
==========================

Interact with the code in Markdown

In Markdown, we can also interact with the code. For example, if we call a function, the page will automatically jump to the document page of the function when clicking on it.

Here is how to do it:

\ref The function to be called

For example, if we want to call function SystemInit, we can write like this:

\ref SystemInit

Ending

That's all for how to use Markdown in Doxygen. There are a lot of traps, and special attention is needed to the cautions.

Many materials were referred to when writing this document. Many thanks! If you find any mistake or any paragraph hard to understand, please let us know, we will fix it any soon as possible.

References

1. Doxygen Manual main page
2. Doxygen Manual main page--Markdown support
3. Markdown standard syntax--Chinese version
4. Markdown standard syntax--English version
5. Markdown standard syntax--Quickstart Chinese version

Common Markdown editors

• Windows platform
  • MarkdownPad
  • MarkPad
• Linux platform
  • ReText
• Mac platform
  • Mou
• Online editors
  • stackedit.io
  • Markable.in
  • Dillinger.io
• Browser plugin
  • MaDe (Chrome)
• Advanced application
  • Sublime Text 2
  • MarkdownEditing
  • SublineMarkdown Manual