Plugin System

Using Plugins

Plugins are sorted into two categories, compiler plugins and runtime plugins. Compiler plugins can affect how the project builds or modify the abstract syntax tree that Idyll produces. Runtime plugins can inspect and affect Idyll's reactive variable system in the browser.

See each plugin for specific installation and usage instructions.

Compiler Plugins

• Spellcheck
• Table of Contents
• Git Revisions

Runtime Plugins

• URL State Synchronization - serialize the article state into the URL. Allows readers to share the article in a particular configuration.
• Analytics - collect detailed usage data to learn how readers are interacting with your article.

To use multiple runtime plugins simultaneously, use idyll-context-compose.

Developing Plugins

This section details how to work with the custom hooks exposed by Idyll's compiler and runtime.

Compiler Plugins

The compiler is responsible for transforming Idyll markup into a machine-readable abstract syntax tree (AST). You may provide custom transformations for processing the AST at compile time.

These transformations are implemented as JavaScript modules.

const AST = require('idyll-ast');

module.exports = (ast) => {
  return AST.appendNode(ast, AST.createNode('div', {}, 'Hello World!') );
};

The above is code for a simple plugin that will append a div to the end of any AST that is provided. The idyll-ast module provides useful helper functions for manipulating the AST structure.

To add a compiler postprocessor to your project, update the configuration in package.json.

"idyll": {
  "compiler": {
    "postProcessors": ['my-idyll-postprocessor']
  }
}

Runtime Context

If you want to write custom code that reads or writes to Idyll's internal state, you can use the context API. This API provides events that fire whenever an Idyll variable is changed, and provides a function to push variable updates.

module.exports = (ctx) => {

  // The context has loaded,
  // initial data is available
  ctx.onInitialize(() => {
    const initialState = ctx.data();

    // Once the context has been initialized,
    // you can use the ctx.update() method
    // to modify data
    ctx.update({
       key: value
    })

  })

  // The application has mounted in the browser,
  // the window object is available
  ctx.onMount(() => {

  })

  // An update has been triggered,
  // arguments contain only modified data
  ctx.onUpdate((newData) => {

  })

}

To configure a custom context locally, you can point Idyll to the file where you've implemented this logic, in the package.json config.

"idyll": {
  "context": "./my-context-file.js"
}