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 |
|
Italic |
|
Blockquote |
|
Ordered list |
1. First item2. Second item3. Third item |
Unordered list |
- First item- Second item- Third item |
Code |
`` code `` |
Horizontal rule |
|
Link |
|
Image |
|
Extensions
These are extensions to the basic syntax that are supported by gi-docgen:
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:
noteimportantwarningseealsotiphint
If there is no title, each type of admonition will use a default title:
Type |
Title |
|---|---|
|
Note |
|
Important |
|
Warning |
|
See also |
|
Tip |
|
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::signalsymbol_name()
Important
Gi-docgen does not turn gtk-doc sigils into links, as they lack the specificity to allow cross-linking.