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.
JSON Schema
Definition
{
"$id": "https://platen.io/modules/platen/config/site/markup/buttons/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Defines the options for Platen's buttons markup\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/",
"properties": {
"aliases": {
"description": "Defines additional prefixes for the image render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#aliases",
"oneOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "string"
}
],
"title": "Aliases"
},
"classes": {
"default": [],
"description": "Add classes to buttons unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#classes",
"items": {
"type": "string"
},
"title": "Default Classes",
"type": "array"
},
"enabled": {
"default": true,
"description": "Whether to enable the Buttons markup option for the site\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#enabled",
"title": "Enable the markup option",
"type": "boolean"
},
"outline": {
"description": "Set whether buttons display with outlines unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#outline",
"title": "Outline Buttons by Default",
"type": "boolean"
},
"partials": {
"description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#partials",
"properties": {
"renderers": {
"description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#renderers",
"properties": {
"image": {
"default": "platen/markup/buttons/image",
"description": "Adds a partial to call when processing the image render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#image",
"title": "Image Render Hook Partial",
"type": "string"
}
},
"title": "Renderer Partials",
"type": "object"
}
},
"title": "Markup Partials",
"type": "object"
},
"pill": {
"description": "Set whether buttons display with rounded corners unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#pill",
"title": "Pill Buttons by Default",
"type": "boolean"
},
"size": {
"description": "Set a default size for buttons unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#size",
"enum": [
"small",
"medium",
"large"
],
"title": "Default Size",
"type": "string"
},
"style": {
"default": "buttons",
"description": "Defines the art markup's simple style module\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#style",
"title": "Markup Simple Style Module",
"type": "string"
},
"use_legacy": {
"default": true,
"description": "Set whether rendered link buttons use the legacy template by default.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#use_legacy",
"title": "Use Legacy Template",
"type": "boolean"
},
"variant": {
"description": "Set a default variant for buttons unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#variant",
"enum": [
"default",
"primary",
"success",
"neutral",
"warning",
"danger",
"text"
],
"title": "Default Variant",
"type": "string"
},
"warn_on_legacy": {
"default": true,
"description": "Set whether Platen warns when you use the legacy template.\n\nhttps://platen.io/modules/platen/config/site/markup/buttons/#warn_on_legacy",
"title": "Warn When Using the Legacy Template",
"type": "boolean"
}
},
"title": "Buttons",
"type": "object"
}Enable the markup option (enabled)
Choose whether the site renders image links with the button: or btn: prefix in their alt
text as buttons or normal image links. If this setting is set to true, any image links
added with the prefix are rendered as anchor (<a>) elements styled like a button.
If this setting is false, the image links are rendered as normal.
Aliases (aliases)
Define one or more prefixes to use in addition to the default prefixes (button and btn)
for button image links.
You can specify a string or an array of strings. If the value is an array, each item in the
array is added as an alias. Do not add a : suffix.
Default Classes (classes)
You can add any number of classes to rendered buttons by default. Specify one or more strings as items in an
array. They’re inserted for all buttons as if they had been specified with the class attribute in the
markup.
If the class attribute is specified for a button, that value overrides the list defined by this setting.
Default Size (size)
You can define a default size for rendered buttons. Any buttons that don’t define the size attribute
in their markup use this value. When this value is undefined and the markup doesn’t specify a size, the default
size from Shoelace (medium) is used instead.
Outline Buttons by Default (outline)
You can define whether buttons are rendered in the outline style by default. Any buttons that don’t define the
outline attribute in their markup use this value. When this value is undefined and the markup doesn’t
specify a size, the default value from Shoelace (false) is used instead.
Pill Buttons by Default (pill)
You can define whether buttons are rendered in the pill style by default. Any buttons that don’t define the
pill attribute in their markup use this value. When this value is undefined and the markup doesn’t
specify a size, the default value from Shoelace (false) is used instead.
Default Variant (variant)
You can define the default variant for rendered buttons. Any buttons that don’t define the
variant attribute in their markup use this value. When this value is undefined and the markup doesn’t
specify a variant, the default variant from Shoelace (default) is used instead.
Use Legacy Template (use_legacy)
Use this setting to configure whether Platen uses the legacy template for the buttons markup. The default
value is true. Set this value to false to use the new template by default.
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 this value to true and migrate your site’s custom styling and
scripting to use the new template.
If you use the legacy option for buttons markup in your content, this value is overriden by that
option.
For more information, see Legacy Template in the reference documentation for this markup.
Warn When Using the Legacy Template (warn_on_legacy)
Use this setting to configure whether Platen raises a warning when you use a legacy template for your
buttons markup. Set this value to false to disable the warning. The default value is true.
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 more information, see Legacy Template in the reference documentation for this markup.
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 and markup options are checked one after the other unless they return a render string. Only the first applicable partial that returns a render string is processed and rendered.
Image Render Hook Partial (image)
Adds support for rendering image links as buttons in Platen. This render hook is
only called if the alt text for the image (i.e. ) has
the button: or btn prefix. If the image link does have the prefix, it’s
processed for adding an anchor ([sref:<a>]) element styled as a button. Activating
the button takes the site visitor to the page defined by the source input.
For more information about how to use this render partial, see the reference documentation for this render hook.
For more information about defining codeblock render hook partials, see Defining a Codeblock Render Hook Partial in the Theme Guide.
Markup Simple Style Module (style)
Defines default styling for buttons created by render hooks.
When you use a button render hook, the following SCSS is applied:
.markdown a.platen-btn {
display: inline-block;
font-size: $font-size-medium;
color: var(--color-link);
line-height: $padding-large * 2;
padding: 0 $padding-large;
border: $padding-minimal solid var(--color-link);
border-radius: $border-radius;
cursor: pointer;
&:hover {
text-decoration: none;
}
}The button is created as an anchor (<a>) element with the platen-btn class.
It sets the display to inline-block so the button can be added in the body text of
a paragraph. It sets the font-size to the value of $font-size-medium, the text
color to light_css.color-link or dark_css.color-link depending on the value
of the theme.config.mode setting.
It sets the horizontal padding for the button to $padding-large and the line height
to twice that value.
It adds a minimal solid border with the width set to $padding-minimal, the color to
either light_css.color-link or dark_css.color-link, and the radius to
$border-radius.
It ensures that the cursor is a normal pointer and that no text decoration is added when a site visitor hovers on the button.
You can overwrite this definition for your own site or theme by creating the file
styles/markup/_buttons.scss in your assets folder, which defaults to assets in
your project root.
You can also create a new style module in the styles/markup folder and set this value to
that module’s name. If you do, omit the leading _ and trailing .scss. For example, the
name for the style module assets/styles/markup/_foo.scss is foo.
Note that if you override the style module or this setting,you entirely overwrite the default from the theme.
For more information on authoring SCSS, see the learning guide.