Skip to main content

Using Markdown

Markdown is used to structure content and is converted to HTML by using the remarkable parser.

Front matter​

website-generator supports front matter in Markdown files written in TOML. The front matter is parsed using gray-matter.

important

Only the +++ front matter delimiter is supported: --- and other variants will not work.

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

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

Reserved front matter​

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 support shortcodes, which are reusable snippets of HTML defined in the shortcodes directory.

Shortcodes are user-defined; website-generator does not come with any set by default. See Creating shortcodes for more information.