Settings

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.

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:
        - operatic

Pages 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.

Edit this page