Block directives

A markdown block directive is a feature that allows embedding custom content within a markdown file. These directives are defined using a special syntax, utilizing the @ prefix, and are processed by Toucan to create dynamic or interactive content. They extend markdown’s basic capabilities.

Example:

@Link(url: "https://toucansites.com") { Click Me }

This could translate to the following HTML code:

<a href="https://toucansites.com">Click Me</a>

Markdown in Toucan can be extended with custom block directives, allowing the integration of custom UI components. These directives are defined in the theme configuration and offer a way to enrich the user interface by embedding custom elements directly into the content.

Custom directives

Theme developers can create a blocks folder within the theme directory. A YAML configuration is sufficient to define a custom block directive.

The following YAML configuration can be used to create a custom Link element:

name: link
parameters:
  - label: url
    default: ""
  - label: class
    default: ""
  - label: target
    default: "_blank"
removesChildParagraph: true
#requiresParentDirective: myContainer
#output: "<a class="{{class}}" href="{{url}}" target="{{target}}">{{contents}}</a>"
tag: a
attributes:
  - name: href
    value: "{{url}}"
  - name: target
    value: "{{target}}"
  - name: class
    value: "{{class}}"

This configuration allows markdown editors to use the @Link block directive with the following syntax to display a link:

@Link(url: "http://toucansites.com/") { This is a link }

Additional block directive examples can be found in the site’s source code on GitHub.

Reference guide