Markdown

Parser

Markdown is rendered using the remarkable parser.

Front matter

website-generator supports Markdown with front-matter written in TOML using gray-matter. Only front-matter defined by the +++ delimiter is supported.

Any front-matter within Markdown is available for use within templates under a page variable (see Template variables).

Additionaly, there are front-matter options that allow website-generator to perform advanced tasks during the build process.

toc

The toc front-matter generates a table of contents (in Markdown) for the section or page to render:

+++
toc: true
+++

Add the following Handlebars block to a section or page template to display the table of contents:

{{#if page.toc}}
  <h2>Table of contents</h2>
  {{&page.toc}}
{{/if}}

For example, the following Markdown:

+++
toc: true
+++

## Heading
Content

### Subheading
Content

## Another heading
Content

…will update the page.toc variable to be:

1. [Heading](#heading)
    - [Subheading](#subheading)
2. [Another heading](#another-heading)

The table of contents is generated by the markdown-toc library.

url

The url front-matter overrides the default output URL for a section or page:

+++
url: custom-url
+++

The value of url will rename the directory relative to the section or page.

warning

URL overrides are in an experimental stage. They will work correctly when used at a root section level but multiple, nested URL overrides may produce unexpected results.

If the following URL override is defined in /content/section/_index.md:

+++
url: override
+++

…the output folder structure will be build/override/index.html instead of build/section/index.html.

If there are other pages and assets such as content/section/page.md and content/section/asset.jpg, they will also be output to build/override/.

Use a single forward slash (/) to remove a directory altogether:

+++
url: /
+++

This would make the output URL for content/section/_index.md become build/index.html, which is useful for organising content within a folder but rendering the HTML output outside of that folder, e.g. storing all blog posts within content/blog and using the URL override of / to make all blog posts available at the root of the website, without blog in the URL.

Shortcodes

Markdown files in website-generator also support shortcodes, which are defined in the shortcodes directory (see Shortcodes).

Shortcodes are entirely user-defined (website-generator does not come with any set by default) and are used to extend Markdown to create reusable snippets of patterns and logic.

An example of a Markdown shortcode in website-generator is:

Content outside of a shortcode

An inline shortcode:
{{%inline-shortcode/%}}

A block shortcode, which accepts its own Markdown content:
{{%block-shortcode%}}
This content will be available in the block shortcode.
{{%/block-shortcode%}}