Tabs (`tabs`)

Defines the map of options for Platen’s tabs markup. The existing value is a map that includes whether or not to enable the codeblock render hook and the style definition for it.

When this markup is enabled, you can create tabbed content on 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.

Metadata

ID: https://platen.io/modules/platen/config/site/markup/tabs/schema.json
Type: object

JSON Schema

Definition

{
  "$id": "https://platen.io/modules/platen/config/site/markup/tabs/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Defines the options for Platen's tabs markup\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/",
  "properties": {
    "activation": {
      "default": "auto",
      "description": "Specify whether tabs should be automatically shown on navigation or require manual activation to show.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#activation",
      "enum": [
        "auto",
        "manual"
      ],
      "title": "Default Activation Mode",
      "type": "string"
    },
    "aliases": {
      "description": "Defines additional language IDs for the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#aliases",
      "oneOf": [
        {
          "items": {
            "oneOf": [
              {
                "description": "A map defining either/both an alias for the grouping and entry codeblock language ID.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/",
                "properties": {
                  "entry": {
                    "description": "Alias for the nested codeblock language ID, (default is 'tab').\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#entry",
                    "title": "Entry Alias",
                    "type": "string"
                  },
                  "group": {
                    "description": "Alias for the top-level codeblock language ID, (default is 'tabs').\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#group",
                    "title": "Group Alias",
                    "type": "string"
                  }
                },
                "type": "object"
              },
              {
                "type": "string"
              }
            ]
          },
          "type": "array"
        },
        {
          "description": "A map defining either/both an alias for the grouping and entry codeblock language ID.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/",
          "properties": {
            "entry": {
              "description": "Alias for the nested codeblock language ID, (default is 'tab').\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#entry",
              "title": "Entry Alias",
              "type": "string"
            },
            "group": {
              "description": "Alias for the top-level codeblock language ID, (default is 'tabs').\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#group",
              "title": "Group Alias",
              "type": "string"
            }
          },
          "type": "object"
        },
        {
          "type": "string"
        }
      ],
      "title": "Aliases"
    },
    "classes": {
      "default": [],
      "description": "Add classes to tabs containers unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#classes",
      "items": {
        "type": "string"
      },
      "title": "Default Classes",
      "type": "array"
    },
    "custom": {
      "default": false,
      "description": "Choose whether tabs rendering uses a custom template.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#custom",
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        }
      ],
      "title": "Use Custom Rendering Template"
    },
    "enabled": {
      "default": true,
      "description": "Choose whether tabs codeblock rendering is available for the site.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#enabled",
      "title": "Enable the markup",
      "type": "boolean"
    },
    "no_scroll_controls": {
      "default": false,
      "description": "Specify whether tab groups should display arrows when the tabs overflow.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#no_scroll_controls",
      "title": "Disable Scroll Controls for Tab Groups",
      "type": "boolean"
    },
    "partials": {
      "description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#partials",
      "properties": {
        "renderers": {
          "description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#renderers",
          "properties": {
            "codeblock": {
              "default": "platen/markup/tabs/codeblock",
              "description": "Adds a partial to call when processing the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#codeblock",
              "title": "Codeblock Render Hook Partial",
              "type": "string"
            }
          },
          "title": "Renderer Partials",
          "type": "object"
        }
      },
      "title": "Markup Partials",
      "type": "object"
    },
    "placement": {
      "default": "top",
      "description": "Specify where the tabs should be rendered relative to their content.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#placement",
      "enum": [
        "top",
        "bottom",
        "start",
        "end"
      ],
      "title": "Default Tabs Placement",
      "type": "string"
    },
    "preset": {
      "description": "Specify the dot-path to a preset to use as the default for this markup.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#preset",
      "title": "Default Preset",
      "type": "string"
    },
    "standardize_height": {
      "default": false,
      "description": "Specify whether the tabs in a group should be rendered with the same height as the tallest tab panel.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#standardize_height",
      "title": "Standardize Tab Heights",
      "type": "boolean"
    },
    "style": {
      "default": "tabs",
      "description": "Defines the art markup's simple style module\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#style",
      "title": "Markup Simple Style Module",
      "type": "string"
    },
    "use_legacy": {
      "default": true,
      "description": "Set whether rendered tabs use the legacy template by default.\n\nhttps://platen.io/modules/platen/config/site/markup/tabs/#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/modules/platen/config/site/markup/tabs/#warn_on_legacy",
      "title": "Warn When Using the Legacy Template",
      "type": "boolean"
    }
  },
  "title": "Tabs",
  "type": "object"
}

Enable the markup (`enabled`)

Choose whether the site renders codeblocks with the tabs language ID as a group of tabs. If this setting is set to true, content inside the codeblock is added inside a <div> that renders child divs as tabs. If this setting is false, the content is rendered as an unhighlighted codeblock.

