Docusaurus Plugin Guide

Quick Start

// Remark plugin - transforms markdown AST
module.exports = function remarkPlugin(options = {}) {
  return async function transformer(ast, vfile) {
    const { visit } = require('unist-util-visit');

    visit(ast, 'link', (node) => {
      // Transform nodes
      node.data = node.data || {};
      node.data.hProperties = { className: 'custom' };
    });

    return ast;
  };
};

// In docusaurus.config.js:
// remarkPlugins: [require('./plugins/my-plugin')]

Core Principles

• 5 Plugin Types: Remark (markdown), Rehype (HTML), Lifecycle (routes/webpack), Theme (components), Content (custom data)
• Remark: Transforms markdown before HTML conversion, use unist-util-visit for AST traversal
• Rehype: Transforms HTML after compilation, processes HAST (HTML AST)
• Lifecycle: Most flexible, implements hooks like loadContent(), contentLoaded(), postBuild()
• Export function: Returns transformer (remark/rehype) or plugin object (lifecycle)

Reference Files

Detailed guides for each plugin type:

• [references/remark-plugins.md](references/remark-plugins.md) - Markdown transformation
• [references/rehype-plugins.md](references/rehype-plugins.md) - HTML processing
• [references/lifecycle-plugins.md](references/lifecycle-plugins.md) - Routes, webpack, global data
• [references/theme-plugins.md](references/theme-plugins.md) - Themes and swizzling
• [references/content-plugins.md](references/content-plugins.md) - Custom content types
• [references/package-structure.md](references/package-structure.md) - Publishing and config

<!-- PROGRESSIVE DISCLOSURE GUIDELINES:

• Keep this file ~50 lines total (max ~150 lines)
• Use 1-2 code blocks only (recommend 1)
• Keep description <200 chars for Level 1 efficiency
• Move detailed docs to references/ for Level 3 loading
• This is Level 2 - quick reference ONLY, not a manual

LLM WORKFLOW (when editing this file):

1. Write/edit SKILL.md
2. Format (if formatter available)
3. Run: claude-skills-cli validate <path>
4. If multi-line description warning: run claude-skills-cli doctor <path>
5. Validate again to confirm

-->