Markdown Extensions

Under the hood, Resonance uses the League\Commonmark library. By default, it has several plugins enabled. Resonance's Static Site Generator requires those extensions, and thus, you should not disable them:

• Description Lists
• External Links
• Github-Flavored Markdown
• Heading Permalinks

Besides those plugins that are distributed with League\Commonmark, Resonance adds a few custom extensions.

Admonitions

Adomnitions follow the Docusaurus syntax (three colons, then type string).

For example, this markdown code:

markdown
:::my-admonition-type
My admonition.
:::

Is going to be transformed into:

<div class="admonition admonition--my-admonition-type">
My admonition.
</div>

The admonition type is arbitrary; you can name it in any way you need. To customize them, you need to use CSS. A few types of admonitions are styled by default:

Linking Pages

You can use the {{page-reference}} syntax to link between pages.

For example, let's assume there is a test.md page with the following contents:

yaml
---
title: My Page
description: My Description
layout: dm:document
---

Hello!

Using {{test}} is going to produce the following link:

<a href="/test.html">My Page</a>

Table of Contents

This is not an extension; instead, it's a library that can process the League\Commonmark parsed document to build the Table of Contents from the headings it finds.

It's used in the default document layout to generate the table of contents.

You can use it programmatically like so:

php
<?php

use League\CommonMark\Output\RenderedContent;
use Distantmagic\Resonance\CommonMarkTableOfContentsBuilder;

$tableOfContentsBuilder = new CommonMarkTableOfContentsBuilder();

/**
 * @var RenderedContent $renderedOutput
 */
$renderedDocument = $renderedOutput->getDocument();

$tableOfContentsLinks = $tableOfContentsBuilder->getTableOfContentsLinks($renderedDocument);

foreach ($tableOfContentsLinks as $link) {
    $link->level; // nesting level
    $link->slug; // to be used in the url #hash
    $link->text; // text contents of a heading
}