Lucee Docs Markdown

The base Markdown engine used is commonmark. Please see both the official Markdown website for the supported syntax.

On top of this base layer, the Lucee 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 highlighting

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 highlighting would look like this:

```
x = y;
WriteOutput( x );
```

We have implemented two lexers for Lucee, lucee and luceescript. The former is used for tag based code, the latter, script based. For a complete list of available lexers, see the Pygments website.

Embedded TryCF code runner

In addition to syntax highlighting, we also will take any lexer that is suffixed with +trycf, and convert the contained code into a runnable and editable sample using TryCF (in the website only). For example:

```luceescript+trycf
x = 10;
WriteOutput( x );
```

or:

```lucee+trycf
<cfset x = 10>
<cfoutput>#x#</cfoutput>
```

Cross referencing

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:

[[function-abs]]

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]]

Notice boxes

Various "notice boxes" can be rendered by using a nested blockquote syntax. The nesting level dictates the type of notice rendered.

Info boxes

Info boxes use three levels of blockquote indentation:

>>> An example info box

An example info box

Warning boxes

Warning boxes use four levels of blockquote indentation:

>>>> An example warning box

An example warning box

Important boxes

Important boxes use five levels of blockquote indentation:

>>>>> An example 'important' box

An example 'important' box

Tip boxes

Tip boxes use six levels of blockquote indentation:

>>>>>> An example tip box

An example tip box

Content Directives

Content directives allow you to embed dynamic content from the documentation system using the [[content::type]] syntax. These are rendered at build time.

The content wiki links are parsed in api/rendering/WikiLinksRenderer.cfc and dispatched via the renderContent() method in api/data/DocTree.cfc, which maps each content type to a renderer CFC in api/rendering/content/. To add a new content directive, add a case to the switch statement in renderContent() and create a corresponding CFC in that directory.

System Properties / Environment Variables

To render the details for a single system property or environment variable inline:

[[content::sysprop-envvar#LUCEE_EXTENSIONS_INSTALL]]

To render the full listing of all system properties and environment variables, grouped by category:

[[content::sysprop-envvar-listing]]

The sysprop-envvar-for-tag and sysprop-envvar-for-function directives are used automatically in the tag and function reference templates to show related system properties.

Latest Recipes

To render a list of the latest recipe pages:

[[content::latest-recipes]]

Latest Changelog

To render a list of the most recently introduced tags, functions, arguments and attributes (default 20 items, sorted by introduced version descending):

[[content::latest-changelog]]

Pass a custom limit via the hash parameter:

[[content::latest-changelog#10]]

Inline Page References

In addition to the plain cross-reference [[page-id]], the ::modifier suffix renders a page's content inline rather than as a link.

::inline

Renders a compact block with the linked title and a short description (from the page's frontmatter, or the first paragraph of the body). Works with any page type. For function and tag pages the usage signature is appended in a code block:

[[function-mavenexists::inline]]
[[tag-http::inline]]
[[recipe-docker-onbuild::inline]]

::signature

Renders just the signature in a code block — no title, no description. Useful when the surrounding prose already names the function or tag:

[[function-abs::signature]]
[[tag-query::signature]]

::signature only supports function and tag pages. The signature is produced by getUsageSignature() on the page object — the same call used by the function and tag page templates — so tags with many attributes will emit the full multi-line signature.

The ::modifier suffix is parsed in api/rendering/WikiLinksRenderer.cfc and dispatched through renderContent() in api/data/DocTree.cfc just like the content:: directives above, which makes it cheap to add new modifiers.

Front Matter

Front matter adds metadata that the build system uses for cross referencing, navigation, search indexing and rendering.

Two formats are supported depending on page type:

• YAML — used by guides, reference pages, categories, and most content under /docs/. Three dashes --- at the top of the file, a YAML block, then three dashes on their own line.
• JSON in HTML comment — used by recipe pages under /docs/recipes/. An HTML comment containing a JSON object, before the body. New recipes must also be added to /docs/recipes/index.json.

YAML example:

---
id: function-abs
title: Abs()
description: Returns the absolute value of a number.
categories:
    - number
    - math
related:
    - function-sgn
    - function-ceiling
---

JSON-in-HTML-comment example (recipes):

<!--
{
    "title": "Recipe Title",
    "id": "recipe-slug",
    "description": "One-line description.",
    "keywords": ["keyword1", "keyword2"],
    "categories": ["category-name"],
    "related": ["other-recipe-id", "function-name"]
}
-->

Both formats accept the same fields, documented below.

Required fields

Common fields

Visibility & navigation

Specialty fields

Redirecting retired pages

To retire a page without breaking inbound links, set redirect: to the id of the canonical replacement. The body is ignored — set only title (used by the stub) and redirect:

---
title: Securing Tomcat and Lucee on Windows
redirect: locking-down-lucee-server
---

The build emits a minimal HTML file at the old URL containing a <meta http-equiv="refresh">, a <link rel="canonical">, a noindex robots directive, and a body link for crawlers and no-JS clients. The matching .md export gets a one-line > This page has moved to [Title](url). notice so scripts that consume the markdown form still get a pointer to the canonical page.

Redirect pages are excluded from sitemap.xml, the search index, the recipes index, the See Also block on other pages, category landing pages, and the nav. Pointing redirect: at an id that doesn't exist in the build fails the build with an InvalidRedirectTarget error.

Cross referencing

Category links render as [[category-categoryname]]. related links render through the Markdown renderer, so they accept any valid link format including the [[page-id]] cross-reference syntax. To include surrounding quotes when using cross-reference syntax inside YAML, double-quote the value:

related:
    - "[Problem with Abs()](http://someblog.com/somearticle.html)"
    - function-sgn