Guides

Plugins

Plugins bundle functionality into reusable extensions that hook into the Nizel pipeline.

Using a Plugin

import { useNizel } from 'nizel';
import { syntaxHighlightPlugin } from 'nizel-highlight';

const nizel = useNizel({
  plugins: [syntaxHighlightPlugin()],
});

Plugin Hooks

A plugin can implement one or more hooks:

interface NizelPlugin {
  name?: string;
  hooks?: {
    beforeParse?(markdown: string, options: NizelOptions): string;
    afterParse?(ast: NizelRootNode, options: NizelOptions): NizelRootNode | void;
    afterRender?(html: string, options: NizelOptions): string;
  };
}

beforeParse

Receives the raw Markdown string before parsing. Return the modified string.

const plugin = {
  name: 'add-footer',
  hooks: {
    beforeParse(markdown) {
      return markdown + '\n\n---\n*Generated by Nizel*';
    },
  },
};

afterParse

Receives the AST after parsing. Return the modified AST.

const plugin = {
  name: 'external-links',
  hooks: {
    afterParse(ast) {
      // modify link nodes to open externally
      return ast;
    },
  },
};

afterRender

Receives the rendered HTML string. Return the modified HTML.

const plugin = {
  name: 'wrap-tables',
  hooks: {
    afterRender(html) {
      return html.replace(/<table>/g, '<div class="table-wrapper"><table>');
    },
  },
};

Plugin Order

Plugins run in the order they appear in the plugins array. beforeParse hooks run left to right. afterParse hooks run left to right. afterRender hooks run left to right.

Official Plugins

Nizel publishes first-party plugins from the npm workspace:

All official plugins are TypeScript packages that publish dist JavaScript and .d.ts files. Plugin tests include unit coverage for package helpers and integration coverage through useNizel.