Create your own extension

If you want to create yourself an extension, this is the place. You can take a look at the source of builtin extensions such as layouts or rst.

Available events to register to

The following are the different events which you can register your extension to.

Note

The arguments that are listed are given as arguments, not keyword_arguments.

doc-post-read

Arguments: site, document

Called after each document read.

site-post-read

Arguments: site

Called after all the documents have been read.

Empty extension

This will be the backbone of your extension, one that does nothing:

def do_nothing(site, document):
   pass

def setup(site):
   pass

Taika will use the setup() as entry point, so you should do your loading there.

Save it as a Python file and place it in the extensions and put it’s path into extensions_path, so we can find it and load it:

# taika.yml
...
extensions_path: /path/to/my_extensions
extensions:
   ...
   - my_extension  # <--
   ...
...

Adding functionality

Here, we use as example an extension that will print certain documents. First we print all the documents:

def print_document(site, document):
    print(document)

def setup(site):
    site.events.register("doc-post-read", print_document)

Note that we are registering our function using site.events.register.

Making the extension configurable

Now we want to print only certain documents, based on the frontmatter keys. But we want to configure which key is needed to print the documents, so we make our extension to read site.config.:

def print_document(site, document):
    on_key = site.config.get("print_document_on_key", DEFAULT_KEY)
    if on_key in document:
        print(document)

def setup(site):
    site.events.register("doc-post-read", print_document)

We used the get method on the configuration and we passed our key name and a default value. Later, we decide that we want to pass a list of keys which will trigger the print. We modify our extensions as follows:

def print_document(site, document):
    on_keys = site.config.get("print_document_on_keys", DEFAULT_KEYS)
    match = [key in document for key in on_keys]
    if any(match):
        print(document)

def setup(site):
    site.events.register("doc-post-read", print_document)

And that’s all! Be creative!