docusaurus-plugin-archify

Build-time integration for Archify diagrams in Docusaurus v3.

Install

pnpm add docusaurus-plugin-archify

The Archify CLI is intentionally not an npm dependency. Install or clone Archify separately and point the plugin at its bin/archify.mjs file.

Configure

// docusaurus.config.ts
export default {
  plugins: [
    [
      'docusaurus-plugin-archify',
      {
        diagramsDir: 'diagrams',
        archify: {
          cliPath: '.agents/skills/archify/bin/archify.mjs',
        },
        routeBasePath: 'archify',
        failOnError: true,
      },
    ],
  ],
};

Every *.json file below diagramsDir is discovered recursively. Its diagram_type must be one of architecture, workflow, sequence, dataflow, or lifecycle. The ID comes from meta.id when present, otherwise from the relative filename without .json; meta.title is optional and falls back to the ID.

Use from MDX

import { ArchifyDiagram } from 'docusaurus-plugin-archify/react';

<ArchifyDiagram name="system" />
<ArchifyDiagram name="authentication" height={600} title="Authentication flow" />

For a non-default route, pass the same route base path:

<ArchifyDiagram name="system" routeBasePath="diagrams" />

The component uses Docusaurus's configured baseUrl, renders the generated self-contained HTML in an isolated iframe, follows the site's light/dark color mode through the theme URL parameter, and supports name, height, title, loading, className, and routeBasePath. When title is omitted, the title from meta.title is used. A name that is not in the generated manifest fails the build in the default strict mode; with failOnError: false, it renders an accessible warning instead.

Development and build behavior

During loadContent, the plugin validates the configured CLI path, discovers diagrams, and runs archify deliver <type> <input> <output> --json; deliver performs validation and rendering in one CLI call. Artifacts and the v1 manifest are written below Docusaurus's generated files directory. getPathsToWatch() watches diagramsDir, and the generated directory is mounted at the configured route in development, so edits trigger regeneration and refresh the iframe through a content revision query. Deleted diagrams are removed from generated artifacts. After a production build, HTML files are copied to <outDir>/<routeBasePath>/<id>.html.

Set failOnError: false to turn per-diagram discovery/render failures into warnings. Valid diagrams remain in the manifest and continue to render; failed diagrams are omitted and any stale HTML for them is removed. A missing CLI or unreadable diagrams directory is still treated as a global failure and produces an empty manifest. The default is true, which reports the diagram ID and Archify command stage in the build error.

The plugin validates diagramsDir, archify.cliPath, routeBasePath, and failOnError during Docusaurus plugin initialization. routeBasePath must contain safe URL path segments and cannot escape the build output directory.

Checks

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build

The repository includes a fixture in fixtures/docusaurus. It demonstrates the plugin configuration and MDX usage, including a diagram generated from this plugin's own architecture, without writing artifacts into source static/.

Constraints and future scope

Archify remains an external CLI boundary because its package is private. This MVP does not include AI generation, Mermaid conversion, WYSIWYG editing, viewer reimplementation, databases, external APIs, or Git diff views. The renderer contract is intentionally small so a package renderer or a content-hash cache can be added later; the manifest also leaves room for compare/Before-Delta-After views and AI knowledge-source integration.