Docusaurus Plugins

This document explains how plugins are configured and managed in the SignalWire documentation platform.

Types of Plugins

Our documentation uses three types of plugins with different configuration locations:

1. Docusaurus Plugins - Configured in the plugins field of docusaurus.config.js - technical reference: https://docusaurus.io/docs/api/docusaurus-config#plugins
2. Remark Plugins - Configured in the presets field of docusaurus.config.js - technical reference: https://docusaurus.io/docs/markdown-features/plugins#installing-plugins
3. Rehype Plugins - Configured in the presets field of docusaurus.config.js - technical reference: https://docusaurus.io/docs/markdown-features/plugins#installing-plugins

---

Docusaurus Plugins

Plugin Configuration Structure

Docusaurus plugins are configured through:

1. config/pluginsConfig/index.ts - Main plugin registration
2. plugins field in docusaurus.config.js

// docusaurus.config.js
const config = {
  plugins: require("./config/pluginsConfig"), // plugins of the site
};

Plugin Registration Process

New Docusaurus plugins are added by:

1. Creating a plugin configuration file in /config/pluginsConfig/
2. Importing and adding the plugin to the plugins array in config/pluginsConfig/index.ts

// config/pluginsConfig/index.ts
import { PluginConfig } from '@docusaurus/types';
import { openapiPlugin } from './docusaurus-plugin-openapi-docs';
import { sassPlugin } from './sass';
import { markdownPrinterPlugin } from './markdown-printer';
import { showcasePlugin } from './guide-showcase';

const plugins: PluginConfig[] = [
  openapiPlugin,
  sassPlugin,
  markdownPrinterPlugin,
  showcasePlugin,
];

Current Docusaurus Plugins

1. OpenAPI Plugin

Location: /config/pluginsConfig/docusaurus-plugin-openapi-docs

• Handles OpenAPI documentation rendering
• Integrates with the docusaurus-theme-openapi-docs theme
• Used for API reference documentation

2. SASS Plugin

Location: /config/pluginsConfig/sass

• Enables SASS/SCSS stylesheet processing
• Allows for more maintainable styling using SASS features

3. Markdown Printer Plugin

Location: /config/pluginsConfig/markdown-printer

• Custom plugin for enhanced markdown processing
• Located in /plugins/markdown-printer

4. Guide Showcase Plugin

Location: /config/pluginsConfig/guide-showcase

• Handles the showcase features of the documentation
• Located in /plugins/docusaurus-plugin-showcase

---

Remark Plugins

Remark plugins are markdown processors configured in the presets field of docusaurus.config.js:

// docusaurus.config.js
const config = {
  presets: require("./config/presets.js"), // Contains remark plugin configuration
};

Current Remark Plugins

Located in /plugins/, we have several custom remark plugins:

1. remark-plugin-a11y-checker

Location: /plugins/remark-plugin-a11y-checker

• Checks markdown content for accessibility issues
• Ensures documentation meets accessibility standards
• Reports issues during build process

2. remark-plugin-api-table

Location: /plugins/remark-plugin-api-table

• Enhances API documentation tables
• Provides consistent formatting for API endpoints
• Supports additional metadata for API documentation

3. remark-plugin-image-to-figure

Location: /plugins/remark-plugin-image-to-figure

• Converts markdown images to HTML figure elements
• Allows for better image captions and accessibility
• Enhances image presentation in documentation

4. remark-plugin-vfile-reporter

Location: /plugins/remark-plugin-vfile-reporter

• Provides detailed reporting of markdown processing
• Helps identify issues in markdown files
• Useful for debugging and quality assurance

5. remark-plugin-yaml-and-json

Location: /plugins/remark-plugin-yaml-and-json

• Handles YAML and JSON processing in markdown
• Enables structured data in documentation
• Supports metadata processing

---

Rehype Plugins

Rehype plugins process HTML after markdown conversion. Like remark plugins, they are configured in the presets field of docusaurus.config.js:

// config/presets.js
module.exports = [
  [
    'classic',
    {
      docs: {
        rehypePlugins: [
          // rehype plugins would go here
        ],
      },
    },
  ],
];

Note: We currently do not use any rehype plugins in our documentation system. This section is provided for future reference if rehype plugins are added.

Adding Rehype Plugins

To add a new rehype plugin:

1. Install the plugin package:

