Plugin Architecture

The plugins used operate at various points in a pelican build. Pelican uses signals at various points. These are documented here. At a high level consider the following sequence of events:

  1. Pelican Settings. Settings for a Pelican Build are in your Pelican Configuration

    These are automatically created according to your pelicanconf.yaml into a settings file that would have something like:

    PLUGIN_PATHS = ['./theme/plugins']
    PLUGINS = ['asfgenid', 'asfrun', 'asfdata', 'gfm', 'asfreader', 'asfcopy']
  2. Init (initialized). At this point any ASF_DATA is read into a metadata dictionary made available in every page.

    • The asfdata plugin reads an .asfdata.yaml file and creates the metadata dictionary.
      data: asfdata.yaml
    ASF_DATA_YAML = "asfdata.yaml"
    ASF_DATA = {
         'data': ASF_DATA_YAML,
         'metadata': { },
         'debug': True
      unsafe: yes
      metadata: yes
      elements: yes
      headings_depth: 4
      permalinks: yes
      toc_depth: 4
      tables: yes
    ASF_GENID = {
        'unsafe': True,
        'metadata': True,
        'elements': True,
        'headings': True,
        'permalinks': True,
        'toc': True,
        'toc_headers': r"h[1-6]",
        'debug': False
        - /bin/bash
    ASF_RUN = [
        - /bin/bash
  3. Readers (readers_init). Two important readers are set at this point. Readers are responsible for transforming page files to html and providing a metadata dictionary

    • GFMReader by the gfm plugin. Transforms GitHub Flavored Markdown(GFM) to HTML.
      • .md
      • .markdown
      • .mkd
      • .mdown
    • ASFReader by the asfreader plugin. Transforms an ezt template into GFM and then to HTML.
      • .ezmd
  4. Content Init (content_object_init). This is signaled after a Reader has processed content. At this point plugins can review, record, and transform the html content.

    • The asfgenid plugin performs a number of steps. Some of the steps are optional.
      • Metadata transformation by looking up {{ key_expression }} in the page metadata.
      • Inventory of existing id attributes.
      • Set id and class attributes specified by and {.class} syntax.
      • Assign id to all headings without ids.
      • Insert a Table of Contents if a [TOC] tag is present.
  5. Finalization (finalized). This is signalled after all content is generated and static files copied. At this point additional content can be copied and the final output analyzed.

    • The asfcopy plugin is an example. Here is copies files from the source tree. It could be modified to copy information in from external sources too.