Skip to main content

Plugin Policy

This document defines the approved plugin policy for the Engineering Journal Docusaurus site and the process for adding new plugins or extensions.

Current Approved Plugins​

PluginSourcePurpose
@docusaurus/plugin-content-docspreset-classicDocs content rendering
@docusaurus/plugin-content-pagespreset-classicStatic pages
@docusaurus/plugin-sitemappreset-classicSitemap generation
@docusaurus/theme-classicpreset-classicDefault theme
@docusaurus/theme-mermaidexplicitMermaid diagram rendering
@easyops-cn/docusaurus-search-localexplicitOffline/local full-text search (no external services)
@docusaurus/plugin-pwaexplicitProgressive Web App with offline support
docusaurus-plugin-glossaryexplicitAuto-generated glossary page with inline term tooltips
Giscus (via swizzle)explicitGitHub Discussions-backed comments on all doc pages

Plugin Allowlist Policy​

Principles​

  1. Minimal surface — only install plugins that solve a problem that cannot be solved with Docusaurus built-ins or existing tooling.
  2. Active maintenance — plugins must be actively maintained. Abandoned plugins are not approved.
  3. No vendor lock-in — prefer plugins from the Docusaurus core team over third-party alternatives.
  4. Build-time only — plugins that run at build time are preferred over runtime plugins that add JavaScript to the deployed site.

Approval Process​

To add a new plugin:

  1. Open an issue with label type:feature and area:theme or area:repo-docs
  2. Document the problem the plugin solves and why built-ins are insufficient
  3. Link to the plugin's repository and verify it is actively maintained
  4. Get approval before adding to website/package.json
  5. Update this document with the new entry

Prohibited​

  • Plugins that add analytics or tracking without explicit consent
  • Plugins that inject third-party scripts into the deployed site
  • Plugins with known security vulnerabilities
  • Plugins not compatible with the current Docusaurus major version

Extension Guidelines​

Adding Mermaid Diagrams​

Mermaid is already enabled. Use fenced code blocks with the mermaid language identifier.

Custom CSS​

All custom CSS lives in website/src/css/custom.css. Use CSS variables defined in :root and [data-theme="dark"] rather than hardcoded values. Do not add separate CSS files or import external stylesheets.

Custom React Components​

Custom components live in website/src/components/. Keep them small and focused. Do not introduce new npm dependencies for components — use what is already available in the Docusaurus ecosystem.

MDX​

MDX is supported. Use sparingly — prefer plain Markdown for content that does not require interactivity. MDX components that require heavy JavaScript should be evaluated against the build-time only principle above.

Reviewing This Document​

This document should be reviewed when:

  • A new plugin is proposed
  • A Docusaurus major version upgrade is planned
  • An existing plugin is deprecated upstream

Related Content​