Writing Plugins

Writing Plugins

MarkBind plugins are js scripts that are loaded and run during the page generation. MarkBind allows plugins to modify a page's content during the page generation process, amongst other things.

This page details the available interfaces you may use to write plugins.

Rendering

MarkBind provides two entry points for modifying the page generated - processNode and postRender.

processNode operates during the HTML processing stage of MarkBind, where each node (HTML element) processed is passed to the entry point.

In most cases, this is sufficient, and more performant since this ties directly into MarkBind's HTML processing.

However, if you need to operate on the page as a whole, or you need access to the frontmatter of the page, you may use the postRender interface instead, which operates on the HTML content after it is processed by MarkBind.

• processNode(pluginContext, node): Called before MarkBind renders the source from Markdown to HTML.
  • pluginContext: User provided parameters for the plugin. This can be specified in the site.json.
  • node: A domhandler node object, which represents a HTML element. This object may be directly manipulated for simple operations, or operated on using cheerio.
• postRender(pluginContext, frontmatter, content): Called after the HTML is rendered
  • pluginContext: User provided parameters for the plugin. This can be specified in the site.json.
  • frontmatter: The frontmatter of the page being processed, in case any frontmatter data is required.
  • content: The rendered HTML.
  • Returns: the post-processed HTML string

An example of a plugin is shown below. The plugin shows two ways of appending a paragraph of text to a specific div in the Markdown files:

// myPlugin.js

const cheerio = module.parent.require('cheerio');

module.exports = {
  processNode: (pluginContext, node) => {
    if (node.attribs.id === 'my-div') {
      cheerio(node).append(pluginContext.content);
    }
  },
  postRender: (pluginContext, frontmatter, content) => {
    const $ = cheerio.load(content, { xmlMode: false });
    // Modify the page...
    $('#my-div').append(pluginContext.content);
    return $.html();
  },
};

    

    


    
    

// site.json

{
  ...
  "plugins": [
    "myPlugin"
  ],
  "pluginsContext": {
    "myPlugin": {
      "content": "<p>Hello World</p>",
    }
  }
}

    

    


    
    

// index.md

...
<div id="my-div">
</div>

    

    


    
    

Assets

Plugins can implement the methods getLinks and getScripts to add additional assets to any page.

• getLinks(pluginContext, frontmatter, content): Called to get link elements to be added to the head of the page.
  • pluginContext: User provided parameters for the plugin. This can be specified in the site.json.
  • frontmatter: The frontmatter of the page being processed, in case any frontmatter data is required.
  • content: The rendered HTML.
  • Returns: an array of strings containing link elements to be added.
• getScripts(pluginContext, frontmatter, content): Called to get script elements to be added after the body of the page.
  • pluginContext: User provided parameters for the plugin. This can be specified in the site.json.
  • frontmatter: The frontmatter of the page being processed, in case any frontmatter data is required.
  • content: The rendered HTML.
  • Returns: an array of strings containing script elements to be added.

An example of a plugin which adds links and scripts to the page:

// myPlugin.js

module.exports = {
  getLinks: (pluginContext, frontmatter, content) => ['<link rel="STYLESHEET_LINK">'],
  getScripts: (pluginContext, frontmatter, content) => [
    '<script src="SCRIPT_LINK"></script>',
    '<script>alert("hello")</script>'
  ],
};


    

    


    
    

This will add the following link and script elements to the page:

• <link rel="stylesheet" href="STYLESHEET_LINK">
• <script src="SCRIPT_LINK"></script>
• <script>alert("hello")</script>

Tag Behaviour

MarkBind also provides several convenient interfaces that can be used alone, or in conjunction with the rendering interfaces to modify how tags are processed.

To use these interfaces, add the tagConfig property to your plugin export:

module.exports = {
  tagConfig: {
    puml: {
      isSpecial: true,
      attributes: [
        {
          name: 'src',
          isRelative: true,
          isSourceFile: true,
        },
      ],
    },
  },
}

    

    


    
    

Tag Properties

Tag properties are top-level properties of the tag configuration object. The following table lists what these properties are used for:

Attribute Properties

The following table lists what the possible properties for configuring the attributes of a tag, and what they are used for:

Lifecycle hooks

You may also need to maintain some plugin state during site generation, then reset this when the site or pages are regenerated.

To do this, you may implement the beforeSiteGenerate method.

• beforeSiteGenerate(): Called during initial site generation and subsequent regenerations during live preview.
  • No return value is required.