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.

With the first beta release, custom block directives can now be defined. These block directives are integrated into the themes, allowing theme authors to provide shorthands for common UI components.

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
params:
  - 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