Site Configuration (config)

Site Comments Feature (comments)

Settings that control the site’s commenting feature.

For more information, see Site Comments Feature

Portable Links Feature (portable_links)

Settings that control the site’s portable links feature.

For more information, see Portable Links Feature

Progressive Web Application Feature (pwa)

Settings that control the site’s progressive web application feature.

For more information, see Progressive Web Application Feature

Site Search Feature (search)

Settings that control the site’s search feature.

For more information, see Site Search Feature

Shoelace Feature Options (shoelace)

Platen is in the process of more closely integrating the excellent set of web components from Shoelace into the site theme. This gives you a set of very configurable and customizable components to use on your site and in your markup.

For more information, see Shoelace Feature Options

Pattern Properties

Defining Features (pattern-any)

Platen and its modules include several features that you can use in your site. These settings control their behavior.

For more information, see Defining Features

Pattern Properties

Defining a Registered Shortcode (pattern-any)

Defines the minimal properties a theme developer needs to define for a shortcode to integrate with Platen’s configuration, automatically and dynamically loading styles without requiring the end users to update their own site configuration or assets. and adding site-level control over the shortcode behaviors.

Platen, through the site configuration, keeps a registry of integrated shortcodes. This enables site authors and theme developers to discover, enable, disable, and configure shortcodes in a friendlier way than Hugo’s default, without preventing Hugo’s built-in behavior.

At a minimum, every registered shortcode must define the enabled setting. If the shortcode has specific styling needs, it must define the style setting with the name property set to the name of the style module in assets/styles/shortcodes, like tabs for the style module at assets/styles/shortcodes/_tabs.scss.

A registered shortcode’s style asset must be placed in the assets/styles/shortcodes folder.

In addition to these properties, any registered shortcode may define any other settings that make sense for it. Theme developers should use these settings to provide sensible defaults that are meant to be overridden.

For more information on developing a registered shortcode for Platen, see Defining a Registered Shortcode in the Theme Guide.

For more information, see Defining a Registered Shortcode

JSON Schema

{
  "description": "Configure custom markdown for Platen.\n\nhttps://platen.io/schemas/platen/site/config/",
  "patternProperties": {
    ".": {
      "$ref": "https://platen.io/schemas/platen/site/markup/defining/schema.json"
    }
  },
  "properties": {
    "art": {
      "$ref": "https://platen.io/schemas/platen/site/markup/art/schema.json"
    },
    "buttons": {
      "$ref": "https://platen.io/schemas/platen/site/markup/buttons/schema.json"
    },
    "columns": {
      "$ref": "https://platen.io/schemas/platen/site/markup/columns/schema.json"
    },
    "details": {
      "$ref": "https://platen.io/schemas/platen/site/markup/details/schema.json"
    },
    "itch": {
      "$ref": "https://platen.io/schemas/platen/site/markup/itch/schema.json"
    },
    "katex": {
      "$ref": "https://platen.io/schemas/platen/site/markup/katex/schema.json"
    },
    "mermaid": {
      "$ref": "https://platen.io/schemas/platen/site/markup/mermaid/schema.json"
    },
    "section": {
      "$ref": "https://platen.io/schemas/platen/site/markup/section/schema.json"
    },
    "styled_text": {
      "$ref": "https://platen.io/schemas/platen/site/markup/styled_text/schema.json"
    },
    "subscripts": {
      "$ref": "https://platen.io/schemas/platen/site/markup/subscripts/schema.json"
    },
    "superscripts": {
      "$ref": "https://platen.io/schemas/platen/site/markup/superscripts/schema.json"
    },
    "tabs": {
      "$ref": "https://platen.io/schemas/platen/site/markup/tabs/schema.json"
    }
  },
  "title": "Markup Options",
  "type": "object"
}

Art (art)

Defines the map of options for Platen’s art markup. The existing value is a map that includes whether or not to enable the image render hook and its style definition.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Art

Buttons (buttons)

Defines the map of options for Platen’s buttons markup. The existing value is a map that includes whether or not to enable the image render hook and its style definition.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Buttons

Columns (columns)

Defines the map of options for Platen’s columns markup. The existing value is a map that includes whether or not to enable the option and the style definition for it.

When this markup is enabled, you can create columns for content on a page with a codeblock.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Columns

