Alerts

Alerts (alerts)

Defines the map of options for Platen’s alerts 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 make content stand out from its surroundings on a page with a codeblock. It inserts an <sl-alert> element from Shoelace with your content rendered inside it.

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/alerts/schema.json

Type

object

JSON Schema

Definition
{
  "$id": "https://platen.io/modules/platen/config/site/markup/alerts/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Defines the options for Platen's alerts markup\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/",
  "properties": {
    "aliases": {
      "description": "Defines additional language IDs for the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#aliases",
      "oneOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "string"
        }
      ],
      "title": "Aliases"
    },
    "classes": {
      "default": [],
      "description": "Add classes to alerts unless overridden in the markup.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#classes",
      "items": {
        "type": "string"
      },
      "title": "Default Classes",
      "type": "array"
    },
    "custom": {
      "default": false,
      "description": "Choose whether alert rendering uses a custom template.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#custom",
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        }
      ],
      "title": "Use Custom Rendering Template"
    },
    "enabled": {
      "default": true,
      "description": "Choose whether alert codeblock rendering is available for the site.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#enabled",
      "title": "Enable the markup",
      "type": "boolean"
    },
    "icons": {
      "description": "Specify default icons for alerts by their variant.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#icons",
      "properties": {
        "danger": {
          "default": "exclamation-octagon@builtin_bootstrap",
          "description": "Specify the name of the default icon for danger variant alerts.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#danger",
          "title": "Default 'danger' Alert Variant Icon",
          "type": "string"
        },
        "default": {
          "default": "gear@builtin_bootstrap",
          "description": "Specify the name of the default icon for default variant alerts.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#default",
          "title": "Default 'default' Alert Variant Icon",
          "type": "string"
        },
        "primary": {
          "default": "info-circle@builtin_bootstrap",
          "description": "Specify the name of the default icon for primary variant alerts.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#primary",
          "title": "Default 'primary' Alert Variant Icon",
          "type": "string"
        },
        "success": {
          "default": "check2-circle@builtin_bootstrap",
          "description": "Specify the name of the default icon for success variant alerts.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#success",
          "title": "Default 'success' Alert Variant Icon",
          "type": "string"
        },
        "warning": {
          "default": "exclamation-triangle@builtin_bootstrap",
          "description": "Specify the name of the default icon for warning variant alerts.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#warning",
          "title": "Default 'warning' Alert Variant Icon",
          "type": "string"
        }
      },
      "title": "Default Alert Icons",
      "type": "object"
    },
    "partials": {
      "description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#partials",
      "properties": {
        "renderers": {
          "description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#renderers",
          "properties": {
            "codeblock": {
              "default": "platen/markup/alerts/codeblock",
              "description": "Adds a partial to call when processing the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#codeblock",
              "title": "Codeblock Render Hook Partial",
              "type": "string"
            }
          },
          "title": "Renderer Partials",
          "type": "object"
        }
      },
      "title": "Markup Partials",
      "type": "object"
    },
    "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/alerts/#preset",
      "title": "Default Preset",
      "type": "string"
    },
    "style": {
      "default": "alerts",
      "description": "Defines the alerts markup's simple style module\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#style",
      "title": "Markup Simple Style Module",
      "type": "string"
    },
    "use_default_icons": {
      "default": true,
      "description": "Set whether rendered alerts use configured icons by default\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#use_default_icons",
      "title": "Use Default Icons",
      "type": "boolean"
    },
    "variant": {
      "default": "primary",
      "description": "Specify the default variant for rendered alerts.\n\nhttps://platen.io/modules/platen/config/site/markup/alerts/#variant",
      "enum": [
        "danger",
        "default",
        "primary",
        "success",
        "warning"
      ],
      "title": "Default Variant",
      "type": "string"
    }
  },
  "title": "Alerts",
  "type": "object"
}

Enable the markup (enabled)

Choose whether the site renders codeblocks with the alert language ID as an alert. If this setting is set to true, content inside the codeblock is added inside a [sref:<sl-alert>] element. 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 ID for codeblocks that render their content as an alert. The default is alert.

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

