Markdown

LFP Docs supports all template languages that Eleventy offers. It is recommended to use Markdown for creating documentation due to its simplicity and ease of use.

A page with minimum required setup would look like this:

---
title: Example Document
---
This is example content, written in **Markdown**.

## This is a heading

This is more content. With an [internal link](/example/page/).

Headings

Headings in Markdown are represented as lines starting with one or up to six #, mimicking HTML's six heading levels.

As a page title is given to LFP Docs via the title key in the frontmatter section, it is recommended to only use headings, starting with level 2 (as seen in the example above).

Headings automatically generate IDs by which you can reference them:

---
title: Example Document
---
## A heading

A [link](#a-heading) to the heading.

Generally, heading text gets converted to kebab-case, with hyphens replacing spaces and other special characters. When using camelCase, the word gets split at the capital letter and a hyphen gets inserted; camelCase thus becomes camel-case. For more uncommon cases, test your links during development (as is recommended with all references on your page).

Links

When linking to same-site content in Markdown, use paths relative to the output directory's root (or use the page's permalink).

Automatic input-output path mapping is not supported, though you can add this functionality with a plugin; compatibility with LFP Docs is not tested.

Shortcodes

Shortcodes are code snippets that function a lot like small functions or macros: they take some string-based input and usually return HTML that then gets rendered to the page.

You can use the following shortcodes, bundled with LFPDocs, or define your own. These shortcodes are available with LFP Docs:

• Badge
• Codeblock
• Details
• Example
• Table of Contents

Default Extensions

By default, Eleventy's Markdown processor, markdown-it, is rudimentary. This is by design, as markdown-it supports a rich extension system, which LFP Docs builds upon by introducing a couple of bespoke plugins.

GFM Alerts

For callouts and important sections, use GFM alerts. Use them like this, right in Markdown:

::: important
This is an important section.
:::

::: caution "Custom label"
An alert with custom label. Put the label text in quotes.
:::

::: note
:::

::: tip
:::

::: new
:::

And they render like this:

Multi-lingual support for alert labels is currently only allowed on a site-wide level (see configuration for lang and i18n). Consider setting a custom label for translating on a per-page basis.

Attributes

markdown-it-attrs enables the author to add attributes to HTML inside of raw Markdown.

This is helpful if there are several homonymous headings on one page and you want to reference them semantically:

### Heading {#custom-id}

-> <h3 id="custom-id"><a href="#custom-id">Heading</a></h3>

Footnotes

Footnotes are available through markdown-it-footnote and can be used like so:

This is text.^[And this is an inline footnote.]

More text.[^1]

[^1]: And another footnote.

Footnotes are automatically added to the end of the page content section.

Extending Markdown

Because Eleventy, and thus LFP Docs, uses markdown-it as Markdown processor, it can easily be extended; in your Eleventy configuration file:

// other imports
import mdExtension from 'markdown-it-your-extension';

export default function (eleventyConfig) {
  // other configuration
  eleventyConfig.amendLibrary('md', mdLib => {
    mdLib.use(mdExtension),
    // options go here, if your extension supports them
  });
  // more configuration
}

Other Supported Languages

Other than Markdown, LFP Docs supports the following languages:

• plain HTML (useful when designing unique pages, such as a landing page)
• JavaScript (as 11ty.js)
• Liquid
• Nunjucks

See Eleventy's page on languages for more information. You can use the language that suits your needs best, or use them interchangeably.