Skip to main content

Plugins

Plugins are used to extend Doxicity’s functionality. For your convenience, a number of useful first-party plugins come out of the box. You can enable as many or as few as you’d like.

Activating Plugins

Plugins are imported and activated in your config file like this.

// doxicity.config.js
import myPlugin from 'doxicity/dist/plugins.js';

export default {
  // ...
  plugins: [
    myPlugin({
      /* plugin options go here */
    })
  ]
};

Plugins are be executed in the same order they appear in the plugins array.

First-party Plugins

The following plugins ship with the official Doxicity package. This project is still young, so for now please see the source of each plugin (linked below) to see which config options are available. Additional third-party plugins will soon be found on npm .

Example usage:

// doxicity.config.js
import { activeLinks, anchorHeadings, highlightCode, search } from 'doxicity/plugins';

export default {
  // ...
  plugins: [activeLinks(), anchorHeadings(), highlightCode(), search()]
};

Writing Your Own Plugins

Many static site generators offer a ton of hooks for plugin authors to tap into. However, this usually results in confusion and unintended results. For example, how does each hook affect rendering? What if a plugin runs too soon or too late? What if it only applies to markdown content and not the rest of the HTML? With so many hooks, it’s difficult to keep track of which plugins are doing what and when.

Doxicity simplies this by offering only a limited number of hooks and making it easy to mutate the entire page — not just the markdown content. At the heart of Doxicity’s plugin API is the transform hook. It provides you with a Document object that you can mutate just like you would in a browser.

Here’s a contrived example that prepends the text “Wow ” to every paragraph of every page.

const wowPlugin = {
  transform: doc => {
    doc.querySelectorAll('p').forEach(p => {
      p.innerHTML = 'Wow ' + p.innerHTML;
    });
  }
};

export default wowPlugin;

This may seem silly, but the important thing to note is that you have complete control over every page. You can change the template’s structure, add or remove things from the DOM, mutate existing elements, and more.

Plugin Hooks

The following hooks are currently available to plugin authors.

Name Description
transform Hooks into the DOM transform phase, allowing you to mutate the document object before it gets turned into HTML. Use this for all types of DOM manipulation.
afterTransform Hooks into the raw HTML string after all rendering and transformations are complete. Use this for formatters.
afterAll Hooks into the pages after they’ve been rendered and after all transforms have completed. Use this when you need to do something after all pages have been processed.

Every Doxicity plugin must adhere to the DoxicityPlugin interface. The interface is described in TypeScript, but you can write plugins in JavaScript as well. All hooks can be synchronous or asynchronous.

export interface DoxicityPlugin {
  transform?: (doc: Document, page: DoxicityPage, config: DoxicityConfig) => Document | Promise<Document>;
  afterTransform?: (html: string, page: DoxicityPage, config: DoxicityConfig) => string | Promise<string>;
  afterAll?: (pages: DoxicityPage[], config: DoxicityConfig) => void | Promise<void>;
}