Module brl.markdown

The markdown module converts easy to read/write plain text (known as markdown) to html, using a simple text formatting syntax. More...

Declarations

Imported By
`brl`

Please note that only documented modules are listed here, there might be undocumented modules that import this one.

Classes
`Markdown`	The Markdown class is used to transform text using the brl.markdown syntax.

Interfaces
`ILinkResolver`
`IPrettifier`

Detailed Discussion

The markdown module converts easy to read/write plain text (known as markdown) to html, using a simple text formatting syntax.

Markdown may also include html. Note that the special html characters <, > and & must therefore be 'escaped' using a backslash, the markdown escape character. For example, to insert a literal < into your markdown, you should use \<.

To convert markdown text to html, you must create a Markdown object and call its Markdown.ToHtml method.

Markdown syntax

Paragraph separators

A blank line inserts a paragraph separator into the output.

Example

This
is
on
one
line...
 
This is a new paragraph!

Output

This is on one line...

This is a new paragraph!

Line breaks

Appending ~n to the end of a line will cause a line break to be inserted.

Example

Tightly~n
Packed~n
Lines~n

Output

Tightly
Packed
Lines

Text style

Text may be enclosed in the following style tags to control text style. Style tags may not span multiple lines.

*bold*
%italic%
`code`

Additionally, the @ character can be used to put emphasis on a single word.

Example

*This is in bold* as well as @this, while %this is in italics%. And `this is some code`.

Output

This is in bold as well as this, while this is in italics. And this is some code.

In-line HTML

Except for the <pre> </pre> tags, html tags are passed as-is to the final generated document. This means, you can use html markup for coloured texts, iframes, embedded objects and so on. Just keep in mind that the html renderer inside your IDE might not have every html feature implemented.

Example

This text contains a <span style="background:yellow;">highlighted</span> word.

Output

This text contains a highlighted word.

Code blocks

Code blocks are generated using <pre> .. </pre> tags.

Example

<pre>
Function Main:Int()
	Return 0
End
</pre>

Output

Function Main:Int()
Return 0
End

Note that inside <pre> blocks markdown is bypassed, so you don't have to escape html or markdown special chars.

For code blocks without syntax highlighting, you need to use in-line html with <div class="pretty"> .. </div> tags around the block and put the code into <code> .. </code> tags. However, the escaping within such blocks differs from the one within pre-tags, meaning you have to escape html characters and markdown. Also, such blocks may not contain blank lines, since they will be translated into paragraph separators, which would cause invalid html. Instead, you have to put a space character at the place of a blank line.

Lists

* Unordered list

+ Ordered list

Example

* Item
* Another item
* Yet another item
 
+ Item 1
+ Item 2
+ Item 3

Output

Item
Another item
Yet another item

Item 1
Item 2
Item 3

Lists may contain paragraph separators.

Tables

Tables may not contain paragraph separators - a blank line ends the table.

Example

| Flags   | Meaning
| 1       | Enable
| 2       | MidHandle

Output

Flags	Meaning
1	Enable
2	MidHandle

Headers

> Top level header
>> Second level header
>>> Third level header
>>>> Fourth level header
>>>>> Fifth level header
>>>>>> Sixth level header

Example

> Title
>> Chapter 1
>> Chapter 2
>>> Figure 1

Output

Title

Chapter 1

Chapter 2

Figure 1

Links

Links may be created by enclosing the link target in [[ and ]]. In addition, alternate link text may be added using |.

Example

* [[Home]]
* [[Home|Go Home]]
* [This also is a form of a link that leads to Home](Home)

Output

Anchors

Using the an empty <a> element with a name attribute, anchors can be defined to which you can link within a page.

Example

>>>> <a name="anchor"></a> You can link here
 
Watch where this link takes you:
 
[[#anchor]]

Output

You can link here

Watch where this link takes you:

#anchor

Images

Images may be inserted with ![Alternate text](url).

Example

![Cerberus X logo](data/cerberusx.png)

Output

Cerberus X logo

Horizontal dividers

A horizontal divider may be inserted by using one to three dash characters alone on a line.

Example

Above
---
Below

Output

Above

Below

Escaping markdown characters

The backslash character may be used to escape any special markdown characters. To insert a literal backslash, use \\.

Example

*This is bold*, but \*this isn't\*.

Output

This is bold, but *this isn't*.