Content

Gi-docgen parses the content of docblocks from the introspection data as plain Markdown, using the Python-Markdown module.

For more information on Markdown, please see the syntax rules.

Basic syntax

These are the elements outlined in the original Markdown documentation.

Element	Markdown Syntax
Heading	# H1 ## H2 ### H3
Bold	**bold text**
Italic	*italicized text*
Blockquote	> blockquote
Ordered list	1. First item 2. Second item 3. Third item
Unordered list	- First item - Second item - Third item
Code	`` code ``
Horizontal rule	---
Link	[title](https://www.example.com)
Image	

Extensions

These are extensions to the basic syntax that are supported by gi-docgen:

• Definition Lists

• Fenced Code Blocks

• Tables

Admonitions

Gi-docgen supports “admonitions”: asides, like notes, tips, and warnings.

The syntax for admonitions is:

::: type "optional title within double quotes"
    Any number of other indented markdown elements.

    This is another paragraph within the admonition

    - This is a list
    - With two items

The type can be one of:

• note

• important

• warning

• seealso

• tip

• hint

If there is no title, each type of admonition will use a default title:

Type	Title
note	Note
important	Important
warning	Warning
seealso	See also
tip	Tip
hint	Hint

In order to distinguish the content of an admonition block from content following the admonition, you should add an empty line after the admonition, e.g.

::: tip
    This is a tip.

    This is still a tip


This paragraph is outside the tip.

GTK-Doc compatibility

Gi-docgen tries to facilitate porting an API reference from gtk-doc. It automatically turns gtk-doc sigils into code fragments:

• %CONSTANT

• #TypeName

• #TypeName:property

• #TypeName::signal

• symbol_name()

Important

Gi-docgen does not turn gtk-doc sigils into links, as they lack the specificity to allow cross-linking.