Contents
Markdown Support
Most of the plain text sections of the Documentation Block Parts support a custom variant of the basic text formatting syntax called Markdown.
Markdown is comprised entirely of punctuation characters with an attempt to make them look like what they mean.
Differences from Traditional Markdown
The differences from typical Markdown are either extensions to the syntax, different behavior of the standard syntax, or unimplemented features.
Extensions to the Syntax
- |[
- At the beginning of a line starts a program listing block
- |[<!-- language="" -->
- At the beginning of a line starts a program listing block for the given language.
- ]|
- At the beginning of a line ends a program listing block
- function()
- to refer to functions or macros which take arguments.
- @param
- to refer to parameters. Also use this when referring to parameters of other functions, related to the one being described.
- %constant
- to refer to a constant, e.g. %G_TRAVERSE_LEAFS.
- #symbol
- to refer to other types of symbol, e.g. structs and enums and macros which don't take arguments.
- #Object::signal
- to refer to a GObject signal
- #Object:property
- to refer to a GObject property
- #Struct.field
- to refer to a field inside a structure. # Heading 1 # {#anchor-identifier}
- Headings may include optional anchor identifiers.
Note that we no longer interpret XML markup in text, so it is no longer necessary (and not working, either) to escape the special characters '<', '>', '()', '@', '%', or '#' as XML entities "<", ">", "(", ")", "@", "%" and "#". If you need to prevent one of these characters from being interpreted as markup, escape them with a backslash '\'. Inside of a program listing |[ ]| block, the text is left unmodified except that some "entities" (such as @", "%", etc) are converted back to the actual characters. This is done to support legacy use. If you include C-style comments in your program listings you may need to take special care to avoid confusing the preprocessor with comment strings. The easiest way to do this is with single-line comments:
* |[
* // Theme labels that are descendants of a window
* GtkWindow GtkLabel {
* background-color: #898989
* }
Different Behavior
Only two levels of heading are supported. This is primarily due to a restriction in Docbook.
Currently "reference links" are treated somewhat differently. [title][id] gets converted to a Docbook "<link>" element that can be used to link to any section id, not just those defined with Markdown anchors.
Unimplemented Features
The following are not supported and likely never will be:
Markdown <code> blocks. We use the "|[" syntax instead.
- Horizontal rules
- Link definitions
- Reference links for images
- Implicit links
Not supported at this time but may be in the future:
- "optional title" attributes for links
- Emphasis
Typical Markdown
Paragraphs
Paragraphs are one or more lines of consecutive text followed by a blank line.
This is one paragraph. And this is another.
Headings
Two levels of heading are supported. They can be created by adding one # mark before a first level heading or ## before a second level heading. Optional anchor identifiers may be included at the end of the line.
# Heading 1
## Heading 2
## Heading 3 with anchor ## {#anchor-id}
Inset Blocks (as known as block quotes
One or more lines of text may be inset by starting the line with >.
> This is an inset block. > That can continue on another line.
Lists
Unordered lists may be created by starting a line with a - character. Each list item may contain multiple lines of text followed by a blank line. Each subsequent line be indented by 2 or more spaces. Additional paragraphs may be used by including a blank line.
- This is a first list item This is a continuation of the same item. This is another paragraph. - This is a second list item.
Ordered lists may be created by using a number followed by a period in the manner described above. The number value used does not matter. However, to aid readability of the source it is recommended to keep a natural order.
1. First item 2. Second item.
Links
Links to external resources may be included by marking the link text in square brackets [text] immediately followed by the link URI in parentheses (uri).
[GNOME](http://www.gnome.org/)
Links to documentation resources may be included by marking the link text in square brackets immediately followed by the resource identifier in square brackets.
[supported CSS properties][gtk-css-properties]
A shorthand syntax is also supported. URIs placed in angle brackets will be automatically turned into links. At the moment, only http and https resources are supported.
<http://www.gnome.org>
Email addresses place in angle brackets will be automatically converted to mailto type links.
<help@gnome.org>
Images
Images may be included using a variation of the link syntax. The alternate text of the image should be placed in square brackets preceded by a ! character and the image file name should follow in square brackets.
![a plot of the result][plot-result.png]