Extend Blocks

Extending templating blocks is the best way to provide extra functionalities to authors.

The most common usage is to process the content within some tags at runtime. It's like filters, but on steroids because you aren't confined to a single expression.

Defining a new block

Blocks are defined by the plugin, blocks is a map of name associated with a block descriptor. The block descriptor needs to contain at least a process method.

module.exports = {
    blocks: {
        tag1: {
            process: function(block) {
                return "Hello "+block.body+", How are you?";
            }
        }
    }
};

The process should return the html content that will replace the tag. Refer to Context and APIs to learn more about this and GitBook API.

Handling block arguments

Arguments can be passed to blocks:

{% tag1 "argument 1", "argument 2", name="Test" %}
This is the body of the block.
{% endtag1 %}

And arguments are easily accessible in the process method:

module.exports = {
    blocks: {
        tag1: {
            process: function(block) {
                // block.args equals ["argument 1", "argument 2"]
                // block.kwargs equals { "name": "Test" }
            }
        }
    }
};

Handling sub-blocks

A defined block can be parsed into different sub-blocks, for example let's consider the source:

{% myTag %}
    Main body
    {% subblock1 %}
    Body of sub-block 1
    {% subblock 2 %}
    Body of sub-block 1
{% endmyTag %}