1 /******************************************************************************
5 * Copyright (C) 1997-2015 by Dimitri van Heesch.
7 * Permission to use, copy, modify, and distribute this software and its
8 * documentation under the terms of the GNU General Public License is hereby
9 * granted. No representations are made about the suitability of this software
10 * for any purpose. It is provided "as is" without express or implied warranty.
11 * See the GNU General Public License for more details.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page markdown Markdown support
22 was introduced in doxygen version 1.8.0. It is a plain text formatting
23 syntax written by John Gruber, with the following underlying design goal:
25 > The design goal for Markdown's formatting syntax is to
26 > make it as readable as possible. The idea is that a Markdown-formatted
27 > document should be publishable as-is, as plain text, without
28 > looking like it's been marked up with tags or formatting instructions.
29 > While Markdown's syntax has been influenced by several existing
30 > text-to-HTML filters, the single biggest source of inspiration
31 > for Markdown's syntax is the format of plain text email.
33 In the \ref markdown_std "next section" the standard Markdown features
34 are briefly discussed. The reader is referred to the [Markdown site][markdown]
37 Some enhancements were made, for instance [PHP Markdown Extra][mdextra], and
38 [GitHub flavored Markdown][github]. The section \ref markdown_extra discusses
39 the extensions that doxygen supports.
41 Finally section \ref markdown_dox discusses some specifics for doxygen's
42 implementation of the Markdown standard.
44 [markdown]: https://daringfireball.net/projects/markdown/
45 [mdextra]: https://michelf.ca/projects/php-markdown/extra/
46 [github]: https://github.github.com/github-flavored-markdown/
48 \section markdown_std Standard Markdown
50 \subsection md_para Paragraphs
52 Even before doxygen had Markdown support it supported the same way
53 of paragraph handling as Markdown: to make a paragraph you just separate
54 consecutive lines of text by one or more blank lines.
58 Here is text for one paragraph.
60 We continue with more text in another paragraph.
62 \subsection md_headers Headers
64 Just like Markdown, doxygen supports two types of headers
66 Level 1 or 2 headers can be made as the follows
68 This is a level 1 header
69 ========================
71 This is a level 2 header
72 ------------------------
74 A header is followed by a line containing only ='s or -'s.
75 Note that the exact amount of ='s or -'s is not important as long as
76 there are at least two.
78 Alternatively, you can use #'s at the start of a line to make a header.
79 The number of #'s at the start of the line determines the level (up to 6 levels are supported).
80 You can end a header by any number of #'s.
84 # This is a level 1 header
86 ### This is level 3 header #######
88 \subsection md_blockquotes Block quotes
90 Block quotes can be created by starting each line with one or more >'s,
91 similar to what is used in text-only emails.
93 > This is a block quote
94 > spanning multiple lines
96 Lists and code blocks (see below) can appear inside a quote block.
97 Quote blocks can also be nested.
99 Note that doxygen requires that you put a space after the (last) > character
100 to avoid false positives, i.e. when writing
105 the second line will not be seen as a block quote.
107 \subsection md_lists Lists
109 Simple bullet lists can be made by starting a line with -, +, or *.
113 More text for this item.
117 + another nested item.
120 List items can span multiple paragraphs (if each paragraph starts with
121 the proper indentation) and lists can be nested.
122 You can also make a numbered list like so
127 Make sure to also read \ref mddox_lists for doxygen specifics.
129 \subsection md_codeblock Code Blocks
131 Preformatted verbatim blocks can be created by indenting
132 each line in a block of text by at least 4 extra spaces
134 This a normal paragraph
138 We continue with a normal paragraph again.
140 Doxygen will remove the mandatory indentation from the code block.
141 Note that you cannot start a code block in the middle of a paragraph
142 (i.e. the line preceding the code block must be empty).
144 See section \ref mddox_code_blocks for more info how doxygen handles
145 indentation as this is slightly different than standard Markdown.
147 \subsection md_rulers Horizontal Rulers
149 A horizontal ruler will be produced for lines containing at least three or more
150 hyphens, asterisks, or underscores. The line may also include any amount of whitespace.
157 Note that using asterisks in comment blocks does not work. See
158 \ref mddox_stars for details.
160 \subsection md_emphasis Emphasis
162 To emphasize a text fragment you start and end the fragment with an underscore or star.
163 Using two stars or underscores will produce strong emphasis.
169 * _single underscores_
171 * **double asterisks**
173 * __double underscores__
175 See section \ref mddox_emph_spans for more info how doxygen handles
176 emphasis / strikethrough spans slightly different than standard / Markdown GitHub Flavored Markdown.
178 \subsection md_strikethrough Strikethrough
180 To strikethrough a text fragment you start and end the fragment with two tildes.
186 See section \ref mddox_emph_spans for more info how doxygen handles
187 emphasis / strikethrough spans slightly different than standard Markdown / GitHub Flavored Markdown.
189 \subsection md_codespan code spans
191 To indicate a span of code, you should wrap it in backticks (`). Unlike code blocks,
192 code spans appear inline in a paragraph. An example:
194 Use the `printf()` function.
196 To show a literal backtick inside a code span use double backticks, i.e.
198 To assign the output of command `ls` to `var` use ``var=`ls```.
200 See section \ref mddox_code_spans for more info how doxygen handles
201 code spans slightly different than standard Markdown.
203 \subsection md_links Links
205 Doxygen supports both styles of make links defined by Markdown: *inline* and *reference*.
207 For both styles the link definition starts with the link text delimited by [square
210 \subsubsection md_inlinelinks Inline Links
212 For an inline link the link text is followed by a URL and an optional link title which
213 together are enclosed in a set of regular parenthesis.
214 The link title itself is surrounded by quotes.
218 [The link text](http://example.net/)
219 [The link text](http://example.net/ "Link title")
220 [The link text](/relative/path/to/index.html "Link title")
221 [The link text](somefile.html)
223 In addition doxygen provides a similar way to link a documented entity:
225 [The link text](@ref MyClass)
227 \subsubsection md_reflinks Reference Links
229 Instead of putting the URL inline, you can also define the link separately
230 and then refer to it from within the text.
232 The link definition looks as follows:
234 [link name]: http://www.example.com "Optional title"
236 Instead of double quotes also single quotes or parenthesis can
237 be used for the title part.
239 Once defined, the link looks as follows
241 [link text][link name]
243 If the link text and name are the same, also
251 can be used to refer to the link.
252 Note that the link name matching is not case sensitive
253 as is shown in the following example:
255 I get 10 times more traffic from [Google] than from
258 [google]: http://google.com/ "Google"
259 [yahoo]: http://search.yahoo.com/ "Yahoo Search"
260 [msn]: http://search.msn.com/ "MSN Search"
262 Link definitions will not be visible in the output.
264 Like for inline links doxygen also supports \@ref inside a link definition:
266 [myclass]: @ref MyClass "My class"
268 \subsection md_images Images
270 Markdown syntax for images is similar to that for links.
271 The only difference is an additional ! before the link text.
275 ![Caption text](/path/to/img.jpg)
276 ![Caption text](/path/to/img.jpg "Image title")
277 ![Caption text][img def]
280 [img def]: /path/to/img.jpg "Optional Title"
282 Also here you can use \@ref to link to an image:
284 ![Caption text](@ref image.png)
287 [img def]: @ref image.png "Caption text"
289 The caption text is optional.
291 \subsection md_autolink Automatic Linking
293 To create a link to an URL or e-mail address Markdown supports the following
296 <http://www.example.com>
297 <https://www.example.com>
298 <ftp://www.example.com>
299 <mailto:address@example.com>
300 <address@example.com>
302 Note that doxygen will also produce the links without the angle brackets.
304 \section markdown_extra Markdown Extensions
306 \subsection md_toc Table of Contents
308 Doxygen supports a special link marker `[TOC]` which can be placed in a page
309 to produce a table of contents at the start of the page, listing all sections.
311 Note that using `[TOC]` is the same as using a
312 \ref cmdtableofcontents "\\tableofcontents" command.
314 Note that the \ref cfg_toc_include_headings "TOC_INCLUDE_HEADINGS" has to be set
315 to a value > 0 otherwise no table of contents is shown when using \ref md_headers "Markdown Headers".
317 \subsection md_tables Tables
319 Of the features defined by "Markdown Extra" is support for
320 <a href="https://michelf.ca/projects/php-markdown/extra/#table">simple tables</a>:
322 A table consists of a header line, a separator line, and at least one
323 row line. Table columns are separated by the pipe (|) character.
327 First Header | Second Header
328 ------------- | -------------
329 Content Cell | Content Cell
330 Content Cell | Content Cell
332 which will produce the following table:
334 First Header | Second Header
335 ------------- | -------------
336 Content Cell | Content Cell
337 Content Cell | Content Cell
339 Column alignment can be controlled via one or two colons
340 at the header separator line:
342 | Right | Center | Left |
343 | ----: | :----: | :---- |
345 | 1000 | 1000 | 1000 |
347 which will look as follows:
349 | Right | Center | Left |
350 | ----: | :----: | :---- |
352 | 1000 | 1000 | 1000 |
354 Additionally, column and row spans are supported. Using a caret ("^")
355 in a cell indicates that the cell above should span rows. Sequences
356 of carets may be used for any number of row spans. For example:
358 | Right | Center | Left |
359 | ----: | :----: | :---- |
363 which will look as follows:
365 | Right | Center | Left |
366 | ----: | :----: | :---- |
370 Column spans are supported by means of directly adjacent vertical bars
371 ("|"). Each additional vertical bar indicates an additional column to
372 be spanned. To put it another way, a single vertical bar indicates a
373 single column span, two vertical bars indicates a 2 columns span, and
376 | Right | Center | Left |
377 | ----: | :----: | :---- |
381 which will look as follows:
383 | Right | Center | Left |
384 | ----: | :----: | :---- |
388 For more complex tables in doxygen please have a look at: \ref tables
390 \subsection md_fenced Fenced Code Blocks
392 Another feature defined by "Markdown Extra" is support for
393 <a href="https://michelf.ca/projects/php-markdown/extra/#fenced-code-blocks">
394 fenced code blocks</a>:
396 A fenced code block does not require indentation, and is
397 defined by a pair of "fence lines". Such a line consists of 3 or
398 more tilde (~) characters on a line. The end of the block should have the
399 same number of tildes. Here is an example:
402 This is a paragraph introducing:
404 ~~~~~~~~~~~~~~~~~~~~~
405 a one-line code block
406 ~~~~~~~~~~~~~~~~~~~~~
408 By default the output is the same as for a normal code block.
410 For languages supported by doxygen you can also make the code block
411 appear with syntax highlighting. To do so you need to
412 indicate the typical file extension that corresponds to the
413 programming language after the opening fence. For highlighting according
414 to the Python language for instance, you would need to write the following:
429 and for C you would write:
432 int func(int a,int b) { return a*b; }
438 int func(int a,int b) { return a*b; }
441 The curly braces and dot are optional by the way.
443 Another way to denote fenced code blocks is to use 3 or more backticks (```):
446 also a fenced code block
449 \subsection md_header_id Header Id Attributes
451 Standard Markdown has no support for labeling headers, which
452 is a problem if you want to link to a section.
454 PHP Markdown Extra allows you to label a header by adding
455 the following to the header
460 ## Header 2 ## {#labelid2}
462 To link to a section in the same comment block you can use
464 [Link text](#labelid)
466 to link to a section in general, doxygen allows you to use \@ref
468 [Link text](@ref labelid)
470 Note this only works for the headers of level 1 to 4.
472 \section markdown_dox Doxygen specifics
474 Even though doxygen tries to following the Markdown standard as closely as
475 possible, there are couple of deviation and doxygen specifics additions.
477 \subsection md_page_header Including Markdown files as pages
479 Doxygen can process files with Markdown formatting.
480 For this to work the extension for such a file should
481 be `.md` or `.markdown` (see
482 \ref cfg_extension_mapping "EXTENSION_MAPPING" if your Markdown files have
483 a different extension, and use `md` as the name of the parser).
484 Each file is converted to a page (see the \ref cmdpage "page" command for
487 By default the name and title of the page are derived from the file name.
488 If the file starts with a level 1 header however, it is used as the title
489 of the page. If you specify a label for the
490 header (as shown in \ref md_header_id) doxygen will use that as the
493 If the label is called `index` or `mainpage` doxygen will put the
494 documentation on the front page (`index.html`).
496 Here is an example of a file `README.md` that will appear as the main page
497 when processed by doxygen:
499 My Main Page {#mainpage}
502 Documentation that will appear on the main page
504 If a page has a label you can link to it using \ref cmdref "\@ref" as
505 is shown above. To refer to a markdown page without
506 such label you can simple use the file name of the page, e.g.
508 See [the other page](other.md) for more info.
510 \subsection md_html_blocks Treatment of HTML blocks
512 Markdown is quite strict in the way it processes block-level HTML:
514 > block-level HTML elements — e.g.
515 > `<div>`, `<table>`, `<pre>`, `<p>`, etc. —
516 > must be separated from surrounding content by blank lines,
517 > and the start and end tags of the block should not be indented
518 > with tabs or spaces.
520 Doxygen does not have this requirement, and will also process
521 Markdown formatting inside such HTML blocks. The only exception is
522 `<pre>` blocks, which are passed untouched (handy for ASCII art).
524 Doxygen will not process Markdown formatting inside verbatim or code blocks,
525 and in other sections that need to be processed without changes
526 (for instance formulas or inline dot graphs).
528 \subsection mddox_code_blocks Code Block Indentation
530 Markdown allows both a single tab or 4 spaces to start a code block.
531 Since doxygen already replaces tabs by spaces before doing Markdown
532 processing, the effect will only be same if TAB_SIZE in the configuration file
533 has been set to 4. When it is set to a higher value spaces will be
534 present in the code block. A lower value will prevent a single tab to be
535 interpreted as the start of a code block.
537 With Markdown any block that is indented by 4 spaces (and 8 spaces
538 inside lists) is treated as a code block. This indentation amount
539 is absolute, i.e. counting from the start of the line.
541 Since doxygen comments can appear at any indentation level
542 that is required by the programming language, it
543 uses a relative indentation instead. The amount of
544 indentation is counted relative to the preceding paragraph.
545 In case there is no preceding paragraph (i.e. you want to start with a
546 code block), the minimal amount of indentation of the whole comment block
547 is used as a reference.
549 In most cases this difference does not result in different output.
550 Only if you play with the indentation of paragraphs the difference
561 In this case Markdown will put the word code in a code block,
562 whereas doxygen will treat it as normal text, since although the absolute
563 indentation is 4, the indentation with respect to the previous paragraph
566 Note that list markers are not counted when determining the
577 For Item1 the indentation is 4 (when treating the list marker as whitespace),
578 so the next paragraph "More text..." starts at the same indentation level
579 and is therefore not seen as a code block.
581 \subsection mddox_emph_spans Emphasis and strikethrough limits
583 Unlike standard Markdown and Github Flavored Markdown doxygen will not touch internal underscores or
584 stars or tildes, so the following will appear as-is:
588 Furthermore, a `*` or `_` only starts an emphasis and a `~` only starts a strikethrough if
589 - it is followed by an alphanumerical character, and
590 - it is preceded by a space, newline, or one the following characters `<{([,:;`
592 An emphasis or a strikethrough ends if
593 - it is not followed by an alphanumerical character, and
594 - it is not preceded by a space, newline, or one the following characters `({[<=+-\@`
596 Lastly, the span of the emphasis or strikethrough is limited to a single paragraph.
599 \subsection mddox_code_spans Code Spans Limits
601 Note that unlike standard Markdown, doxygen leaves the following untouched.
603 A `cool' word in a `nice' sentence.
605 In other words; a single quote cancels the special treatment of a code span
606 wrapped in a pair of backtick characters. This extra restriction was
607 added for backward compatibility reasons.
609 \subsection mddox_lists Lists Extensions
611 With Markdown two lists separated by an empty line are joined together into
612 a single list which can be rather unexpected and many people consider it to
613 be a bug. Doxygen, however, will make two separate lists as you would expect.
623 With Markdown the actual numbers you use to mark the list have no
624 effect on the HTML output Markdown produces. I.e. standard Markdown treats the
625 following as one list with 3 numbered items:
631 Doxygen however requires that the numbers used as marks are in
632 strictly ascending order, so the above example would produce 3 lists
633 with one item. An item with an equal or lower number than
634 the preceding item, will start a new list. For example:
648 Historically doxygen has an additional way to create numbered
649 lists by using `-#` markers:
654 \subsection mddox_stars Use of asterisks
656 Special care has to be taken when using *'s in a comment block
657 to start a list or make a ruler.
659 Doxygen will strip off any leading *'s from the comment before doing
660 Markdown processing. So although the following works fine
669 When you remove the leading *'s doxygen will strip the other stars
670 as well, making the list disappear!
672 Rulers created with *'s will not be visible at all. They only work
675 \subsection mddox_limits Limits on markup scope
677 To avoid that a stray * or _ matches something many paragraphs later,
678 and shows everything in between with emphasis, doxygen limits the scope
679 of a * and _ to a single paragraph.
681 For a code span, between the starting and ending backtick only two
682 new lines are allowed.
684 Also for links there are limits; the link text, and link title each can
685 contain only one new line, the URL may not contain any newlines.
687 \section markdown_debug Debugging of problems
689 When doxygen parses the source code it first extracts the comments blocks,
690 then passes these through the Markdown preprocessor. The output of the
691 Markdown preprocessing consists of text with \ref cmd_intro "special commands"
692 and \ref htmlcmds "HTML commands".
693 A second pass takes the output of the Markdown preprocessor and
694 converts it into the various output formats.
696 During Markdown preprocessing no errors are produced. Anything that
697 does not fit the Markdown syntax is simply passed on as-is. In the subsequent
698 parsing phase this could lead to errors, which may not always be obvious
699 as they are based on the intermediate format.
701 To see the result after Markdown processing you can run doxygen with the
702 `-d Markdown` option. It will then print each comment block before and
703 after Markdown processing.
706 Go to the <a href="lists.html">next</a> section or return to the
707 <a href="index.html">index</a>.