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

   PLUGIN_PATHS = ['./theme/plugins']
   PLUGINS = ['asfgenid', 'asfshell', 'asfdata', 'pelican-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.

   ASF_DATA_YAML = ".asfdata.yaml"
   ASF_DATA = {
        'data': ASF_DATA_YAML,
        'metadata': { },
        'debug': True
   }
   

   • The asfgenid plugin configures its features.

   ASF_GENID = {
       'metadata': True,
       'elements': True,
       'headings': True,
       'permalinks': True,
       'toc': True,
       'toc_headers': r"h[1-6]",
       'debug': False
   }
   

   • The asfshell plugin runs shell scripts as found in your Pelican Configuration

   ASF_SHELL = [
       '/bin/bash shell.sh'
   ]
   

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 pelican-gfm plugin. This code is in a private repository - ask Infra. 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.