Buttons

The button image markup makes it possible for you to define a link that’s styled as a button.

When used, it inserts an <sl-button> element from Shoelace to the page that site visitors can select to open another web page or download a file.

Syntax #

Basic Block Syntax #

![button:label_text](source ['label_icon'])
{
  [.class [.class]]
  [circle        = (true|false)]
  [download_name = "download_name"]
  [height        = "height"]
  [legacy        = (true|false)]
  [outline       = (true|false)]
  [pill          = (true|false)]
  [prefix_icon   = "prefix_icon"]
  [preset        = "preset"]
  [rel           = "rel"]
  [size          = (small|medium|large)]
  [suffix_icon   = "suffix_icon"]
  [target        = (_blank|_parent|_self|_top)]
  [variant       = (default|primary|success|neutral|warning|danger|text)]
  [width         = "width"]
}

Reference Link Block Syntax #

![button:label_text][<ReferenceID>]
{
  [.class [.class]]
  [circle        = (true|false)]
  [download_name = "download_name"]
  [height        = "height"]
  [legacy        = (true|false)]
  [outline       = (true|false)]
  [pill          = (true|false)]
  [prefix_icon   = "prefix_icon"]
  [preset        = "preset"]
  [rel           = "rel"]
  [size          = (small|medium|large)]
  [suffix_icon   = "suffix_icon"]
  [target        = (_blank|_parent|_self|_top)]
  [variant       = (default|primary|success|neutral|warning|danger|text)]
  [width         = "width"]
}

[<ReferenceID>]: source ['label_icon']

Examples #

1. Minimal Example #

Markdown Input

