Markup

This section documents the special markup that Platen supports. The markup transforms your Markdown without requiring the use of shortcodes or inline HTML, meaning you can write more normal Markdown while still adding non-standard blocks and elements to your site. Platen supports special markup for codeblocks, headings, images (both block and inline), and links.

Codeblocks, headings, and block images support using attributes to pass options to the markup outside of your site or page configuration. For more information, see the Attributes section.

Codeblocks #

A codeblock normally highlights the plain text source code placed inside it. Platen uses codeblocks for rendering blocks of text, like adding tabs or columns, and converting non-Markdown text, like turning KaTeX markup into formulas or Mermaid markup into diagrams.

In Markdown, a codeblock is specified with three or more backticks (```) followed by a language ID. In addition to providing syntax highlighting for many code languages through Hugo, Platen supports specific language IDs to transform your input.

Generally, Codeblocks use this syntax:

```<language_id>
<definition>
```

Platen’s markup codeblocks use this syntax:

```<language_id> { <attributes>}
---
<options>
---
<definition>
```

In addition to attributes, Platen’s markup that use codeblocks also all support passing options as a YAML block wrapped in lines that only have triple dashes (---). This is a more readable alternative to attributes, which are limited to a single line for codeblocks and only support basic types of values.

You can use attributes and the option block together, but it’s best practice to only use one of them for a codeblock.

Options are always defined and documented for each codeblock markup.

Headings #

Headings are used to add semantic structure to a page. They create a <h1>–<h6> heading element. This paragraph is immediately beneath an <h2> element.

In Markdown, a heading is specified with one or more hashes (#) followed by a space and then the heading’s text and an optional declaration of attributes in curly braces ({}).

Generally, headings use this syntax:

### <text>

Platen’s markup headings use this syntax:

### <text> { <attributes> }

Platen’s markup headings always use an attribute to tell Platen to render the heading differently than default. If your heading doesn’t have any attributes, you can be sure it will render normally.

For more information about how attributes work, see the Attributes section.

Image Links #

Markdown supports adding images to your pages with alt text and an optional title as an image link. You can add image links inline (inside a paragraph, table, or other block element) or as a block of their own.

Generally, image links use this syntax:

![alt_text](source 'title')

Image Reference Links

You can also write image links with references. This is useful when the source is reused multiple times. Instead of adding the parentheses after the alt text with the source (and optional title), add square brackets ([]) with a reference id. At the bottom of your Markdown, define the reference id by adding it, followed by a colon (:) and then the source and optional title.

For example, these two links are equivalent:

<!--   Basic Image Link   -->
![Platen Logo](/images/logo.svg)

<!-- Image Reference Link -->
![Platen Logo][01]

<!-- Reference Definition -->
[01]: /images/logo.svg

The syntax for image reference links is:

![alt_text][reference_id]

[reference_id]: source 'title'

The reference definition can be anywhere in the file, but it’s best practice to define all of them at the end of the file. You can use whatever ID you want for a reference link. Generally, shorter names break the flow of your Markdown less.

Inline Image Links #

By default, inline image links may break the flow of their containing block element. Some of Platen’s markup uses inline image links to insert HTML into a block element without breaking the flow, like the markup for buttons.

Platen’s markup for inline image links use this syntax:

![prefix:alt_text](source 'title')

Platen’s markup that uses inline image links always requires a prefix that ends with a colon (:) that tells Platen which markup it should treat the image link as. Image links without a prefix or with an unrecognized prefix are always treated as normal image links.

Inline image links don’t have attributes and are usually less flexible than block image links.

Block Image Links #

Platen’s markup for block image links use this syntax:

![prefix:alt_text](source 'title')
{ <attributes> }

Platen’s markup that uses block image links always requires a prefix that ends with a colon (:) that tells Platen which markup it should treat the image link as. Image links without a prefix or with an unrecognized prefix are always treated as normal image links.

Block image links can have attributes to add more options for how the markup is used. For more information, see the Attributes section.

Links #

Markdown supports adding linked text to your pages with an optional link title.

Links use this basic syntax:

[text](destination 'title')

Platen’s markup for links use this syntax:

[prefix:text](destination 'title')

Platen’s markup that links always requires a prefix that ends with a colon (:) that tells Platen which markup it should treat the link as. Links without a prefix or with an unrecognized prefix are always treated as normal links.

Links don’t have attributes.

Attributes #

Platen supports passing attributes to Markdown blocks, like tables, lists, and paragraphs. They can’t be passed to inline elements like links or images inside a paragraph.

Unless otherwise stated, all of Platen’s special markup and all Markdown block elements support using attributes to set the rendered markup’s or element’s [sref:id][saa] attribute and add to its [sref:class] attribute.

Attributes are always declared wrapped in curly braces ({}). Except for codeblocks, the attributes may span multiple lines, which can make them easier to read.

The ID attribute is always specified with a hash (#) prefix. For example, to add the ID cool-pic to an image, you would use #cool-pic:

![alt_text](source)
{ #cool-pic }

You can add any number of classes by including them in the attribute declaration with a dot (.) prefix. For example, to add the classes foo, bar, and baz to a codeblock, you would use .foo, .bar, and .baz:

```html { .foo .bar .baz }
<p>An example HTML codeblock</p>
```

Other attributes may be added as key-value pairs separated by an equals sign (=). For example, to pass the attribute collapse as true for a heading, you would use collapse=true:

## A Very Long Section { collapse=true }

A few notes on values for key-value pairs in attributes:

If the value should be boolean (either true or false) or a number, don’t wrap the value in quotes.
If the value is a string of text, wrap the value in either single (') or double (") quotes.

How the attributes are used depends on each markup’s syntax.

Available Markup #

This section includes the list of available markup for Platen. For more information on any of them, see their documentation.

Alerts: Documentation on adding alerts to your content with a codeblock.
Art: Documentation on adding artwork to your content with an image link.
Buttons: Documentation on the button image link markup, which renders an image link as a button.
Columns: Documentation on the columns language ID for codeblocks, which enables you to format content in multiple columns on a page.
Details: Documentation on the details language ID for codeblocks, which adds a details and summary HTML tag to a Markdown page for semantically collapsible content.
Itch Embeds: Documentation on the itch image link markup, which embeds an iframe linking to the itch page for a project.
KaTeX Formulas: Documentation on using math markup to include formulas in your text.
Mermaid Diagrams: Documentation on the mermaid language ID for codeblocks, which renders Mermaid markup on a content page, allowing you to include flowcharts and other diagrams.
Section Lists: Documentation on the section language ID for codeblocks, which adds a list of links to pages in a content section with their summary to provide context for those pages.
Styled Text: Documentation on the styled image link markup, which renders an image link’s text as a styled span.
Subscripts: Documentation on the sub image link markup, which renders an image link’s text as subscript.
Superscripts: Documentation on the sup image link markup, which renders an image link’s text as superscript.
Tabs: Documentation on the tabs language ID for codeblocks, which enables you to format content as tabs in a card pane on a page.