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.
JSON Schema
Definition
{
"$id": "https://platen.io/schemas/platen/site/markup/details/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Defines the options for Platen's details markup\n\nhttps://platen.io/schemas/platen/site/markup/details/",
"properties": {
"aliases": {
"description": "Defines additional language IDs for the codeblock render hook.\n\nhttps://platen.io/schemas/platen/site/markup/details/#aliases",
"oneOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "string"
}
],
"title": "Aliases"
},
"classes": {
"default": [],
"description": "Add classes to details blocks unless overridden in the markup.\n\nhttps://platen.io/schemas/platen/site/markup/details/#classes",
"items": {
"type": "string"
},
"title": "Default Classes",
"type": "array"
},
"custom": {
"default": false,
"description": "Choose whether details block rendering uses a custom template.\n\nhttps://platen.io/schemas/platen/site/markup/details/#custom",
"oneOf": [
{
"type": "boolean"
},
{
"type": "string"
}
],
"title": "Use Custom Rendering Template"
},
"enabled": {
"default": true,
"description": "Choose whether details block rendering is available for the site.\n\nhttps://platen.io/schemas/platen/site/markup/details/#enabled",
"title": "Enable Details",
"type": "boolean"
},
"icons": {
"description": "Define default icons displayed on rendered details blocks.\n\nhttps://platen.io/schemas/platen/site/markup/details/#icons",
"properties": {
"collapse": {
"description": "Define an icon to display when the details block can be collapsed.\n\nhttps://platen.io/schemas/platen/site/markup/details/#collapse",
"title": "Collapse Icon",
"type": "string"
},
"expand": {
"description": "Define an icon to display when the details block can be expanded.\n\nhttps://platen.io/schemas/platen/site/markup/details/#expand",
"title": "Expand Icon",
"type": "string"
}
},
"required": [
"collapse",
"expand"
],
"title": "Default Icons",
"type": "object"
},
"linkable": {
"default": true,
"description": "Set whether rendered details blocks are linkable by default.\n\nhttps://platen.io/schemas/platen/site/markup/details/#linkable",
"title": "Make Details Blocks Linkable",
"type": "boolean"
},
"open": {
"default": true,
"description": "Set whether rendered details blocks are open by default.\n\nhttps://platen.io/schemas/platen/site/markup/details/#open",
"title": "Make Details Blocks Open",
"type": "boolean"
},
"partials": {
"description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/schemas/platen/site/markup/details/#partials",
"properties": {
"renderers": {
"description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/schemas/platen/site/markup/details/#renderers",
"properties": {
"codeblock": {
"default": "platen/markup/details/codeblock",
"description": "Adds a partial to call when processing the codeblock render hook.\n\nhttps://platen.io/schemas/platen/site/markup/details/#codeblock",
"title": "Codeblock Render Hook Partial",
"type": "string"
}
},
"title": "Renderer Partials",
"type": "object"
}
},
"title": "Markup Partials",
"type": "object"
},
"style": {
"default": "details",
"description": "Defines the markup's simple style module\n\nhttps://platen.io/schemas/platen/site/markup/details/#style",
"title": "Markup Simple Style Module",
"type": "string"
},
"use_legacy": {
"default": true,
"description": "Set whether rendered details blocks use the legacy template by default.\n\nhttps://platen.io/schemas/platen/site/markup/details/#use_legacy",
"title": "Use Legacy Template",
"type": "boolean"
},
"warn_on_legacy": {
"default": true,
"description": "Set whether Platen warns when you use the legacy template.\n\nhttps://platen.io/schemas/platen/site/markup/details/#warn_on_legacy",
"title": "Warn When Using the Legacy Template",
"type": "boolean"
}
},
"title": "Details",
"type": "object"
}Enable Details (enabled)
Choose whether the site renders codeblocks as <sl-details> (or <details> when using the
legacy template) elements, making the content semantically collapsible. The default is true.
Aliases (aliases)
Define one or more language IDs to use in addition to the default language IDs for codeblocks
that render details blocks. The default language ID is details.
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.
Use Custom Rendering Template (custom)
Choose whether details blocks are rendered with a custom template. The default value is false. When this
value is true, Platen uses the platen/markup/details/templates/custom.html partial template for the
rendering. When this value is a string, Platen uses that value as the name of the partial template in the
platen/markup/details/templates folder.
If a details markup defines the custom option, the value defined on the markup overrides this setting.
For more information, see Custom Templates.
Default Classes (classes)
You can add any number of classes to rendered details blocks by default. Specify one or more strings as items
in an array. They’re inserted for all details blocks as if they had been specified with the class
attribute or option in the markup.
If the attribute or option are specified for a details block, those values override the list defined by this setting.
Default Icons (icons)
Use this setting to define default icons for the rendered details blocks. By default, Platen renders the
details blocks with a caret that rotates when the block expands and collapses. When you define the expand and
collapse icons, those are used instead and the rotation is disabled.
This setting is only valid when using the non-legacy template.
If you define one icon, you must define the other. If you only define one icon, Platen raises a warning and ignores this setting.
To override this default in your markup, set the icon_collapse or icon_expand option to null or
an empty string ('').
Required Properties
Expand Icon (expand)
Use this setting to define an icon to display when the details block can be expanded. You can find the list of available icons in the Shoelace documentation.
If you specify a value for the icon_expand option for a details markup in your content, that
value overrides this one.
Collapse Icon (collapse)
Use this setting to define an icon to display when the details block can be collapsed. You can find the list of available icons in the Shoelace documentation.
If you specify a value for the icon_collapse option for a details markup in your content, that
value overrides this one.
Make Details Blocks Linkable (linkable)
Use this setting to configure whether details blocks are linkable by default. When the value is true, an
ID is generated and applied to rendered block so you can link directly to it. The default value is true.
If you specify the linkable option for a details markup in your content, the value of that option
overrides this setting for that details block.
For more information on how this setting affects your markup, see the documentation for the
linkable option in the markup’s reference documentation.
Make Details Blocks Open (open)
Use this option to configure whether details blocks are rendered in their open (expanded) state. Set this
value to false to render them collapsed. The default value is true.
If you specify the open option for a details markup in your content, the value of that option
overrides this setting for that details block.
Use Legacy Template (use_legacy)
Use this setting to configure whether Platen uses the legacy template for details 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 details 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
details 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.
Codeblock Render Hook Partial (codeblock)
Adds support for rendering content as collapsible blocks with a summary. This render
hook is only processed when the language ID for a codeblock is details.
It renders the codeblock’s definition inside a <details> element with
a <summary> and the content rendered in a <div.
For more information about using codeblocks to add collapsible details, see the reference documentation.
This value defaults to platen/markup/details/codeblock. You can replace it with a
different value, defining a new partial, or override the existing partial by creating
the file layouts/partials/platen/markup/mermaid/codeblock.html in your own site or
module.
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 columns created by the codeblock.
When you use the details codeblock, the following SCSS is applied:
.markdown sl-details.platen-details {
// When custom icons are used, don't rotate.
&.no-rotate-icon::part(summary-icon) {
rotate: none;
}
// Ensure the summary element doesn't have a margin - keeps the height standard.
[slot="summary"] > * {
margin: 0;
}
// Remove top padding - we always add block elements and the extra padding
// leaves too much space.
&::part(content) {
padding-top: 0;
}
}
.markdown {
details {
padding: $padding-large;
border: $padding-minimal solid var(--gray-200);
border-radius: $border-radius;
summary {
line-height: 1;
padding: $padding-large;
margin: -$padding-large;
list-style: none;
cursor: pointer;
> * {
display: inline-block;
margin: 0;
}
&::after {
float: right;
content: "+";
}
}
&[open] summary {
margin-bottom: 0;
&::after {
content: "-";
}
}
@each $name, $color in $details-colors {
&.#{$name} {
border-color: $color;
background-color: rgba($color, 0.1);
}
}
}
}
body[dir="rtl"] .markdown details summary::after {
float: left;
}You can overwrite this definition for your own site or theme by creating the file styles/markup/_details.scss
in your [assets folder][02], 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][03].