Metadata

Type: boolean

Aliases (`aliases`)

Define one or more language IDs to use in addition to the default language IDs for codeblocks that render their content in a group of divs as tabs. The default for the top-level codeblock for the column group is tabs. The default for the nested codeblock defining a single column is tab.

You can specify a string, a map, or an array of strings or maps for this value. If the value is an array, each item in the array is added as an alias.

String values are added as valid language IDs for the top-level codeblock in addition to tabs.

Map values must have either the group or entry key with a string value. If you define a value for group, it becomes a valid language ID for the top-level codeblock. If you define a value for entry, it becomes a valid language ID for the nested codeblock. You can specify both in a single map but don’t have to.

Metadata

Must be one of: Type
array
Valid items
Type
string; Type
object; Type
string

Use Custom Rendering Template (`custom`)

Choose whether tabs are rendered with a custom template. The default value is false. When this value is true, Platen uses the platen/markup/tabs/templates/custom/group.html partial template for rendering the tabs container and tab.html in the same folder for rendering individual tabs. When this value is a string, Platen uses that value as the name of the folder in the platen/markup/tabs/templates folder to look for the group.html and tabs.html partial templates.

If a tabs markup defines the custom option, the value defined on the markup overrides this setting.

For more information, see Custom Templates.

Metadata

Must be one of: Type
boolean; Type
string

Default Classes (`classes`)

You can add any number of classes to rendered tabs containers by default. Specify one or more strings as items in an array. They’re inserted for all tabs containers as if they had been specified with the class attribute or option in the markup.

If the attribute or option are specified for a tab group, those values override the list defined by this setting.

Metadata

Type

array

Valid items

Type: string

Default Activation Mode (`activation`)

You can define a default activation mode for a tab group. When the tab group is focused, keyboard users can press the kbd:Left and kbd:Right keys to select the desired tab.

When the value of this option is auto, the selected tab is shown immediately.

To require the user to press kbd:Space or kbd:Enter to show the tab, set this value to manual.

If the activation option is specified for a tab group in the markup, that value override this setting.

Metadata

Type: string
Enums: auto; manual

Disable Scroll Controls for Tab Groups (`no_scroll_controls`)

Specify whether the scroll arrows should be visible when tabs overflow. Set this value to true to disable the scroll arrows.

If the no_scroll_controls option is specified for a tab group in the markup, that value override this setting.

Metadata

Type: boolean

Default Tabs Placement (`placement`)

Specify where the tabs should be rendered relative to their content. When the placement is top or bottom and the tabs overflow the available horizontal width, they can be scrolled. You can disable the scroll arrows displayed when the tabs overflow by setting no_scroll_controls in your site settings or in the options for a tab group.

If the placement option is specified for a tab group in the markup, that value override this setting.

Metadata

Type: string
Enums: top; bottom; start; end

Standardize Tab Heights (`standardize_height`)

Specify whether the tabs in every group should be rendered with the same height as the tallest tab panel in the group. This can help to reduce how much the page’s layout updates when a reader switches between tabs in a group. Set this value to true to standardize the height of the tabs.

If the standardize_height option is specified for a tab group in the markup, that value overrides this setting.

Metadata

Type: boolean

Default Preset (`preset`)

You can define any number of preset tab groups and tabs reusably in your site’s data. Any YAML files you add in the data/platen/tabs folder are available for use. You can use folders to group presets together. For more information about presets, see Presets in the reference documentation for the markup.

Metadata

Type: string

Use Legacy Template (`use_legacy`)

Use this setting to configure whether Platen uses the legacy template for tabs 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 tabs markup in your content, this value is overriden by that option.

For more information, see Legacy Template in the reference documentation for this markup.

Metadata

Type: boolean

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 tabs markup. Set this value to false to disable the warning. The default value is true.

For more information, see Legacy Template in the reference documentation for this markup.

Metadata

Type: boolean

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.

Metadata

Type: object

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 ID
heading, processed for headings
image, processed for image links
link, 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.

Metadata

Type: object

Codeblock Render Hook Partial (`codeblock`)

