Display Settings (settings)
The Platen display settings control how the Platen site is structured and displays, separate from the SCSS styling.
JSON Schema
Definition
{
"$id": "https://platen.io/schemas/platen/site/display/settings/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "Optional settings controlling how a Platen site is structured.\n\nhttps://platen.io/schemas/platen/site/display/settings/",
"properties": {
"date_format": {
"default": "January 2, 2006",
"description": "Specifies the format for dates on the site.\n\nhttps://platen.io/schemas/platen/site/display/settings/#date_format",
"oneOf": [
{
"enum": [
":date_full",
":date_long",
":date_medium",
":date_short",
":time_full",
":time_long",
":time_medium",
":time_short"
]
},
{
"type": "string"
}
],
"title": "Date Format"
},
"header": {
"description": "Controls the rendering of the header element for site pages.\n\nhttps://platen.io/schemas/platen/site/display/settings/#header",
"properties": {
"title_as_heading": {
"default": false,
"description": "Specify whether the page title should be rendered as an h1 instead of strong.\n\nhttps://platen.io/schemas/platen/site/display/settings/#title_as_heading",
"title": "Render Page Title as Heading",
"type": "boolean"
}
},
"title": "Page Header Settings",
"type": "object"
},
"logo": {
"description": "Defines the branding logo for the site.\n\nhttps://platen.io/schemas/platen/site/display/settings/#logo",
"properties": {
"url": {
"description": "Specifies the path to the logo to use for the site's branding.\n\nhttps://platen.io/schemas/platen/site/display/settings/#url",
"title": "Logo URL",
"type": "string"
}
},
"title": "Site Logo",
"type": "object"
},
"menu": {
"$ref": "https://platen.io/schemas/platen/site/display/menu/settings/schema.json"
},
"mobile": {
"$ref": "https://platen.io/schemas/platen/site/display/mobile/schema.json"
},
"section_classes": {
"description": "Adds CSS classes to sections by URL prefix\n\nhttps://platen.io/schemas/platen/site/display/settings/#section_classes",
"patternProperties": {
".": {
"description": "Fiddle fart foo bagel\n\nhttps://platen.io/schemas/platen/site/display/settings/#.",
"items": {
"type": "string"
},
"title": "Section Class List",
"type": "array",
"uniqueItems": true
}
},
"title": "Extra CSS Classes for Sections",
"type": "object"
},
"table_of_contents": {
"description": "Controls the rendering of the table of contents for site pages.\n\nhttps://platen.io/schemas/platen/site/display/settings/#table_of_contents",
"properties": {
"maximum_level": {
"default": 4,
"description": "Specify the maximum heading level to include in Platen's table of contents.\n\nhttps://platen.io/schemas/platen/site/display/settings/#maximum_level",
"maximum": 6,
"minimum": 1,
"title": "Maximum Heading Level",
"type": "integer"
},
"minimum_level": {
"default": 2,
"description": "Specify the minimum heading level to include in Platen's table of contents.\n\nhttps://platen.io/schemas/platen/site/display/settings/#minimum_level",
"maximum": 6,
"minimum": 1,
"title": "Minimum Heading Level",
"type": "integer"
},
"ordered_list": {
"default": false,
"description": "Specify whether table of contents entries should render in an ordered list.\n\nhttps://platen.io/schemas/platen/site/display/settings/#ordered_list",
"title": "As Ordered List",
"type": "boolean"
},
"render": {
"default": true,
"description": "Whether to render the table of contents for the site's content\n\nhttps://platen.io/schemas/platen/site/display/settings/#render",
"title": "Render the Table of Contents",
"type": "boolean"
},
"use_built_in": {
"default": false,
"description": "Choose whether to use Hugo's builtin table of contents.\n\nhttps://platen.io/schemas/platen/site/display/settings/#use_built_in",
"title": "Use Built-In",
"type": "boolean"
}
},
"title": "Table of Contents",
"type": "object"
}
},
"title": "Display Settings",
"type": "object"
}Date Format (date_format)
Specifies the date-time format on the site. You can specify a shorthand value, like
:date_full, or a example string Jan 2 2006.
The default value is January 2, 2006.
Page Header Settings (header)
Controls the rendering of the header element for site pages. By default, every page is
rendered with a header element that includes the controls for displaying the menu and table
of contents in mobile view and the page’s title in a <strong> element.
You can use the title_as_heading option to write the page’s title as an <h1>
instead.
Render Page Title as Heading (title_as_heading)
Use this setting to specify whether the page title should be rendered as an <h1>
element instead of the default <strong> element.
If this set to true, Platen renders the title text in an <h1> with the ID set to
the title, downcased and urlized.
When the page title is rendered as a heading, it’s always visible, even when not in mobile view.
Site Logo (logo)
Defines the logo for the site. The logo is added to the site menu before the site’s name.
Logo URL (url)
Defines the path to the logo file. You can specify the path to an image in the assets
folder for your site, a site-relative path to the file in your static folder, or to
a remote image. You can also set this value to an empty string to remove the logo from
the site menu entirely.
We recommend placing your logo in the assets folder for best results and the static
folder for ease-of-use. We don’t recommend you use a remote image for your site’s logo
due to site performance impacts.
This value isn’t set by default.
Site Menu Settings (menu)
The Platen display options control how the Platen site’s menu is structured and displays.
With the root_section setting, you can define a content folder to add to the site menu as
the main section.
With the before_injection, before_hugo_config, before_root_section,
after_root_section, after_hugo_config, and after_injection settings
(collectively, the menu position settings), you can use Platen features to add entries to
the site’s menu in one of several locations using a partial defined for the feature.
In addition to the position settings, feature module authors can define any settings that make sense for their functionality, such as top-level defaults that apply to every position unless overridden.
For more information on how to define these settings, see Defining a Feature Menu Entry.
For more information on how this setting is used internally and how to define a feature that can
support these menu items, see partials.menu in Defining Features.
For more information, see Site Menu Settings
Site Mobile Display Settings (mobile)
The Platen display options control how the site displays on smaller screens.
For more information, see Site Mobile Display Settings
Extra CSS Classes for Sections (section_classes)
Defines a set of sections and the CSS classes to inject in the body element for every page
in that section. This enables you to add styling to an entire section quickly without
editing your theme. By default, the body element has no classes added to it.
The keys for this option should be the section’s URL prefix without the
leading slash (/). For example, for the section defined in the content/games/space/opera
folder, the key name would be games/space/opera.
The values for this option should always be a list of classes to add to the body element.
When a section matches multiple keys in this setting, all classes added by those keys are
added to the page.
For example, given this configuration:
platen:
display:
section_classes:
games:
- playful
games/space:
- techno
games/space/opera:
- operaticPages in defined in the content/games/space/opera folder would get the attribute
class="playful techno operatic" added to their body element.
Pattern Properties
Section Class List (Pattern: .)
Specify one or more classes to add to the body element for pages in the section.
Table of Contents (table_of_contents)
Controls the rendering of the table of contents for site pages. You can choose whether to use Platen’s table of contents generator or Hugo’s. If you’re using Platen to generate the table of contents, you can set the minimum and maximum heading levels to include.
By default, the site is set to use Platen to generate the table of contents and include heading levels 2–4.
Use Built-In (use_built_in)
Choose whether to use Hugo’s builtin table of contents or generate them with Platen.
Hugo’s builtin table of contents only includes markdown headings, not HTML headings added in shortcodes. For more information on configuring the behavior for Hugo’s builtin table of contents, see Table of Contents in the Hugo documentation
Platen’s table of contents includes all headings, HTML and Markdown, as long as they’re
within the specified values for minimum_level and
maximum_level, inclusive.
The default is false and the site use’s Platen to generate the table of contents.
Render the Table of Contents (render)
Specifies whether to render the table of contents for the site’s content.
To prevent the table of contents from rendering for a page, set this value to false.
To render the table of contents for a page when it’s disabled at the site level, set
this value to true.
The default value is true.
Minimum Heading Level (minimum_level)
Specify the minimum heading level to include in Platen’s table of contents. This value
only affects the table of contents when use_built_in is set to false.
Headings at a lower level than this value aren’t included in the table of contents. For
example, when this is set to 3, first and second level Markdown and HTML headings
aren’t included in the table of contents.
This value must be less than or equal to the value of maximum_level.
The default is 2.
Maximum Heading Level (maximum_level)
Specify the maximum heading level to include in Platen’s table of contents. This value
only affects the table of contents when use_built_in is set to false.
Headings at a higher level than this value aren’t included in the table of contents. For
example, when this is set to 4, fifth and sixth level Markdown and HTML headings
aren’t included in the table of contents.
This value must be greater than or equal to the value of minimum_level.
The default is 4.
As Ordered List (ordered_list)
Specify whether the table of contents should render its entries in an ordered list with numerals before each item. By default, the table of contents is rendered in an unordered list without any list markers, only with indents.
Set this value to true to add the entries in an ordered list instead.
This value can be overridden on a per-page basis.