A macro (“macroinstruction”) is a programmable pattern which translates a certain sequence of input into a preset sequence of output.

Macros can be registered to certain renderers, and can take parameters that control how they are expanded.

All macros look like this: {{name:parameters}}

Makros may take parameters. Two parameters are processed before the macro is executed:

  • only: macro is executed only for the specified preset(s)
  • skip: macro is skipped for the specified preset(s)
Presets are separated with ‘ ’

Examples:

{{index:ignore=jekyll|all-in-one}}_ {{index:only=jekyll}}_

Custom Macros

Creating custom macros is easy, they only need to provide a render method:

def render_my_macro(config, structure, *args, **kwargs):
    return "macros will be replaced with this text"

Macros have access to the project configuration and to the content structure, so that they can create indexes and links, and are able to react on configuration parameters.

Example: the index below is rendered via {{index:root=indexes,sort=title,style=list}})