npm install rehype-plugin-name

2. Add the plugin to the presets configuration:

// config/presets.js
module.exports = [
  [
    'classic',
    {
      docs: {
        rehypePlugins: [
          [require('rehype-plugin-name'), {
            // plugin options
          }],
        ],
      },
    },
  ],
];

---

Plugin Build Configuration

TypeScript Plugin Build Setup

When creating TypeScript-based plugins, they need to be built before Docusaurus can use them. This is configured in package.json:

1. Add a build script for your plugin:

{
  "scripts": {
    "build:new-plugin": "cd plugins/new-plugin && npm run build && cd ../../"
  }
}

2. Add the plugin to the build:plugins script chain:

{
  "scripts": {
    "build:plugins": "npm run build:remark-plugin-yaml-and-json && npm run build:docusaurus-plugin-showcase && npm run build:new-plugin"
  }
}

Current plugin build configuration example:

{
  "scripts": {
    "build:docusaurus-plugin-showcase": "cd plugins/docusaurus-plugin-showcase && npm run build && cd ../../",
    "build:remark-plugin-yaml-and-json": "cd plugins/remark-plugin-yaml-and-json && npm run build && cd ../../",
    "build:remark-plugin-a11y-checker": "cd plugins/remark-plugin-a11y-checker && npm run build && cd ../../",
    "build:remark-plugin-vfile-reporter": "cd plugins/remark-plugin-vfile-reporter && npm run build && cd ../../",
    "build:remark-plugin-image-to-figure": "cd plugins/remark-plugin-image-to-figure && npm run build && cd ../../",
    "build:remark-plugin-api-table": "cd plugins/remark-plugin-api-table && npm run build && cd ../../",
    "build:plugins": "npm run build:remark-plugin-yaml-and-json && npm run build:docusaurus-plugin-showcase && npm run build:remark-plugin-a11y-checker && npm run build:remark-plugin-vfile-reporter && npm run build:remark-plugin-image-to-figure && npm run build:remark-plugin-api-table"
  }
}

Plugin Dependencies

For plugins that use external dependencies:

1. Add the plugin as a local dependency in the root package.json:

{
  "dependencies": {
    "docusaurus-plugin-showcase": "./plugins/docusaurus-plugin-showcase",
    "docusaurus-plugin-markdown-printer": "./plugins/markdown-printer"
  }
}

2. Create a separate package.json in your plugin directory with its specific dependencies:

{
  "name": "your-plugin",
  "version": "1.0.0",
  "dependencies": {
    "specific-dependency": "^1.0.0"
  }
}

Build Process

The build process follows this order:

1. npm run build:plugins runs first to compile all TypeScript plugins
2. Docusaurus build process runs after plugins are built
3. Plugin dependencies are resolved through the root package.json

Example of the complete build chain:

{
  "scripts": {
    "build": "npm run build:plugins && npm run build:root",
    "start": "npm run build:plugins && docusaurus start"
  }
}

Best Practices for Plugin Builds

1. Keep plugin-specific dependencies in the plugin's own package.json
2. Add TypeScript plugins to the build:plugins script
3. Ensure plugin build scripts return to the root directory using cd ../../
4. Test plugin builds individually before adding to the main build chain
5. Use consistent naming conventions for build scripts

Plugin Processing Pipeline

The documentation processing pipeline follows this order:

1. Remark Processing (via presets)

   • Processes markdown through configured remark plugins
   • Transforms content according to plugin rules

2. Rehype Processing (via presets)

   • Processes HTML output from remark
   • Currently not in use, but available for future HTML transformations

3. Docusaurus Plugin Processing (via plugins)

   • Handles additional functionality and features
   • Manages site-wide plugin operations

Best Practices

1. Keep Docusaurus plugin configurations in /config/pluginsConfig/
2. Configure remark and rehype plugins in the /config/presets.js configuration
3. Document plugin options and dependencies
4. Test plugins in development before deploying
5. Maintain consistent file naming conventions

---

Troubleshooting

If a plugin isn't working:

1. For Docusaurus plugins:
   • Check the plugin configuration in /config/pluginsConfig/
   • Verify the plugin is properly imported in index.ts
2. For remark/rehype plugins:
   • Check the /config/presets.js configuration
   • Verify the plugin is properly included in the appropriate plugins array
3. Review the Docusaurus build logs for errors