![button:Flagrant Garden](https://flagrant.garden)

HTML Output

<sl-button href="https://flagrant.garden" class="platen-btn">
  Flagrant Garden
</sl-button>

Rendered Output

Flagrant Garden

2. Button Sizes #

You can make your buttons smaller or larger with the size attribute, which uses consistent values across your site for small, medium, and large. You can also use the height and width attributes to customize those values for the button, overriding the defaults for the size.

Markdown Input

![button:Flagrant Garden](https://flagrant.garden)
{ size="small" }

![button:Flagrant Garden](https://flagrant.garden)
{ size="medium" }

![button:Flagrant Garden](https://flagrant.garden)
{ size="large" }

![button:Flagrant Garden](https://flagrant.garden)
{ height="4rem" width="100%" }

HTML Output

<sl-button href="https://flagrant.garden" class="platen-btn" size="small">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden" class="platen-btn" size="medium">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden" class="platen-btn" size="large">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           data-custom-height="true"
           data-custom-width="true"
           style="--custom-height: 4rem; --custom-width: 100%">
  Flagrant Garden
</sl-button>

Rendered Output

Flagrant Garden

3. Button Variants #

You can use variants to change how the buttons are displayed. For more information on variants, see variant.

You can also use the outline attribute to render the buttons with the variant colors applied to the label text and outline instead of making the entire button the variant color.

Note that the text variant never has an outline or background color. It’s the same size as the other buttons but only has the text colored.

Markdown Input

![button:Flagrant Garden](https://flagrant.garden)
{ variant="default" }

![button:Flagrant Garden](https://flagrant.garden)
{ variant="default" outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ variant="primary" }

![button:Flagrant Garden](https://flagrant.garden)
{ variant="primary" outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ variant="success" }

![button:Flagrant Garden](https://flagrant.garden)
{ variant="success" outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ variant="neutral" }

![button:Flagrant Garden](https://flagrant.garden)
{ variant="neutral" outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ variant="warning" }

![button:Flagrant Garden](https://flagrant.garden)
{ variant="warning" outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ variant="danger" }

![button:Flagrant Garden](https://flagrant.garden)
{ variant="danger" outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ variant="text" }

HTML Output

<sl-button href="https://flagrant.garden" class="platen-btn" variant="default">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="default"
           outline="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn" variant="primary">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="primary"
           outline="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn" variant="success">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="success"
           outline="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn" variant="neutral">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="neutral"
           outline="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn" variant="warning">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="warning"
           outline="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn" variant="danger">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="danger"
           outline="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn" variant="text">
  Flagrant Garden
</sl-button>

Rendered Output

Flagrant Garden

4. Pill Buttons #

Markdown Input

You can make the buttons rounded by setting the [`pill`](#pill) attribute. This
works with the [`variant`](#variant) and [`outline`](#outline) attributes.

<!-- Example Start -->
![button:Flagrant Garden](https://flagrant.garden)
{ pill=true }

![button:Flagrant Garden](https://flagrant.garden)
{ pill=true outline=true }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ pill=true variant="primary" }

![button:Flagrant Garden](https://flagrant.garden)
{ pill=true variant="primary" outline=true }

HTML Output

<p>You can make the buttons rounded by setting the <a href="#pill"><code>pill</code></a> attribute. This
works with the <a href="#variant"><code>variant</code></a> and <a href="#outline"><code>outline</code></a> attributes.</p>
<!-- Example Start -->
<sl-button href="https://flagrant.garden" class="platen-btn" pill="true">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           outline="true"
           pill="true">
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="primary"
           pill="true">
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden"
           class="platen-btn"
           variant="primary"
           outline="true"
           pill="true">
  Flagrant Garden
</sl-button>

Rendered Output

You can make the buttons rounded by setting the pill attribute. This works with the variant and outline attributes.

Flagrant Garden

5. Buttons with Icons #

Markdown Input

You can add an icon before or after the label text with the
[`prefix_icon`](#prefix_icon) and [`suffix_icon`](#suffix_icon) attributes.

You can use the [`title`](#title-as-label_icon)  input instead of writing text
for the button's label. When you do, you can also use the [`circle`](#circle)
attribute to render the button as a circle around the icon.

<!-- Example Start -->
![button:Flagrant Garden](https://flagrant.garden)
{ prefix_icon="cloud-download-fill" }

![button:Flagrant Garden](https://flagrant.garden)
{ suffix_icon="cloud-upload-fill" }

<br />

![button:Flagrant Garden](https://flagrant.garden)
{ prefix_icon="cloud-download-fill" suffix_icon="cloud-upload-fill" }

<br />

![button:](https://flagrant.garden "cog@boxicons")

![button:](https://flagrant.garden "cog&solid@boxicons")
{ circle=true }

HTML Output

<p>You can add an icon before or after the label text with the
<a href="#prefix_icon"><code>prefix_icon</code></a> and <a href="#suffix_icon"><code>suffix_icon</code></a> attributes.</p>
<p>You can use the <a href="#title-as-label_icon"><code>title</code></a>  input instead of writing text
for the button&rsquo;s label. When you do, you can also use the <a href="#circle"><code>circle</code></a>
attribute to render the button as a circle around the icon.</p>
<!-- Example Start -->
<sl-button href="https://flagrant.garden" class="platen-btn">
    <sl-icon slot="prefix" name="cloud-download-fill"></sl-icon>
  Flagrant Garden
</sl-button><sl-button href="https://flagrant.garden" class="platen-btn">
    <sl-icon slot="suffix" name="cloud-upload-fill"></sl-icon>
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn">
    <sl-icon slot="prefix" name="cloud-download-fill"></sl-icon>
    <sl-icon slot="suffix" name="cloud-upload-fill"></sl-icon>
  Flagrant Garden
</sl-button><br />
<sl-button href="https://flagrant.garden" class="platen-btn">
  <sl-icon library="boxicons" name="cog"></sl-icon>
</sl-button><sl-button href="https://flagrant.garden" class="platen-btn" circle="true">
  <sl-icon library="boxicons" name="cog&solid"></sl-icon>
</sl-button>

Rendered Output

You can add an icon before or after the label text with the prefix_icon and suffix_icon attributes.

You can use the title input instead of writing text for the button’s label. When you do, you can also use the circle attribute to render the button as a circle around the icon.

Flagrant Garden

6. With Classes #

Markdown Input

![button:Flagrant Garden](https://flagrant.garden)
{ .example .flagrant }

HTML Output

<sl-button href="https://flagrant.garden" class="platen-btn example flagrant">
  Flagrant Garden
</sl-button>

Rendered Output

Flagrant Garden

7. With Preset #

Markdown Input

![button:](preset:flagrant_garden)

HTML Output

<sl-button href="https://flagrant.garden" class="platen-btn">
    <sl-icon slot="prefix" name="flower3"
                           style="filter: invert(.7)sepia(1)saturate(.5)hue-rotate(270deg);"></sl-icon>
  _Flagrant Garden_
</sl-button>

Rendered Output

_Flagrant Garden_

8. With Legacy Template #

Markdown Input

This example uses the legacy template for rendering the button.

With [`legacy`](#legacy) set to `true` in the attributes or from a preset,
Platen renders the button with the native [sref:`<a>` (anchor)][s01] HTML
element instead of the [sref:`<sl-button>`] element from [sref:Shoelace].

This option is included to allow folks to intentionally transition from the
legacy implementation to Shoelace, which will become the default in the future.
Eventually, the legacy implementation will be removed. For more information, see
[Legacy Template](#legacy-template).

[sref:`<sl-button>`]: sl.component:button
[sref:Shoelace]: sl:
[s01]: mdn.html.element:a

<!-- Example Start -->

![button:Legacy Button](https://flagrant.garden)
{ legacy=true }

HTML Output

<p>This example uses the legacy template for rendering the button.</p>
<p>With <a href="#legacy"><code>legacy</code></a> set to <code>true</code> in the attributes or from a preset,
Platen renders the button with the native <a class="schematize-sref" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a"><code>&lt;a&gt;</code> (anchor)</a> HTML
element instead of the <a class="schematize-sref" href="https://shoelace.style/components/button"><code>&lt;sl-button&gt;</code></a> element from <a class="schematize-sref" href="https://shoelace.style/">Shoelace</a>.</p>
<p>This option is included to allow folks to intentionally transition from the
legacy implementation to Shoelace, which will become the default in the future.
Eventually, the legacy implementation will be removed. For more information, see
<a href="#legacy-template">Legacy Template</a>.</p>
<!-- Example Start -->
<a href="https://flagrant.garden" class="platen-btn">
  Legacy Button
</a>

Rendered Output

This example uses the legacy template for rendering the button.

With legacy set to true in the attributes or from a preset, Platen renders the button with the native <a> (anchor) HTML element instead of the <sl-button> element from Shoelace.

This option is included to allow folks to intentionally transition from the legacy implementation to Shoelace, which will become the default in the future. Eventually, the legacy implementation will be removed. For more information, see Legacy Template.

Legacy Button

Inputs #

This section describes how the normal markdown input for images works with the button render hook.

Images use this syntax for their inputs:

![alt_text](source "title")

`alt_text` (as `label_text`) #

Specifies the Markdown text to render as the button’s label.

This value must start with the prefix button:. For example, with ![button:Platen](https://platen.io), label_text’s value would be Platen.

This value is rendered as inline Markdown.

RendersMarkdown: true
Required: true
Type: String

`source` (as `destination`) #

Specify the URL for where the button should take a visitor when clicked. This value is used as the href attribute of the button’s element.

You can also use this value to specify a Preset for the button by prefixing the value with preset:. Specify the name of the preset, like ![button:](preset:foo). If the preset is defined in a subfolder, specify the dot-path relative to data/platen/buttons. For example, the preset defined in data/platen/buttons/flagrant_garden/home would be specified like ![button:](preset:flagrant_garden.home).

Specify the text without wrapping quotes, like this.

Required: true
Type: String

`title` (as `label_icon`) #

Specify the name of the icon you want to display instead of text for the button label. You can use any valid icon from Shoelace. When you specify the name of an icon, Platen ignores the value for label_text.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

Attributes #

`circle` #

Use this attribute to make the button render as a circle just large enough to hold the label_icon. If this attribute is set without a label icon, it’s ignored.

This option isn’t valid with the legacy button.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

`class` #

Specify one or more classes to add to the button’s element. By default, it has only the platen-btn class.

You can also define the default classes for your buttons with the platen.markup.buttons.classes setting for your site configuration. Values from your site configuration are overridden by this attribute in your markup. For more information, see Configuration.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`download_name` #

Use this attribute to tell the browser to download the linked file with this name. This is only useful when the destination is a file.

This option isn’t valid with the legacy button.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`height` #

Use this attribute to set a custom height for the rendered button. This overrides the height set by the button’s size. This is a simplistic style option for when the only style you want to override for your button is its dimensions. It’s usually better and more maintainable to define a custom class for your buttons. For more information on styling your buttons, see Styling.

This option isn’t valid with the legacy button.

Specify a valid CSS length wrapped in quotes. For example, you could specify "10rem" to set the value to ten times the size of root elment’s font-size.

Required: false
Type: String

`legacy` #

Use this option to set whether Platen uses the legacy template for rendering buttons.

Specify true to use the legacy template for the buttons element, or false to use the <sl-button> element from Shoelace. If this value isn’t set, Platen uses the value of the platen.markup.buttons.use_legacy setting defined in your site configuration. For more information, see Configuration.

When this setting is true, the options in the list below aren’t valid. If you use them when legacy is true, Platen warns you about the incompatibility and ignores the invalid options.

circle
download_name
height
outline
pill
prefix_icon
rel
size
suffix_icon
target
variant
width

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

`outline` #

Use this attribute to render the button with an outline instead of as a block with background color.

You can also define whether your buttons are rendered with an outline with the platen.markup.buttons.outline setting for your site configuration. Values from your site configuration are overridden by this attribute in your markup. For more information, see Configuration.

This option isn’t valid with the legacy button.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

`pill` #

Use this attribute to render the button with rounded corners instead of as a rectangle.

You can also define whether your buttons are rendered with rounded corners with the platen.markup.buttons.pill setting for your site configuration. Values from your site configuration are overridden by this attribute in your markup. For more information, see Configuration.

This option isn’t valid with the legacy button.

Specify true or false without wrapping quotes.

Required: false
Type: Boolean

`prefix_icon` #

Use this attribute to insert an icon before your label text. You can specify the icon as a string using the shorthand syntax for icons.

This option isn’t valid with the legacy button.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

Shorthand Syntax #

The shorthand syntax for icons in Platen is <name>[&<variant>][@<library>], where:

<name> is mandatory and represents the name of the icon.
&<variant> is optional and represents the variant of the icon. Not all icons and libraries support variants. When you specify a variant in this syntax, you must specify it after the icon’s name. You must separate the variant from the icon name with an ampersand (&). When you don’t specify a variant, Platen uses the library’s default variant.
&<library> is optional and represents the library the icon belongs to. When you specify a library in this syntax, you must specify it after the icon’s name and variant. You must separate the library from the icon name or variant with an at sign (@). When you don’t specify a library, Platen uses the configured default library.

You can find the list of available icons in the default library in Shoelace’s documentation.

`preset` #

Specify the name of the preset to use, if any. If the preset is defined in a subfolder, specify the dot-path relative to data/platen/buttons. For example, the preset defined in data/platen/buttons/flagrant_garden/home would be specified as flagrant_garden.home.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`rel` #

Use this value to set the [sref:rel] to define the relationship of the linked URL as a list of link types. When specifying multiples values, specify them together as a space-separated string.

The default value is noreferrer noopener. Set this value to an empty string to remove the attribute from the rendered button.

Valid values are:

alternate
author
bookmark
external
help
license
me
next
nofollow
noopener
noreferrer
opener
prev
search

For more information on valid values, see the documentation for the rel attribute.

This option isn’t valid with the legacy button.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

`size` #

Use this attribute to specify the size of the rendered button. The default size is medium.

This option isn’t valid with the legacy button.

Required: false
Type: Enum
ValidValues:
- small
- medium
- large

`suffix_icon` #

Use this attribute to insert an icon after your label text. You can specify the icon as a string using the shorthand syntax for icons.

This option isn’t valid with the legacy button.

Specify the text wrapped in quotes, like "this".

Required: false
Type: String

Shorthand Syntax #

The shorthand syntax for icons in Platen is <name>[&<variant>][@<library>], where:

<name> is mandatory and represents the name of the icon.
&<variant> is optional and represents the variant of the icon. Not all icons and libraries support variants. When you specify a variant in this syntax, you must specify it after the icon’s name. You must separate the variant from the icon name with an ampersand (&). When you don’t specify a variant, Platen uses the library’s default variant.
&<library> is optional and represents the library the icon belongs to. When you specify a library in this syntax, you must specify it after the icon’s name and variant. You must separate the library from the icon name or variant with an at sign (@). When you don’t specify a library, Platen uses the configured default library.

`target` #

Use this attribute to set the target attribute on the rendered button to tell the browser where to open the link. Note that when using this attribute, you will need to override the rel attribute or the links won’t work.

This option isn’t valid with the legacy button.

Required: false
Type: Enum
ValidValues:
- _blank
- _parent
- _self
- _top

`variant` #

Use this attribute to change the theme of the rendered button.

The text variant is a special variant that removes the borders and background color of the button styling only the label. The button has the same target area for interactions.

This option isn’t valid with the legacy button.

Required: false
Type: Enum
ValidValues:
- default
- primary
- success
- neutral
- warning
- danger
- text

`width` #

Use this attribute to set a custom width for the rendered button. This overrides the width set by the button’s size. This is a simplistic style option for when the only style you want to override for your button is its dimensions. It’s usually better and more maintainable to define a custom class for your buttons. For more information on styling your buttons, see Styling.

This option isn’t valid with the legacy button.

Specify a valid CSS length wrapped in quotes. For example, you could specify "10rem" to set the value to ten times the size of root elment’s font-size.

Required: false
Type: String

Presets #

You can define any number of preset buttons reusably in your site’s data. Any YAML files you add in the data/platen/buttons folder are available for use. You can use folders to group presets together.

The available properties you can specify for a preset are listed below and match the available attributes and inputs. When used together with attributes and inputs, any value specified as an attribute or input overrides the value specified in the preset’s definition.

Preset Definition

Here we define a preset for linking to the Flagrant Garden coop in data/platen/buttons/platenio.yaml:

destination: https://flagrant.garden
label_text:  _Flagrant Garden_
prefix_icon:
  name: flower3
  style: >-
    filter: invert(.7)sepia(1)saturate(.5)hue-rotate(270deg);

Markdown Usage

Then, in our markdown, we use the button markup and reference the preset:

![button:Flagrant Garden Coop]()
{
  preset="flagrant_garden"
  .extra-flagrant
  .extra-garden
}

Which is processed to the equivalent YAML internally:

class:      extra-flagrant extra-garden
preset:     flagrant_garden
label_text: Flagrant Garden Coop

Merged Values

Now that we have both the values from the preset and Markdown, Platen combines them into:

class:       extra-flagrant extra-garden
destination: https://flagrant.garden
label_text:  Flagrant Garden Coop
prefix_icon:
  name: flower3
  style: >-
    filter: invert(.7)sepia(1)saturate(.5)hue-rotate(270deg);

Because both the preset and the markdown specify a value for label_text, the value from Markdown is used. If it had been written as ![button:]() instead, the value from flagrant_garden.yaml would’ve been used.

Only the preset defines a value for the button’s destination source, so that value is used.

The preset doesn’t define any classes but the Markdown does, so those are added for use.

Flagrant Garden Coop

Careful!

When you use a preset, inputs, and attributes together, the values specified as an input or attribute always override any values from the preset. If you specify a class as an attribute, only classes from the attribute are used, not the value of the class property in the preset.

If you want to use extensible values, you probably want to define a style or add another preset instead.

`circle` #

Use this property to make the button render as a circle just large enough to hold the label_icon. If this property is set without a label icon, it’s ignored.

This option isn’t valid with the legacy button.

`class` #

Specify one or more classes to add to the button’s element. By default, it has only the platen-btn class.

You can specify this value either as a string (if you only need to add one class) or as a list of strings.

Single Class

class: sepia

Multiple Classes

class:
  - big
  - shadowed

You can also define the default classes for your buttons with the platen.markup.buttons.classes setting for your site configuration. Values from your site configuration are overridden by this property in your preset. For more information, see Configuration.

`destination` #

Specify the URL for where the button should take a visitor when clicked. This value is used as the href attribute of the button’s element.

`download_name` #

Use this property to tell the browser to download the linked file with this name. This is only useful when the destination input or preset property is a file.

This option isn’t valid with the legacy button.

`height` #

Use this property to set a custom height for the rendered button. This overrides the height set by the button’s size. This is a simplistic style option for when the only style you want to override for your button is its dimensions. It’s usually better and more maintainable to define a custom class for your buttons. For more information on styling your buttons, see Styling.

This option isn’t valid with the legacy button.

`html_attributes` #

Use this property to add any number of HTML attributes to the button element. This property gives you more flexibility for extending and overriding the element without needing a custom template.

This value must be a map of key-value pairs where the key is the name of the attribute and value is the attribute’s value. Any values that aren’t a string are converted into one before inserting them into the element’s HTML.

For example, you could define the lang global attribute to set the language of the button to Italian:

html_attributes:
  lang: it

If any of the keys in this property conflict with a key that is added by another property or an attribute in the markup, the other property or attribute is applied instead of the value for the key in this property. For example, while you could specify size with this property, it would be overrided by the size attribute or preset property if either of them is set.

This option isn’t valid with the legacy button.

`label_icon` #

Use this property to insert an icon instead of label text. When you specify this property, Platen ignores the value for label_text.

If this property’s value is a string, it must be the shorthand syntax for an icon. With this property, you can also define attributes to pass to the label icon.

As String (Shorthand Syntax)

In this case, the value of label_icon must use the shorthand syntax for icons in Platen.

The shorthand syntax for icons in Platen is <name>[&<variant>][@<library>], where:

<name> is mandatory and represents the name of the icon.
&<variant> is optional and represents the variant of the icon. Not all icons and libraries support variants. When you specify a variant in this syntax, you must specify it after the icon’s name. You must separate the variant from the icon name with an ampersand (&). When you don’t specify a variant, Platen uses the library’s default variant.
&<library> is optional and represents the library the icon belongs to. When you specify a library in this syntax, you must specify it after the icon’s name and variant. You must separate the library from the icon name or variant with an at sign (@). When you don’t specify a library, Platen uses the configured default library.

# data/platen/buttons/label_icon/string.yaml
label_icon: cog&solid@boxicons

As Object with Properties

In this case, the value of label_icon is an object with defined properties. You must specify the name property for the icon. You can specify the library and variant properties as needed.

You can also pass any valid global HTML attribute in the options map for the icon, like class or style. Those attributes are passed through to the icon element.

Note that the style property in this example uses the >- syntax after the key name. The content is then indented and it defines one CSS style setting on each line. We strongly recommend you use this syntax—it’s more readable and easier to maintain. Remember that inline styles must have a semi-colon (;) after each style entry.

# data/platen/buttons/label_icon/object.yaml
label_icon:
  library: boxicons
  name:    cog
  variant: solid
  style: >-
    color: #417505;
    opacity: 50%;

This option isn’t valid with the legacy button.

`name` #

If you’re specifying the label_icon as an object, this property is required. The value must be the name of the icon. You can use any valid icon from Shoelace’s default library or the name of an icon from any other configured icon library.

`label` #

Specify an alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices.

`library` #

Specify the library the icon belongs to. If you omit this property, Platen uses the configured default icon library.

`src` #

Specify the URL of an SVG file to use as the icon. Be sure you trust the content you are including, as it will be executed as code and can result in XSS attacks.

If you specify this option, Platen ignores the values for name, variant, and library for the icon.

`variant` #

Specify the variant of the icon to use. Not all icons and libraries support variants. When you don’t specify a variant, Platen uses the library’s default variant.

Other Attributes #

You can specify any other HTML attributes for the icon. The key is used as the name of the attribute and the value is the attribute’s value. Any values that aren’t a string are converted into one before inserting them into the element’s HTML.

`label_text` #

Specifies the Markdown text to render as the button’s visible text. Unlike when defining this value as input, do not prefix this value with button:. This value can also span multiple lines, unlike when you define it as input.

Single Line

label_text: Flagrant Garden

Long Line

In this example, the value is an arbitrarily long block of text. By declaring the key as label_text: >-, you’re telling Platen to treat the value as one very long line of text, replacing line breaks with spaces and trimming any extra whitespace.

In this usage, the value must start on the next line and indented 2 spaces. The rest of the lines of text must start at the same indent level.

label_text: >-
  This line of Markdown is much longer than you could typically fit into a
  button. It might not be aesthetically pleasing to have a button with this
  much text.

  Notice that even though this looks like two paragraphs in the work, it is
  treated as one very long line because of the `>-` syntax used.  
height: auto
width: 100%

This line of Markdown is much longer than you could typically fit into a button. It might not be aesthetically pleasing to have a button with this much text. Notice that even though this looks like two paragraphs in the work, it is treated as one very long line because of the `>-` syntax used.

Notice that this example also needs to use the height and width settings to get the button to display the entire text instead of clipping it. This works, but it still doesn’t look very good. You could further style it with a custom class, but we strongly advise you not to make buttons with this much text.

Paragraphs

In this example, the value is an arbitrarily long block of text representing two paragraphs. By declaring the key as label_text: |-, you’re telling Platen to treat the value as a block of text, where the line breaks are kept but other trailing whitespace is removed.

In this usage, the value must start on the next line and indented 2 spaces. The rest of the lines of text must start at the same indent level.

label_text: |-
  This block of Markdown is much longer than you could typically fit into a
  button. It might not be aesthetically pleasing to have a button with this
  much text.

  Notice that this does produce two paragraphs of text for the button because
  Platen keeps the line breaks. The blank line between these paragraphs ensures
  they're actually rendered as paragraphs.  
height: auto
width: 100%

This block of Markdown is much longer than you could typically fit into a button. It might not be aesthetically pleasing to have a button with this much text. Notice that this does produce two paragraphs of text for the button because Platen keeps the line breaks. The blank line between these paragraphs ensures they're actually rendered as paragraphs.

`legacy` #

Use this property to set whether Platen uses the legacy template for rendering buttons.

Specify true to use the legacy template for the buttons element, or false to use the <sl-button> element from Shoelace. If this value isn’t set in the preset or markup, Platen uses the value of the platen.markup.buttons.use_legacy setting defined in your site configuration. For more information, see Configuration.

When this setting is true, the attributes and preset properties in the list below aren’t valid. If you use them when legacy is true, Platen warns you about the incompatibility and ignores the invalid options.

circle
download_name
height
outline
pill
prefix_icon
rel
size
suffix_icon
target
variant
width

`outline` #

Use this property to render the button with an outline instead of as a block with background color.

You can also define whether your buttons are rendered with an outline with the platen.markup.buttons.outline setting for your site configuration. Values from your site configuration are overridden by this preset property. For more information, see Configuration.

This option isn’t valid with the legacy button.

`pill` #

Use this property to render the button with rounded corners instead of as a rectangle.

You can also define whether your buttons are rendered with rounded corners with the platen.markup.buttons.pill setting for your site configuration. Values from your site configuration are overridden by this preset property. For more information, see Configuration.

This option isn’t valid with the legacy button.

`prefix_icon` #

Use this property to insert an icon before your label text.

If this property’s value is a string, it must be the shorthand syntax for an icon. With this property, you can also define attributes to pass to the prefix icon.

As String (Shorthand Syntax)

In this case, the value of prefix_icon must use the shorthand syntax for icons in Platen.

The shorthand syntax for icons in Platen is <name>[&<variant>][@<library>], where:

<name> is mandatory and represents the name of the icon.
&<variant> is optional and represents the variant of the icon. Not all icons and libraries support variants. When you specify a variant in this syntax, you must specify it after the icon’s name. You must separate the variant from the icon name with an ampersand (&). When you don’t specify a variant, Platen uses the library’s default variant.
&<library> is optional and represents the library the icon belongs to. When you specify a library in this syntax, you must specify it after the icon’s name and variant. You must separate the library from the icon name or variant with an at sign (@). When you don’t specify a library, Platen uses the configured default library.

# data/platen/buttons/prefix/string.yaml
prefix_icon: cog&solid@boxicons

String Configuration

As Object with Properties

In this case, the value of prefix_icon is an object with defined properties. You must specify the name property for the icon. You can specify the library and variant properties as needed.

You can also pass any valid global HTML attribute in the options map for the icon, like class or style. Those attributes are passed through to the icon element.

# data/platen/buttons/prefix/object.yaml
prefix_icon:
  library: boxicons
  name:    cog
  variant: solid
  style: >-
    color: #417505;
    opacity: 50%;

Object Configuration

This option isn’t valid with the legacy button.

`name` #

If you’re specifying the prefix_icon as an object, this property is required. The value must be the name of the icon. You can use any valid icon from Shoelace’s default library or the name of an icon from any other configured icon library.

`label` #

Specify an alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices.

`library` #

Specify the library the icon belongs to. If you omit this property, Platen uses the configured default icon library.

`src` #

Specify the URL of an SVG file to use as the icon. Be sure you trust the content you are including, as it will be executed as code and can result in XSS attacks.

If you specify this option, Platen ignores the values for name, variant, and library for the icon.

`variant` #

Specify the variant of the icon to use. Not all icons and libraries support variants. When you don’t specify a variant, Platen uses the library’s default variant.

Other Attributes #

`rel` #

Use this property to set the [sref:rel] to define the relationship of the linked URL as a list of link types. When specifying multiples values, specify them together as a space-separated string.

The default value is noreferrer noopener. Set this value to an empty string to remove the property from the rendered button.

Valid values are:

alternate
author
bookmark
external
help
license
me
next
nofollow
noopener
noreferrer
opener
prev
search

For more information on valid values, see the documentation for the rel attribute.

This option isn’t valid with the legacy button.

`size` #

Use this property to specify the size of the rendered button. The default size is medium.

This option isn’t valid with the legacy button.

`suffix_icon` #

Use this property to insert an icon after your label text.

If this property’s value is a string, it must be the shorthand syntax for an icon. With this property, you can also define attributes to pass to the label icon.

As String (Shorthand Syntax)

In this case, the value of suffix_icon must use the shorthand syntax for icons in Platen.

The shorthand syntax for icons in Platen is <name>[&<variant>][@<library>], where:

<name> is mandatory and represents the name of the icon.
&<variant> is optional and represents the variant of the icon. Not all icons and libraries support variants. When you specify a variant in this syntax, you must specify it after the icon’s name. You must separate the variant from the icon name with an ampersand (&). When you don’t specify a variant, Platen uses the library’s default variant.
&<library> is optional and represents the library the icon belongs to. When you specify a library in this syntax, you must specify it after the icon’s name and variant. You must separate the library from the icon name or variant with an at sign (@). When you don’t specify a library, Platen uses the configured default library.

# data/platen/buttons/suffix/string.yaml
suffix_icon: cog&solid@boxicons

String Configuration

As Object with Properties

In this case, the value of suffix_icon is an object with defined properties. You must specify the name property for the icon. You can specify the library and variant properties as needed.

You can also pass any valid global HTML attribute in the options map for the icon, like class or style. Those attributes are passed through to the icon element.

# data/platen/buttons/suffix/object.yaml
suffix_icon:
  library: boxicons
  name:    cog
  variant: solid
  style: >-
    color: #417505;
    opacity: 50%;

Object Configuration

This option isn’t valid with the legacy button.

`name` #

If you’re specifying the suffix_icon as an object, this property is required. The value must be the name of the icon. You can use any valid icon from Shoelace’s default library or the name of an icon from any other configured icon library.

`label` #

Specify an alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices.

`library` #

Specify the library the icon belongs to. If you omit this property, Platen uses the configured default icon library.

`src` #

Specify the URL of an SVG file to use as the icon. Be sure you trust the content you are including, as it will be executed as code and can result in XSS attacks.

If you specify this option, Platen ignores the values for name, variant, and library for the icon.

`variant` #

Specify the variant of the icon to use. Not all icons and libraries support variants. When you don’t specify a variant, Platen uses the library’s default variant.

Other Attributes #

`target` #

Use this property to set the target attribute on the rendered button to tell the browser where to open the link. Note that when using this property, you will need to override the rel property or the links won’t work.

This option isn’t valid with the legacy button.

`variant` #

Use this property to change the theme of the rendered button.

The text variant is a special variant that removes the borders and background color of the button styling only the label. The button has the same target area for interactions.

This property isn’t valid with the legacy button.

`width` #

Use this property to set a custom width for the rendered button. This overrides the width set by the button’s size. This is a simplistic style option for when the only style you want to override for your button is its dimensions. It’s usually better and more maintainable to define a custom class for your buttons. For more information on styling your buttons, see Styling.

This property isn’t valid with the legacy button.

Legacy Template #

The legacy template uses the standard <a> (anchor) HTML element instead of the more customizable Shoelace element. It doesn’t support as many options and will eventually be removed.

We strongly suggest you update your themes to use the new template.

Currently, Platen uses the legacy template by default and warns on its use. You can override these behaviors in the configuration. To use the new template by default, set platen.markup.buttons.use_legacy to false. To continue using the legacy buttons element without warnings, set platen.markup.buttons.warn_on_legacy to false.

Configuration #

Several of the options for this markup can be configured in your site configuration or Platen’s parameter data. The most convenient option is to edit the data/_params/platen/markup.yaml file. Except for the warn_on_legacy setting, which is site-wide, every configuration setting can by overridden by the attributes in your markup or properties in a preset.

The default values for this markup’s rendering options are defined below:

buttons:
  classes: []
  size: null
  outline: null
  pill: null
  variant: null
  use_legacy: true
  warn_on_legacy: true

classes: If you set classes to a list of strings, Platen adds them to the rendered buttons. If you specify any classes for a buttons markup as an attribute or preset property, those are used instead.
size: If you want to change the default size for your buttons, set this value to small, medium, or large. The size attribute and preset property override this configuration setting.
outline: If you want to set your buttons to display outlined instead of solid by default, set this value to true. The outline attribute and preset property override this configuration setting.
pill: If you want to set your buttons to display with rounded corners by default, set this value to true. The pill attribute and preset property override this configuration setting.
variant: If you want to change the default variant for your buttons, set this value to a valid variant. The variant attribute and preset property override this configuration setting.
use_legacy: If you want your buttons rendered with the new default template to use the full set of options, set this value to false. It defaults to true now, but will default to false in the future. Eventually, the legacy template will be removed entirely.
warn_on_legacy: If you want to silence the warnings Platen emits when you use the legacy template, set this value to false.

You can find the full set of options for this markup in the configuration reference.

Styling #

This markup uses the SCSS defined in the styles/markup/_buttons.scss file in your assets folder, which defaults to assets in your project root.

This section discusses styling the non-legacy template. Instead of applying custom styles to the legacy template, we strongly recommend you migrate to the non-legacy template. In the near future, it will become the default. Eventually, the legacy template will be removed entirely.

Buttons SCSS #

.markdown sl-button.platen-btn {
  &[data-custom-height="true"] {
    &::part(base) {
      height: var(--custom-height);
      align-items: center;
    }
  }
  &[data-custom-width="true"] {
    width: var(--custom-width);
    &::part(base) {
      white-space: normal;
    }
  }
}

The SCSS for buttons only applies to <sl-button> elements in a container that has the markdown class and only when the element itself has the platen-btn class. This keeps the style from being unintentionally applied anywhere else.

The style:

Handles when the height attribute or preset property is set for a button. When it is, Platen adds the data-custom-height attribute to the <sl-button> element and adds the --custom-height CSS variable as an inline style.
The SCSS applies only when the data-custom-height attribute is set. It overrides the button’s container height and ensures that they align vertically instead of at the top.
Handles when the width attribute or preset property is set for a button. When it is, Platen adds the data-custom-width attribute to the <sl-button> element and adds the --custom-width CSS variable as an inline style.
The SCSS applies only when the data-custom-width attribute is set. It overrides the button’s width and sets ensures that the label text breaks across lines as needed.

Extending the Style #

You can extend this style by adding SCSS into the styles/_custom.scss file in your assets folder or by copying the provided style into styles/markup/_buttons.scss and editing it.

When you do, make sure your styles use this selector as the base. All of your styles should be contained in this selector or one of its children.

.markdown sl-details.platen-btn {
  // Your styles here
}

The rest of this section is a list of selectors you might find useful when styling the rendered buttons.

[slot="prefix"]: This selector targets the <sl-icon> that Platen adds when you use the prefix_icon attribute or preset property.
[slot="suffix"]: This selector targets the <sl-icon> that Platen adds when you use the suffix_icon attribute or preset property.
&::part(base): This selector targets the base container for the rendered button.
&::part(prefix): This selector targets the container that wraps the prefix icon.
&::part(label): This selector targets the container that wraps the button’s label text.
&::part(suffix): This selector targets the container that wraps the suffix icon.

Overriding the Style #

You can completely override the provided style by defining the styles/markup/_buttons.scss file in your assets folder.

You can also create a new style module in the styles/markup folder and set platen.markup.buttons.style in your site configuration 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.

Syntax #

Basic Block Syntax #

Reference Link Block Syntax #

Examples #

1. Minimal Example #

2. Button Sizes #

3. Button Variants #

4. Pill Buttons #

5. Buttons with Icons #

6. With Classes #

7. With Preset #

8. With Legacy Template #

Inputs #

alt_text (as label_text) #

source (as destination) #

title (as label_icon) #

Attributes #

circle #

class #

download_name #

height #

legacy #

outline #

pill #

prefix_icon #

Shorthand Syntax #

preset #

rel #

size #

suffix_icon #

Shorthand Syntax #

target #

variant #

width #

Presets #

circle #

class #

destination #

download_name #

height #

html_attributes #

label_icon #

name #

label #

library #

src #

variant #

Other Attributes #

label_text #

legacy #

outline #

pill #

prefix_icon #

name #

label #

library #

src #

variant #

Other Attributes #

rel #

size #

suffix_icon #

name #

label #

library #

src #

variant #

Other Attributes #

target #

variant #

width #

Legacy Template #

Configuration #

Styling #

Buttons SCSS #

Extending the Style #

Overriding the Style #

`alt_text` (as `label_text`) #

`source` (as `destination`) #

`title` (as `label_icon`) #

`circle` #

`class` #

`download_name` #

`height` #

`legacy` #

`outline` #

`pill` #

`prefix_icon` #

`preset` #

`rel` #

`size` #

`suffix_icon` #

`target` #

`variant` #

`width` #

`circle` #

`class` #

`destination` #

`download_name` #

`height` #

`html_attributes` #

`label_icon` #

`name` #

`label` #

`library` #

`src` #

`variant` #

`label_text` #

`legacy` #

`outline` #

`pill` #

`prefix_icon` #

`name` #

`label` #

`library` #

`src` #

`variant` #

`rel` #

`size` #

`suffix_icon` #

`name` #

`label` #

`library` #

`src` #

`variant` #

`target` #

`variant` #

`width` #