Defining Custom Markup (defining)
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:
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.They must return a string value.
- When an instance is skipped by a renderer, it must return an empty string
"". - When an instance is processed by a renderer, it must return the HTML. There’s no need to
specify
safeHTMLfor the return text.
- When an instance is skipped by a renderer, it must return an empty string
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.
JSON Schema
Definition
{
"$id": "https://platen.io/modules/platen/config/site/markup/defining/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Defines a valid markup renderer for Platen\n\nhttps://platen.io/modules/platen/config/site/markup/defining/",
"properties": {
"enabled": {
"description": "Whether the markup renderer should be used for content.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#enabled",
"title": "Enable the Markup",
"type": "boolean"
},
"partials": {
"description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#partials",
"properties": {
"header": {
"description": "Injects a partial into the HTML header.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#header",
"title": "Header Partial",
"type": "string"
},
"renderers": {
"description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#renderers",
"properties": {
"codeblock": {
"description": "Adds a partial to call when processing the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#codeblock",
"title": "Codeblock Render Hook Partial",
"type": "string"
},
"heading": {
"description": "Adds a partial to call when processing the heading render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#heading",
"title": "Heading Render Hook Partial",
"type": "string"
},
"image": {
"description": "Adds a partial to call when processing the image render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#image",
"title": "Image Render Hook Partial",
"type": "string"
},
"link": {
"description": "Adds a partial to call when processing the link render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#link",
"title": "Link Render Hook Partial",
"type": "string"
}
},
"title": "Renderer Partials",
"type": "object"
},
"style": {
"description": "Injects a partial into the site's SCSS.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#style",
"title": "Style Partial",
"type": "string"
}
},
"title": "Markup Partials",
"type": "object"
},
"style": {
"description": "Defines the markup's simple style module\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#style",
"title": "Markup Simple Style Module",
"type": "string"
}
},
"title": "Defining Custom Markup",
"type": "object"
}Enable the Markup (enabled)
Specifies whether the markup renderer should be used for content. When adding a markup to your theme, you must define this value in the theme configuration that is merged with a site’s.
You can choose whether to default this value to true or false and a site maintainer can
override it in their own configuration.
When this value is set to true, the markup’s renderer is applied before the default
renderer. When this value is set to false, the markup’s renderer is ignored.
Markup Simple Style Module (style)
Defines the name of the markup’s style module. This setting can be omitted if the markup has no specific styling needs (if it relies on existing or otherwise defined CSS or SCSS values to style its output).
This setting is for style modules that don’t require any special handling. If you need to
pass any settings to the style module, use the partials.style setting instead.
If it needs its own SCSS, add the module to the assets/styles/markup folder and set
this value to the SCSS module’s name.
Markup Partials (partials)
Define a map of partials for Platen to inject as needed. These partials are only
injected when enabled is set to true.
Renderer Partials (renderers)
Defines a map of partials to use as Markdown render hooks. Like all partials, these are
only processed when enabled is set to true.
Supported renderer partials include:
codeblock, processed for fenced code blocks with a language IDheading, processed for headingsimage, processed for image linkslink, processed for non-image links
In all cases, all renderer partials for enabled features are checked one after the other unless they return a render string. Once an applicable partial returns a render string, no further render hook partials are processed for that specific content.
JSON Schema
Definition
{
"description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/",
"properties": {
"codeblock": {
"description": "Adds a partial to call when processing the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#codeblock",
"title": "Codeblock Render Hook Partial",
"type": "string"
},
"heading": {
"description": "Adds a partial to call when processing the heading render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#heading",
"title": "Heading Render Hook Partial",
"type": "string"
},
"image": {
"description": "Adds a partial to call when processing the image render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#image",
"title": "Image Render Hook Partial",
"type": "string"
},
"link": {
"description": "Adds a partial to call when processing the link render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/defining/#link",
"title": "Link Render Hook Partial",
"type": "string"
}
},
"title": "Renderer Partials",
"type": "object"
}Codeblock Render Hook Partial (codeblock)
If specified, this partial is processed when a fenced codeblock with a language ID is rendered from Markdown. This support is in addition to Hugo’s normal method for adding codeblock render hooks per language.
In Platen, codeblock render hook partials registered by features are processed one at a time for each enabled feature with a defined codeblock render hook partial until one of them returns a non-empty string representing the rendered content.
If no codeblock render hook partial returns a rendered string, the default codeblock render hook is called instead. The first codeblock render hook partial to return a non-empty string ends the render hook processing. Any remaining render hook partials are never processed for that codeblock.
A feature can only define one codeblock render hook partial.
For more information about defining codeblock render hook partials, see Defining a Codeblock Render Hook Partial in the Theme Guide.
Heading Render Hook Partial (heading)
If specified, this partial is processed when a heading is rendered from Markdown. This support allows you to extend the default heading render hook without replacing it. You can still define additional heading render hooks on a per-output-format basis, like a custom heading output for content in an RSS feed.
In Platen, heading render hook partials registered by features are processed one at a time for each enabled feature with a defined heading render hook partial until one of them returns a non-empty string representing the rendered content.
If no heading render hook partial returns a rendered string, the default heading render hook is called instead. The first heading render hook partial to return a non-empty string ends the render hook processing. Any remaining render hook partials are never processed for that heading.
A feature can only define one heading render hook partial.
For more information about defining heading render hook partials, see Defining a Heading Render Hook Partial in the Theme Guide.
Image Render Hook Partial (image)
If specified, this partial is processed when a image is rendered from Markdown. This support allows you to extend the default image render hook without replacing it. You can still define additional image render hooks on a per-output-format basis, like a custom image output for content in an RSS feed.
In Platen, image render hook partials registered by features are processed one at a time for each enabled feature with a defined image render hook partial until one of them returns a non-empty string representing the rendered content.
If no image render hook partial returns a rendered string, the default image render hook is called instead. The first image render hook partial to return a non-empty string ends the render hook processing. Any remaining render hook partials are never processed for that image.
A feature can only define one image render hook partial.
For more information about defining image render hook partials, see Defining a Heading Render Hook Partial in the Theme Guide.
Link Render Hook Partial (link)
If specified, this partial is processed when a link is rendered from Markdown. This support allows you to extend the default link render hook without replacing it. You can still define additional link render hooks on a per-output-format basis, like a custom link output for content in an RSS feed.
In Platen, link render hook partials registered by features are processed one at a time for each enabled feature with a defined link render hook partial until one of them returns a non-empty string representing the rendered content.
If no link render hook partial returns a rendered string, the default link render hook is called instead. The first link render hook partial to return a non-empty string ends the render hook processing. Any remaining render hook partials are never processed for that link.
A feature can only define one link render hook partial.
For more information about defining link render hook partials, see Defining a Heading Render Hook Partial in the Theme Guide.
Header Partial (header)
If specified, this partial is processed in the HTML header. This is useful for adding
standalone styles, scripts, and metadata. To add a style that uses the SCSS style
modules defined in the theme settings, add a new map to theme.styles,
specify a style partial for the markup, or use the Simple Style Module
option.
The partial is given the current page’s context.
Style Partial (style)
If specified, this partial is processed in platen.scss, which defines the site’s
style. This partial is processed after the theme’s builtin styles and feature styles,
allowing it to depend on styles defined by the theme or a feature. Use this partial to
have more control over how the style is handled, like if you need to use configuration
options.
If the style doesn’t rely on any configuration specific to the markup itself, you can use the Simple Style Module setting instead.
The partial is given the current page’s context. Note that when importing SCSS
modules from this partial, the path is relative to styles/platen.scss, not the
root of the assets folder. To import an SCSS module in assets/myMarkup, you
need to specify the path as ../myMarkup/foo, not myMarkup/foo.