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 "&lt;", "&gt;", "&lpar;", "&rpar;", "&commat;", "&percnt;" and "&num;". 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 &commat;", "&percnt;", 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 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]

Projects/GTK+/DocumentationSyntax/Markdown (last edited 2014-05-06 15:06:42 by MatthiasClasen)