Styled Text

Platen uses special notation for rendering styled text with an image link.

When used, it inserts an <span> (span) HTML element.

Syntax #

Basic Block Syntax #

![styled:text](source ['class'])
![styled:text][<ReferenceID>]


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

Examples #

1. Minimal Example #

Markdown Input
![styled:Flagrant Garden]()
HTML Output
<span >Flagrant Garden</span>
Rendered Output
Flagrant Garden

2. With Classes #

Markdown Input
![styled:Flagrant Garden](. "example foo")
HTML Output
<span class="example foo">Flagrant Garden</span>
Rendered Output
Flagrant Garden

3. With Defined Style #

Markdown Input
![styled:Flagrant Garden](baz)
HTML Output
<span class="baz"
      style="background: violet; border: 2px solid #e66465; color: black;">Flagrant Garden</span>
Rendered Output
Flagrant Garden

4. With Preset #

Markdown Input
An ![styled:](preset:example)
HTML Output
An <span class="baz foo bar"
      style="background: violet; border: 2px solid #e66465; color: black;">Example</span>
Rendered Output
An Example

Inputs #

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

Images use this syntax for their inputs:

![alt_text](source)

alt_text (as text) #

Specifies the Markdown text to render as the span’s text.

This value must start with the prefix styled:. For example, with ![styled:Platen](), text’s value would be Platen.

This value is rendered as inline Markdown.

RendersMarkdown: true
Required: true
Type: String

source (as style) #

Specify the name of the style to use, if any. If the style is defined in a subfolder, specify the dot-path relative to data/platen/styled_text/styles. For example, the style defined in data/platen/styled_text/styles/flagrant_garden/basic would be specified as flagrant_garden.basic. To specify the default style, set this value to . or _default. This value must be passed to specify the class option as the markup’s title.

If you prefix this value with preset:, it uses the value as the preset for the markup instead of the style. For more information, see Presets.

Specify the text without wrapping quotes, like this.

Required: true
Type: String

title (as class) #

Specify one or more classes to add to the span element. To specify this value, you must specify a value for source. To add classes to the default style, specify source as . or _default. For example, the markup ![styled:text](. "foo bar") adds the classes foo and bar to the default style.

Specify the text without wrapping quotes, like this.

Required: false
Type: String

Presets #

You can define any number of preset styled texts reusably in your site’s data. Any YAML files you add in the data/platen/styled_text 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 inputs. When used together with inputs, any value specified as an input overrides the value specified in the preset’s definition.

Work Definition

Here we define a preset for a reusable span in data/platen/styled_text/example.yaml:

text: Example
class:
  - foo
  - bar
style:
  - baz
Markdown Usage

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

![styled:Override](preset:example)

Which is processed to the equivalent YAML internally:

class: []
preset: example
text:   Override
Merged Values

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

class:
  - foo
  - bar
style: baz
text:  Override

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

Only the preset defines a value for the span’s style, so that value is used.

The preset also defines classes that the Markdown doesn’t override, so those are used.

Careful!

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

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

class #

Specify one or more classes to add to the span’s element. By default, it has no classes.

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

style #

Specify any number of styles to use for this preset. The styles are applied in the order they’re specified, with later styles overriding values from earlier ones.

You can specify a single style as a string or any number of styles as a list.

If the style is defined in a subfolder, specify the dot-path relative to data/platen/styled_text/styles. For example, the style defined in data/platen/styled_text/styles/flagrant_garden/basic would be specified as flagrant_garden.basic.

Single Style 
style: classic
Multiple Styles

In this example, because flagrant is specified last, any of its values that conflict with those from classic are used. Any values that are only defined in classic or flagrant are also used.

style:
  - classic
  - flagrant

text #

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

Single Line 
text: Flagrant Garden
Long Line

In this example, the text is an arbitrarily long block of text. By declaring the key as 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.

text: >-
  This line of Markdown is very long. It might not be aesthetically pleasing to
  have a span with this much text.

  Notice that even though this looks like two paragraphs in the preset, it is
  treated as one very long line because of the `>-` syntax used.

Here it is: This line of Markdown is very long. It might not be aesthetically pleasing to have a subscript with this much text. Notice that even though this looks like two paragraphs in the preset, it is treated as one very long line because of the >- syntax used.

Paragraphs

In this example, the text is an arbitrarily long block of text representing two paragraphs. By declaring the key as 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.

text: |-
  This line of Markdown is very long. It might not be aesthetically pleasing to
  have a span with this much text.

  Notice that this does produce two paragraphs of text for the span because
  Platen keeps the line breaks. The blank line between these paragraphs ensures
  they're actually rendered as paragraphs.

This line of Markdown is very long. It might not be aesthetically pleasing to have a subscript with this much text.

Notice that this does produce two paragraphs of text for the subscript because Platen keeps the line breaks. The blank line between these paragraphs ensures they’re actually rendered as paragraphs.

Styles #

You can use the defined styles feature to save different styles for your styled text as data. Any YAML files you add in the data/platen/styled_text/styles folder are available for use. You can use folders to group styles together.

Style settings are applied to the span (<span>) element the markup adds.

Default Style #

All styled texts inherit the empty default style, defined in data/platen/styled_text/styles/_default.yaml. You can override the default values by adding this file to your own site.

Careful when Overriding the Default File

When you add the _default.yaml file to your site data, you completely replace the default that Platen provides for all styled text. Make sure to do so carefully.

Most of the time, you’ll just want to define new styles instead.

classes #

Specify one or more classes to add to the span’s element. By default, it has no classes. For styles other than the default, these values are added to the default list of classes.

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 
classes: sepia
Multiple Classes 
classes:
  - big
  - shadowed

html_attributes #

This property defines the values for the HTML attributes of the span element added by the styled text markup. By default, none of them are defined.

You can add any of the global HTML attributes to the element. If your value needs to be split across multiple lines for readability, make sure to use the >- syntax after the key. This ensures that the value is treated as a single line with no trailing newline, which would break the attribute in the HTML.

For example:

Style Definition

This style (defined in data/platen/styled_text/styles/baz.yaml) defines the style attribute for the spans that use it. Note that it uses the >- syntax after the key.

classes:
  - baz
html_attributes:
  style: >-
    background: violet;
    border: 2px solid #e66465;
    color: black;
Markdown 
This is a styled ![styled:span](baz).
Rendered Output

This is a styled span.

Edit this page