Metadata

Must be one of

Type

array

Valid items

Type

string

Type

string

Use Custom Rendering Template (custom)

Choose whether alerts are rendered with a custom template. The default value is false. When this value is true, Platen uses the platen/markup/alerts/templates/custom.html partial template for rendering the alert. When this value is a string, Platen uses that value as the name of the HTML file in the platen/markup/alerts/templates folder to use as the rendering template.

If an alert 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 Preset (preset)

You can define any number of preset alerts reusably in your site’s data. Any YAML files you add in the data/platen/alerts 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

Default Variant (variant)

You can define a default variant for your alerts. The variant controls the color used for the alert’s border. If the alert includes an icon, the variant also determines the icon’s color. You can override this setting with the variant option in an alert’s markup.

When use_default_icons is set to true in the configuration or an alert markup’s options, the variant also determines which icon is added to the alert.

The valid variants are:

  • danger
  • default
  • primary
  • success
  • warning

The configured default variant is primary.

For more information, see the reference documentation for the markup.

Metadata

Type

string

Enums

danger
default
primary
success
warning

Default Classes (classes)

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

If the attribute or option are specified for an alert’s markup, those values override the list defined by this setting.

Metadata

Type

array

Valid items

Type

string

Default Alert Icons (icons)

Specify default icons for alerts by their variant. These settings are only used when use_default_icons is set to true in the configuration or in an alert’s markup options.

The key for each setting is the name of a variant for the alert. The value is the name of the icon to add to the alert unless overridden by the icon option in the alert’s markup.

The Shoelace documentation lists the valid icon names you can use.

Metadata

Type

object

Default 'danger' Alert Variant Icon (danger)

Use this setting to specify the name of the default icon for `danger`` variant alerts. This icon is only added to alerts when:

You can specify any valid icon name for this setting. The default is exclamation-octagon.

Metadata

Type

string

Default 'default' Alert Variant Icon (default)

Use this setting to specify the name of the default icon for default variant alerts. This icon is only added to alerts when:

You can specify any valid icon name for this setting. The default is gear.

Metadata

Type

string

Default 'primary' Alert Variant Icon (primary)

Use this setting to specify the name of the default icon for primary variant alerts. This icon is only added to alerts when:

You can specify any valid icon name for this setting. The default is info-circle.

Metadata

Type

string

Default 'success' Alert Variant Icon (success)

Use this setting to specify the name of the default icon for success variant alerts. This icon is only added to alerts when:

You can specify any valid icon name for this setting. The default is check2-circle.

Metadata

Type

string

Default 'warning' Alert Variant Icon (warning)

Use this setting to specify the name of the default icon for warning variant alerts. This icon is only added to alerts when:

You can specify any valid icon name for this setting. The default is exclamation-triangle.

Metadata

Type

string

Use Default Icons (use_default_icons)

Use this setting to configure whether Platen adds the configured variant icons to rendered alerts. The default value is true. Set this value to false to ignore the variant icons.

If you use the use_default_icons option for alert markup in your content, this value is overriden by that option.

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 alerts in Platen. This render hook is only called if the language ID for the codeblock (i.e. ```languageID) is alert or a valid alias. If a codeblock does include a valid language ID for the markup, Platen uses the codeblock for rendering an alert.

For more information about using the codeblock to add an alert, see the reference documentation.

This value defaults to platen/markup/alerts/codeblock. You can replace it with a different value and define a new partial template, or override the existing partial by creating the file layouts/partials/platen/markup/tabs/codeblock.html in your own site or module.

We recommend instead that you use the custom configuration setting or markup option. Defining a custom template is much less work than fully implementing a new Markdown render hook.

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 alerts created by the codeblock.

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

// Fill me out

Overriding #

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

If you override the style module or this setting, you entirely overwrite the default from Platen.

For more information on authoring SCSS, see the learning guide. For more information on styling your alerts markup, see Styling in the reference documentation for the markup.

Metadata

Type

string
Edit this page