Configuration

Theming Options (config)

The Platen theme options…

Metadata

ID

https://platen.io/schemas/platen/site/theme/config/schema.json

Type

object

JSON Schema

Definition
{
  "$id": "https://platen.io/schemas/platen/site/theme/config/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Optional settings for theming a Platen site.\n\nhttps://platen.io/schemas/platen/site/theme/config/",
  "properties": {
    "fonts": {
      "description": "Add and configure fonts\n\nhttps://platen.io/schemas/platen/site/theme/config/#fonts",
      "properties": {
        "settings": {
          "$ref": "https://platen.io/schemas/platen/site/theme/fonts/settings/schema.json"
        },
        "styles": {
          "description": "Optional settings for configuring fonts on a Platen site.\n\nhttps://platen.io/schemas/platen/site/theme/config/#styles",
          "items": {
            "oneOf": [
              {
                "description": "The import name of the SCSS module that defines the font or font family or the URL to import a web font.\nThe value must be a string that either:\n- Matches the name of an SCSS module in the `assets/fonts` folder. For example, to add the module in\n  `assets/fonts/_spectral.scss`, specify `spectral`. This value is case sensitive.\n- Is the URL to a webfont that you can import. For example, to add the Montserrat Google font, this\n  value would be `https://fonts.googleapis.com/css2?family=Montserrat\u0026display=swap`.\n\nhttps://platen.io/schemas/platen/site/theme/config/",
                "type": "string"
              },
              {
                "$ref": "https://platen.io/schemas/platen/site/theme/fonts/mapped_style/schema.json"
              }
            ]
          },
          "title": "Font Options",
          "type": "array"
        }
      },
      "title": "Font Options",
      "type": "object"
    },
    "mode": {
      "default": "auto",
      "description": "Specifies whether the site should show light or dark theme or use the user's OS preference setting.\n\nhttps://platen.io/schemas/platen/site/theme/config/#mode",
      "enum": [
        "auto",
        "light",
        "dark"
      ],
      "title": "Display Mode",
      "type": "string"
    },
    "printing": {
      "description": "Configure and style the site for printing\n\nhttps://platen.io/schemas/platen/site/theme/config/#printing",
      "properties": {
        "styles": {
          "$ref": "https://platen.io/schemas/platen/site/theme/printing/styles/schema.json"
        }
      },
      "title": "Printing Options",
      "type": "object"
    },
    "styles": {
      "description": "SCSS Style modules\n\nhttps://platen.io/schemas/platen/site/theme/config/#styles",
      "properties": {
        "base": {
          "$ref": "https://platen.io/schemas/platen/site/theme/styles/base/schema.json"
        },
        "markdown": {
          "$ref": "https://platen.io/schemas/platen/site/theme/styles/markdown/schema.json"
        },
        "mobile": {
          "$ref": "https://platen.io/schemas/platen/site/theme/styles/mobile/schema.json"
        },
        "platen": {
          "$ref": "https://platen.io/schemas/platen/site/theme/styles/platen/schema.json"
        },
        "utils": {
          "$ref": "https://platen.io/schemas/platen/site/theme/styles/utils/schema.json"
        },
        "wide": {
          "$ref": "https://platen.io/schemas/platen/site/theme/styles/wide/schema.json"
        }
      },
      "title": "Styles",
      "type": "object"
    },
    "variables": {
      "description": "Variables to insert for SCSS and CSS.\n\nhttps://platen.io/schemas/platen/site/theme/config/#variables",
      "properties": {
        "basic_scss": {
          "$ref": "https://platen.io/schemas/platen/site/theme/variables/basic_scss/schema.json"
        },
        "calculated_scss": {
          "$ref": "https://platen.io/schemas/platen/site/theme/variables/calculated_scss/schema.json"
        },
        "custom_css": {
          "description": "foo...\n\nhttps://platen.io/schemas/platen/site/theme/config/#custom_css",
          "patternProperties": {
            ".": {
              "description": "Specify the value for the CSS variable. The key name is used as the variable name.\n\nhttps://platen.io/modules/platen/config/site/theme/config/#variables.custom_css\n",
              "title": "Valid Custom CSS Variables",
              "type": "string"
            }
          },
          "title": "Custom CSS Variables",
          "type": "object"
        },
        "dark_css": {
          "$ref": "https://platen.io/schemas/platen/site/theme/variables/dark_css/schema.json"
        },
        "light_css": {
          "$ref": "https://platen.io/schemas/platen/site/theme/variables/light_css/schema.json"
        }
      },
      "title": "Variables",
      "type": "object"
    }
  },
  "title": "Theming Options",
  "type": "object"
}

Display Mode (mode)

Specifies whether the site should display the light theme (light), dark theme (dark), or the theme that matches the user’s OS preferences (auto).

The default is auto.

Metadata

Type

string

Enums

auto
light
dark

Variables (variables)

Defines several different groups of variables to insert into the SCSS that defines how the site is displayed.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all variables in your own configuration file. Only specify the values you want to add or replace.

The variables are added to the SCSS in the following order:

  1. basic_scss is loaded first, because these variables have no dependencies.
  2. calculated_scss is loaded next, because these variables are expected to use values defined in basic_scss for convenience.
  3. light_css and dark_css are loaded next. They’re independent of each other, but may rely on values defined in basic_scss or calculated_scss.
  4. Finally, custom_css is loaded. These values are independent of light_css and dark_css but may rely on values defined in basic_scss or calculated_scss.
Metadata

Type

object