Details (details)

Defines the map of options for Platen’s details markup. The existing value is a map that includes whether or not to enable the codeblock render hook and its style definition.

When this markup is enabled, you can add semantically collapsible content to a page with a codeblock.

Note that Platen is migrating from the legacy template to a new template that uses Shoelace to add a more customizable and extensible element to your site.

The legacy template has a more limited set of options than the new default template and it will eventually be removed. We strongly recommend you set use_legacy to false and migrate your site’s custom styling and scripting to use the new template.

For now, Platen defaults to using the legacy template but warns you that the legacy template will eventually be removed. You can silence this warning by setting warn_on_legacy to false.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Details

Itch (itch)

Defines the map of options for Platen’s itch embed markup. The existing value is a map that includes whether or not to enable the image render hook and its style definition.

When this markup is enabled, you can embed itch.io widgets into your site with an image link.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Itch

KaTeX Markup (katex)

Defines the map of settings for the Platen’s KaTeX markup option. The existing value is a map that includes whether or not to enable the markup rendering, whether to always load the libraries on every page, and which version of KaTeX to use.

When this markup is enabled, you can use KaTeX markup in your content with an image link (that has the chem:, katex:, or math: prefix), codeblock (whose language ID is chem, katex, and math), and even with KaTeX’s own open/closing tags in normal Markdown content if always_load is set to true.

With KaTeX, you can write mathematical and chemical formulae in plaintext and render them as beautiful formula on your site.

You can override some of these settings at a content-level.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see KaTeX Markup

Mermaid Diagrams (mermaid)

Defines the map of settings for the Platen’s Mermaid diagrams markup option. The existing value is a map that includes whether or not to enable the markup rendering, which version of Mermaid to use, and what container element to render the diagrams in by default.

With this markup enabled, you can use Mermaid to create diagrams including flowcharts, pie charts, and sequence diagrams with a codeblock.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Mermaid Diagrams

Section Lists (section)

Defines the map of options for Platen’s section lists markup. The existing value is a map that includes whether or not to enable the codeblock render hook and its style definition.

When this markup is enabled, you can create a description list for pages in a section of your site with a codeblock.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Section Lists

Styled Text (styled_text)

Defines the map of options for Platen’s Styled Text markup. The existing value is a map that includes whether or not to enable the image render hook and its style definition.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Styled Text

Subscripts (subscripts)

Defines the map of options for Platen’s subscripts markup. The existing value is a map that includes whether or not to enable the image render hook and its style definition.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Subscripts

Superscripts (superscripts)

Defines the map of options for Platen’s superscripts markup. The existing value is a map that includes whether or not to enable the image render hook and its style definition.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Superscripts

Tabs (tabs)

Defines the map of options for Platen’s tabs markup. The existing value is a map that includes whether or not to enable the codeblock render hook and the style definition for it.

When this markup is enabled, you can create tabbed content on a page with a codeblock.

Note that Platen is migrating from the legacy template to a new template that uses Shoelace to add a more customizable and extensible element to your site.

The legacy template has a more limited set of options than the new default template and it will eventually be removed. We strongly recommend you set use_legacy to false and migrate your site’s custom styling and scripting to use the new template.

For now, Platen defaults to using the legacy template but warns you that the legacy template will eventually be removed. You can silence this warning by setting warn_on_legacy to false.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

For more information, see Tabs

Pattern Properties

Defining Custom Markup (pattern-any)

Platen site and theme developers sometimes need to override how codeblocks, images, links, and headers are rendered into HTML for a page. These settings allow developers to add new rendering options.

Defined markup renderers must follow these conventions or they’ll break rendering for users:

1. They must analyze the incoming parameters to see if the renderer should be applied in this instance. For example, a link renderer might check for a foo: prefix in the link text and skip any links without that prefix.

2. They must return a string value.

   1. When an instance is skipped by a renderer, it must return an empty string "".
   2. When an instance is processed by a renderer, it must return the HTML. There’s no need to specify safeHTML for the return text.

Only one renderer can be successfully applied to an instance. When a renderer returns a non-empty string representing the rendered instance, all remaining renderers are skipped and the default renderer isn’t applied.

If no renderers apply to an instance, the default renderer is used instead.

For more information, see Defining Custom Markup