From sdd
Generates Docusaurus documentation site from ADRs and OpenSpec specs with cross-links, RFC 2119 highlighting, badges, requirement boxes, and auto-sidebars. Use for 'generate docs' or publishing decisions.
npx claudepluginhub joestump/claude-plugin-sdd --plugin sddThis skill uses the workspace's default tool permissions.
Transform ADRs and OpenSpec specs (located via the **Artifact Path Resolution** pattern from `references/shared-patterns.md`) into a polished documentation website with:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
Transform ADRs and OpenSpec specs (located via the Artifact Path Resolution pattern from references/shared-patterns.md) into a polished documentation website with:
Supports two modes:
docs-site/ with its own Docusaurus installationFollow the Artifact Path Resolution pattern from references/shared-patterns.md to determine the ADR and spec directories. If $ARGUMENTS contains --module <name>, resolve paths relative to that module; otherwise, in a workspace, aggregate across all modules. The resolved ADR directory is {adr-dir} and spec directory is {spec-dir}.
Cross-module aggregation: When in aggregate mode (no --module, workspace detected), include all modules' artifacts in the docs site. Organize the sidebar navigation by module:
Architecture/
├── api/
│ ├── ADRs/
│ │ ├── ADR-0001: Choose REST over GraphQL
│ │ └── ADR-0002: Choose PostgreSQL
│ └── Specs/
│ └── SPEC-0001: Web Dashboard
├── worker/
│ ├── ADRs/
│ │ └── ADR-0001: Choose Redis for queues
│ └── Specs/
│ └── SPEC-0001: Job Processing
└── Overview (cross-module index page)
Each module's artifacts are transformed independently and placed under a module-named directory in the docs output. The index page lists all modules with artifact counts. When --module is provided, generate docs for that single module only (flat structure, no module subdirectory). When in single-module mode (no workspace), operate normally with the existing flat structure.
{adr-dir} has any ADR .md files{spec-dir} has any spec directories (containing spec.md). Validate spec pairing per references/shared-patterns.md § "Spec Pairing Validation"./sdd:adr or /sdd:spec, then re-run /sdd:docs." and stop.Check if .sdd-docs.json exists at the project root.
If .sdd-docs.json exists:
siteDir referenced in the manifest still exists on disk
.sdd-docs.json but the site directory {siteDir} no longer exists." Use AskUserQuestion to offer:
If .sdd-docs.json does NOT exist, continue to Step 2.2.
Scan the project root for directories containing docusaurus.config.ts or docusaurus.config.js:
find . -maxdepth 2 -name 'docusaurus.config.*' -not -path './docs-site/*' -not -path './node_modules/*' 2>/dev/null
If an existing docs site directory is detected (docs-site/ exists or an integration site was found in 2.2) but no .sdd-docs.json:
.sdd-docs.json not found."AskUserQuestion to offer:
.sdd-docs.json using the current state as baseline, then enter Upgrade Mode (Step 3C)If an existing non-scaffold Docusaurus site is found (from Step 2.2), use AskUserQuestion to let the user choose:
If no existing site is found, proceed directly with Scaffold Mode (Step 3A).
Read and follow the plugin's skills/docs/references/scaffold-mode.md for the full scaffold workflow. After completion, proceed to Step 4 below.
Read and follow the plugin's skills/docs/references/integration-mode.md for the full integration workflow. After completion, proceed to Step 4 below.
Read and follow the plugin's skills/docs/references/upgrade-mode.md for the full upgrade workflow. This handles manifest-based file management, conflict resolution, and new template detection.
Runs after Step 3A or 3B to establish upgrade tracking.
Determine managed files based on mode:
docs-site/scripts/, docs-site/src/components/, docs-site/src/css/, docs-site/src/theme/{site}/plugins/sync-spec-docs/, {site}/src/components/design-docs/, {site}/src/css/design-docs.css, {site}/src/theme/MDXComponents.tsx (if created/modified)Compute SHA-256 checksum for each file (shasum -a 256 {file-path}), then write .sdd-docs.json:
{
"version": "<plugin version from .claude-plugin/plugin.json>",
"mode": "scaffold" | "integration",
"siteDir": "<relative path to site dir>",
"createdAt": "<ISO 8601>",
"updatedAt": "<ISO 8601>",
"files": {
"<relative-path>": { "checksum": "sha256:<hex-digest>", "managed": true }
}
}
Tell the user: "Created .sdd-docs.json with {N} tracked files. Future runs of /sdd:docs will detect changes and offer upgrades."
templates/docusaurus/)The templates directory contains production-ready versions of all files. The cp -r approach copies everything; you only need to customize docusaurus.config.ts and package.json.
build-docs.js -- Orchestrator that runs all transformstransform-adrs.js -- Transforms ADR markdown to .mdx with badges, RFC 2119 keyword highlighting, cross-referencestransform-openspecs.js -- Transforms OpenSpec markdown to .mdx with requirement boxes, domain badges, RFC 2119 highlighting. Generates separate pages for spec.md and design.md within a directory-per-spec structure, with a _category_.json file per spec directory for Docusaurus sidebar configuration (Governing: ADR-0006, SPEC-0004)mdx-escape.js -- Escapes MDX v3 unsafe patterns (curly braces, angle brackets) while preserving JSX componentsbuild-spec-mapping.js -- Scans specs for SPEC ID prefixes and generates mapping JSONgenerate-index.js -- Creates the landing page (index.mdx) with links to ADRs and specs sections with countstemplates/integration/sync-spec-docs/)A self-contained Docusaurus plugin with adapted transform scripts.
index.js -- Docusaurus plugin that runs transforms during loadContent() and watches source files via getPathsToWatch()transform-adrs.js -- ADR transforms with parameterized pathstransform-openspecs.js -- OpenSpec transforms with parameterized pathstransform-utils.js -- Shared utilities (RFC 2119 keywords, cross-references, link fixing)mdx-escape.js -- MDX v3 safety escapingbuild-spec-mapping.js -- Spec ID mapping (returns data instead of writing files)generate-index.js -- Index page generation with parameterized pathsUsed by both modes. In scaffold mode, they live at docs-site/src/components/. In integration mode, they're copied to {site}/src/components/design-docs/.
StatusBadge.tsx -- Status with emoji (accepted, proposed, draft, etc.)DateBadge.tsx -- Date display with calendar emojiDomainBadge.tsx -- Domain/category badgePriorityBadge.tsx -- P0-P4 priority levelsSeverityBadge.tsx -- Critical/High/Medium/Low/InfoRFCLevelBadge.tsx -- Maps RFC 2119 keywords to severity colorsRequirementBox.tsx -- Bordered container for spec requirements with ID anchorsField.tsx / FieldGroup.tsx -- Metadata label-value pairssrc/theme/MDXComponents.tsx -- Registers all custom components for use in MDXsrc/css/custom.css -- All badge, keyword, component, and dark mode stylesspec-emojis.json and spec-mapping.json as generated files (populated by build-spec-mapping.js)docusaurus.config.ts wholesale -- only add the plugin entry and CSS importdesign-docs/ to avoid collisions with existing components{site}/docs/architecture/ -- this directory is gitignored and regenerated on every build.sdd-docs.json after a fresh scaffold or integration install (Step 4)files object uses project-root-relative paths as keyssha256:<hex-digest> (lowercase hex)managed: true and use their current checksums as the baseline--module is provided, generate docs for that single module only using flat structure