Basic SCSS Variables (basic_scss)

Defines a set of SCSS variables that Platen uses to determine how to display the site.

For more information, see Basic SCSS Variables

Calculated SCSS Variables (calculated_scss)

Defines a set of calculated SCSS variables that Platen uses to determine how to display the site. Specify values that depend on those defined in theme.variables.basic_scss.

For more information, see Calculated SCSS Variables

Light Mode CSS Variables (light_css)

Defines custom CSS properties that define the light mode for the theme. These values control the display of the site when the theme.mode is set to light or when set to auto and the site visitor’s OS preferences are set to light mode.

For more information, see Light Mode CSS Variables

Dark Mode CSS Variables (dark_css)

Defines custom CSS properties that define the dark mode for the theme. These values control the display of the site when the theme.mode is set to dark or when set to auto and the site visitor’s OS preferences are set to dark mode.

For more information, see Dark Mode CSS Variables

Custom CSS Variables (custom_css)

In addition to the defined list of CSS variables related to the mode for the site, you can define an arbitrary set of CSS variables available in both modes. By default, this setting has no defined variables.

Any key you specify for this setting creates a CSS variable with the same name whose value is the value you specify for the setting. For example, this configuration:

theme:
  variables:
    custom_css:
      foo: sepia(1)
      bar: 16px

Creates the following CSS:

:root {
  --foo: sepia(1);
  --bar: 16px;
}
Metadata

Type

object

Pattern Properties

Valid Custom CSS Variables (Pattern: .)

Specify the value for the CSS variable. The key name is used as the variable name.

Metadata

Type

string

Styles (styles)

Defines several different groups of style modules to insert into the SCSS that defines how the site is displayed.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all variables in your own configuration file. Only specify the values you want to add or replace.

The styles are added to the SCSS in a non-deterministic order.

Metadata

Type

object

Base Style Modules (base)

Defines the map of base SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information, see Base Style Modules

Platen Style Modules (platen)

Defines the map of Platen-specific SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information, see Platen Style Modules

Mobile Style Modules (mobile)

Defines the map of mobile-specific SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information, see Mobile Style Modules

Wide Style Modules (wide)

Defines the map of wide-view-specific SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information on authoring SCSS style modules, see the SCSS documentation.

For more information, see Wide Style Modules

Markdown Style Modules (markdown)

Defines the map of Markdown-specific SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information, see Markdown Style Modules

Utils Style Modules (utils)

Defines the map of utility SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information on authoring SCSS style modules, see the SCSS documentation.

For more information, see Utils Style Modules

Font Options (fonts)

Defines the set of fonts the theme should add and configures how to apply those fonts to different elements in the theme.

The styles property controls the addition of fonts as an overridable array of font declarations. The settings property controls where the fonts are used.

Metadata

Type

object

Font Options (styles)

Defines the array of fonts to load for the theme. The existing value is an array that makes the theme’s default fonts (the Roboto family) available.

If you define this setting in your site or theme, you replace the existing set of fonts. To reinclude the theme’s default fonts, make sure to include roboto in the array.

For example, if a theme defined it’s own spectral font family, it could re-add the roboto font with the following configuration:

Fonts:
  Styles:
    - spectral
    - roboto

There are two options for defining font style modules.

  1. Simple Font Modules

    Simple font module declarations are strings that match the import name of the SCSS module that defines the font or font family or the URL to import a web font.

    The value must be a string that either:

    • Matches the name of an SCSS module in the assets/fonts folder. For example, to add the module in assets/fonts/_spectral.scss, specify spectral. This value is case sensitive.
    • Is the URL to a webfont that you can import. For example, to add the Montserrat Google font, this value would be https://fonts.googleapis.com/css2?family=Montserrat&display=swap.

  2. Mapped Font Modules

    Mapped font modules provide more control over the importing of an SCSS module with fonts or a web font. Add each item as a map with the import_name key defined.

    The import_name must be a string that matches the import name of the SCSS module that defines the font or font family or the URL to import a web font. This setting is mandatory for each defined font.

    The value must be a string that either:

    • Matches the name of an SCSS module in the assets/fonts folder. For example, to add the module in assets/fonts/_spectral.scss, specify spectral. This value is case sensitive.
    • Is the URL to a webfont that you can import. For example, to add the Montserrat Google font, this value would be https://fonts.googleapis.com/css2?family=Montserrat&display=swap.

    You can also specify the weight key to control the order the SCSS modules are loaded. All mapped declarations are loaded before unmapped modules. All weighted modules are loaded before unweighted modules. Weighted modules are loaded in order from lowest weight to highest.

Metadata

Type

array

Valid items

Type

string

Mapped Font Style (Schema)

Mapped font modules provide more control over the importing of an SCSS module with fonts. Add each item as a map with the import_name key defined.

For more information, see Mapped Font Style.

Font Settings (settings)

Defines the map of base font settings for the theme. The existing value is a map of settings that define the font families for body text and code elements.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information on creating your own settings, see Defined Font Settings.

For more information, see Font Settings

Printing Options (printing)

Defines the style modules to use when a site visitor prints a page.

The styles property controls the importing of SCSS modules as a map.

Metadata

Type

object

Printing Style Modules (styles)

Defines the map of printing-specific SCSS style modules for the theme. The existing value is a map of styles that are loaded first for the theme and set defaults for the presentation.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all styles in your own configuration file. Only specify the values you want to add or replace.

For more information on authoring SCSS style modules, see the SCSS documentation.

For more information, see Printing Style Modules

Edit this page