On top of this base layer, the Preside Documentation system processes its own special syntaxes for syntax highlighting, cross referencing and notice boxes. It also processes YAML front matter to glean extra metadata about pages.
Syntax highlighted code blocks start and end with three backticks on their own line with an optional lexer after the first set of ticks.
For example, a code block using a 'luceescript' lexer, would look like this:
```luceescript x = y; WriteOutput( x ); ```
A code block without syntax higlighting would look like this:
``` x = y; WriteOutput( x ); ```
We have implemented two lexers for Lucee,
luceescript. The former is used for tag based code, the latter, script based. For a complete list of available lexers, see the Pygments website.
Cross referencing between pages can be achieved using a double square bracket syntax surrounding the id of the page you wish to link to. For example:
When the link is rendered, the title of the page will be passed to the renderer. To provide a custom text for the link, use the following syntax:
[[function-abs|Custom link text]]
Various "notice boxes" can be rendered by using a nested blockquote syntax. The nesting level dictates the type of notice rendered.
Info boxes use three levels of blockquote indentation:
>>> An example info box
An example info box
Warning boxes use four levels of blockquote indentation:
>>>> An example warning box
An example warning box
Important boxes use five levels of blockquote indentation:
>>>>> An example 'important' box
An example 'important' box
Tip boxes use six levels of blockquote indentation:
>>>>>> An example tip box
An example tip box
YAML Front Matter
YAML Front Matter is used to add metadata to pages that can then be used by the build system. The syntax takes the form of three dashes
--- at the very beginning of a markdown document, followed by a YAML block, followed by three dashes on their own line. For example:
--- variableName: value arrayVariable: - arrayValue 1 - arrayValue 2 ---
The system relies upon an id variable and title variable to be present in all pages in order to build its tree and perform cross referencing tasks. It will also allow you to tag pages with categories and 'related' links.
A full example might look like:
--- id: function-abs title: Abs() related: - "[Problem with Abs()](http://someblog.com/somearticle.html)" categories: - number - math
Category links will be rendered as
[[category-categoryname]]. Related links will be rendered using the markdown renderer so can use any valid link format, including our custom cross referencing syntax (see above, and note the required double quotes to escape the special characters).