Adds support for rendering codeblocks as tabs in Platen. This render hook is only called if the language ID for the codeblock (i.e. ```languageID) is tabs. If a codeblock does include the language ID, the renderer looks for any nested codeblocks with the tab language ID to render as tabs in a shared group.

For more information about using the codeblock to add tabbed content, see the reference documentation.

This value defaults to platen/markup/tabs/codeblock. You can replace it with a different value and defining a new partial, or override the existing partial by creating the file layouts/partials/platen/markup/tabs/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.

Metadata

Type: string

Markup Simple Style Module (`style`)

Defines default styling for tabs created by the codeblock.

When you use the tabs codeblock, the following SCSS is applied:

.markdown .platen-tabs {
  margin-top: $padding-large;
  margin-bottom: $padding-large;

  border: $padding-minimal solid var(--gray-200);
  border-radius: $border-radius;

  overflow: hidden;

  display: flex;
  flex-wrap: wrap;

  label {
    display: inline-block;
    padding: $padding-medium $padding-large;
    border-bottom: $padding-minimal transparent;
    cursor: pointer;
  }

  .platen-tabs-content {
    order: 999; //Move content blocks to the end
    width: 100%;
    border-top: $padding-minimal solid var(--gray-100);
    padding: $padding-large;
    display: none;
  }

  input[type="radio"]:checked + label {
    border-bottom: $padding-minimal solid var(--color-link);
  }
  input[type="radio"]:checked + label + .platen-tabs-content {
    display: block;
  }
  input[type="radio"]:focus + label {
    @include outline;
  }
}

When you use the tabs codeblock, the content is placed in a div container with the platen-tabs class. Each tab uses a radio input with its label used as the selectable tab. Each tab’s content is placed in a div with the platen-tabs-content and markdown-inner classes.

Tab Container #

margin-top: $padding-large;
margin-bottom: $padding-large;

border: $padding-minimal solid var(--gray-200);
border-radius: $border-radius;

overflow: hidden;

display: flex;
flex-wrap: wrap;

The container is uses $padding-large to set the vertical margins. It adds a solid border with the width set to $padding-minimal, the border radius to [sref:theme.variables.light_css.color-link], and the color to theme.variables.light_css.gray-200 or theme.variables.light_css.gray-200 depending on the value of the theme.config.mode setting.

Is sets the overflow attribute to hidden, which keeps any content that doesn’t fit the container from displaying.

It uses flex box to display the tabs and their labels and uses flex-wrap.

Tab Labels #

label {
  display: inline-block;
  padding: $padding-medium $padding-large;
  border-bottom: $padding-minimal transparent;
  cursor: pointer;
}
input[type="radio"]:checked + label {
  border-bottom: $padding-minimal solid var(--color-link);
}
input[type="radio"]:focus + label {
  @include outline;
}

The labels are added as inline blocks, allowing them to display side-by-side. They’re use the value of $padding-medium for the vertical padding and $padding-large for the horizontal padding.

They get a transparent bottom border with the width set to $padding-minimal and have their cursor always display as a normal pointer.

When the input for a label is checked, the label’s border color switches from being transparent to the value of [sref:theme.variables.light_css.color-link] or [sref:theme.variables.light_css.color-link] depending on the theme.config.mode.

When the input for a label is focused, the label uses the theme.styles.utils.outline mixin to add a full box outline to the label.

Tab Content #

.platen-tabs-content {
  order: 999; //Move content blocks to the end
  width: 100%;
  border-top: $padding-minimal solid var(--gray-100);
  padding: $padding-large;
  display: none;
}

input[type="radio"]:checked + label + .platen-tabs-content {
  display: block;
}

The tabs are all set to have an order of 999, putting them together at the end of the flex box. They’re set to have a width of 100% of their container and given a solid top border with a width of $padding-minimal and their color set to either theme.variables.light_css.gray-200 or theme.variables.dark_css.gray-200 depending on the theme.config.mode. Their padding is set to $padding-large.

Finally, their display is set to none so they’re hidden until selected. When a tab is selected, the display is changed block, making it visible.

Overriding #

You can overwrite this definition for your own site or theme by creating the file styles/markup/_tabs.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.

Careful!

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.

Metadata

Type: string

JSON Schema

Enable the markup (enabled)

Aliases (aliases)

Use Custom Rendering Template (custom)

Default Classes (classes)

Default Activation Mode (activation)

Disable Scroll Controls for Tab Groups (no_scroll_controls)

Default Tabs Placement (placement)

Standardize Tab Heights (standardize_height)

Default Preset (preset)

Use Legacy Template (use_legacy)

Warn When Using the Legacy Template (warn_on_legacy)

Codeblock Render Hook Partial (codeblock)

Markup Simple Style Module (style)

Tab Container #

Tab Labels #

Tab Content #

Overriding #

Enable the markup (`enabled`)

Aliases (`aliases`)

Use Custom Rendering Template (`custom`)

Default Classes (`classes`)

Default Activation Mode (`activation`)

Disable Scroll Controls for Tab Groups (`no_scroll_controls`)

Default Tabs Placement (`placement`)

Standardize Tab Heights (`standardize_height`)

Default Preset (`preset`)

Use Legacy Template (`use_legacy`)

Warn When Using the Legacy Template (`warn_on_legacy`)

Codeblock Render Hook Partial (`codeblock`)

Markup Simple Style Module (`style`)