Gambas Markdown Syntax

The Gambas Markdown Syntax is a customized version of the Markdown syntax. It allows to write most of HTML without having to use all these HTML markups.

Here is a quick documentation of the syntax:

Paragraphs

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Normal paragraphs should not be indented with spaces or tabs, except in the context of lists.

If a line ends with a slash \ character, then a line break (<br>) is inserted.

Example

will print:

Headers

You can write first-level headers by underlining the header text this way:

Any number of underlining = will work.

The other syntax is prefixing the header text with #:

Optionally, you may close the headers. This is purely cosmetic - you can use this if you think it looks better.

Example

will print:

Indexed headers

Indexed headers are headers that will be visible in the index generated by the @{index} special command (see below).

To make an indexed header, just write the header title between [ and ] characters.

For example:

Blockquotes

The syntax uses email-style > characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of >:

Blockquotes can contain other elements, including headers, lists, and code blocks:

You can put blockquotes into lists too.

Lists

Unordered lists use asterisks, and hyphens - interchangeably - as list markers:

is equivalent to:

Ordered list items use the plus character + as list markers:

List markers typically start at the left margin, but may be indented by any number of spaces.

If a list item follows a blank line, then the item will be wrapped in <p> tags. For example, this input:

will turn into:

But this:

will turn into:

List items may consist of multiple paragraphs.

To put a blockquote within a list item, the blockquote’s > delimiters need to be indented:

Which gives:

To put a code block within a list item, the code block indentation must be added to the list indentation:

Code blocks

Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Code blocks are wrapped in both <pre> and <code> tags.

To produce a code block, simply indent every line of the block by at least 4 spaces or 1 tab. For example, given this input:

The following will be generated:

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (&) and angle brackets (< and >) are automatically converted into HTML entities. This makes it very easy to include example HTML source code - just paste it and indent it.

For example, this:

will turn into:

The markup syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block.

Horizontal rules

You can produce a horizontal rule tag (<hr/>) by placing three or more hyphens, or asterisks on a line by themselves.

Each of the following lines will produce a horizontal rule:

Links

Two style of links are supported: inline and reference.

In both styles, the link text is delimited by square brackets.

Inline links

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

Will produce:

Note that a "void link" (i.e. []) will not be interpreted and the two brackets will be emitted as is.

If the link between braces is not specified, then it is assumed to be the same as the link title between brackets:

Will produce:

Note that external links are automatically opened in a new window.

Reference links

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

Then, anywhere in the document, you define your link label like this, on a line by itself:

[id]: http://example.com/ "Optional Title Here"

That is:

• Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);

• followed by a colon;

• followed by one or more spaces (or tabs);

• followed by the URL for the link;

• optionally followed by a title attribute for the link, enclosed in double quotes.

Link definitions are stripped from your document in the HTML output.

Link definition names may consist of letters, numbers, spaces, and punctuation - but they are not case sensitive. E.g. these two links:

are equivalent.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets - e.g., to link the word “Google” to the google.com web site, you could simply write:

And then define the link:

[Google]: http://google.com/

Because link names may contain spaces, this shortcut even works for multiple words in the link text:

And then define the link:

Link definitions can be placed anywhere in your document.

Here’s an example of reference links in action:

Using the implicit link name shortcut, you could instead write:

Both of the above examples will produce the following HTML output:

For comparison, here is the same paragraph written using inline link style:

Emphasis

Emphasis is indicated by asterisks (*). Text wrapped with one * will be wrapped with an HTML <em> tag; double *s will be wrapped with an HTML <strong> tag. E.g., this input:

will produce:

Emphasis cannot be used in the middle of a word, nor alone in a word.

It will be treated as a literal asterisk.

To produce a literal asterisk at a position where it would otherwise be used as an emphasis delimiter, you must escape it with a backslash (see below).

Code

To indicate a span of code, wrap it with single quotes (') or backtick quotes (`).

Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

will produce:

With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. This:

will be turned into:

You can write this:

to produce:

The difference between the backquote and the single quote is that HTML tags and HTML entities are interpreted between single quotes, whereas they are automatically escaped between backquotes.

Gives you:

Automatic Escaping for Special Characters

In HTML, there are two characters that demand special treatment: < and &.

Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you must escape them as entities, e.g. <, and &.

You even need to escape ampersands within URLs.

The markup syntax allows you to use these characters naturally, taking care of all the necessary escaping for you. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into &.

So, if you want to include a copyright symbol in your article, you can write:

and it will be left alone. But if you write:

it will be translated to:

Backslash Escapes

Any special character can be escaped with a backslash \ to be interpreted literally and prevent them to be interpreted.

Gives you:

Inline HTML

Finally, you can write any HTML code anywhere. HTML markup are automatically detected.

Beware that the markup syntax is interpreted between HTML tags.

Tables

Table can be created by using the following syntax:

Which gives you:

The header is optional:

Gives you:

If a table has only one cell, then a simple <div> markup will be used instead of a <table>.

Note that the css class of the table can be inserted just after the initial [[.

Special commands

Special commands generate some dynamic part of the page.

The syntax of a special command is @{command} where command is the name of the command.

A command can take arguments: @{command arg1 arg2}. They follow the command name and are separated by space characters.

@{index}

Insert an index of all indexed headers.

@{index <prefix>}

Insert an alphabetic index of all pages whose path begins with <prefix>.

@{since x.x.xx}

Insert a notice that this feature has been available since the indicated version in format x.xx.xx .