vitepress-plugin-openspec — Summary

@stritti/vitepress-plugin-openspec is a VitePress plugin that renders an OpenSpec directory as structured documentation pages — specs, changes, and artifacts — integrated into a VitePress site with auto-generated sidebar navigation and nav entries. It ships a withOpenSpec higher-order config wrapper that handles page generation, the Vite live-reload plugin, nav injection, and sidebar injection in a single call. The plugin reads the openspec/ directory, generates Markdown pages (one per spec, one per change, one per archive), and emits them to disk before VitePress scans for routes. It supports both simple withOpenSpec({}) wrapping and advanced manual setup with lower-level generateOpenSpecPages, generateOpenSpecSidebar, and openspecNav APIs. There are no prompts, skills, hooks, or agent orchestration — this is a documentation pipeline plugin.

differs_from_seeds: No seed framework integrates OpenSpec content into a VitePress documentation site. The closest seed is agent-os which manages markdown documents, but agent-os targets Claude Code context injection, not public documentation generation. This plugin is exclusively a build-time documentation tool with no LLM interaction surface.

vitepress-plugin-openspec — Overview

Origin

Published by Stephan Strittmatter (stritti) under MIT license. Version 0.3.1 as of analysis date. Uses semantic-release for automated publishing. Actively maintained (last commit 2026-05-12).

Philosophy

From the README: "A VitePress plugin that renders your project's OpenSpec folder as structured documentation pages — specs, changes, and artifacts — with sidebar and nav integration."

The design principle is zero-friction integration via the withOpenSpec wrapper: "withOpenSpec handles everything in one call: page generation, the Vite plugin for live reload, the nav entry, and the sidebar section. All fields are optional — it works with an empty config object and sensible defaults."

The plugin takes a "progressive enhancement" approach — if the openspec/ directory doesn't exist, it emits a warning and skips silently without breaking the VitePress build.

Manifesto-style statements

• "Missing directory — if specDir does not exist the plugin emits a console.warn and skips page generation, nav, and sidebar. No error is thrown and your VitePress build continues normally."
• "Other Vite plugins go into vite.plugins as usual — withOpenSpec appends to the array without replacing it."

Target user

Teams that use VitePress for project documentation and want to include their OpenSpec specs and changes as browsable documentation pages, automatically generated from the openspec/ directory.

vitepress-plugin-openspec — Architecture

Distribution

• npm package: @stritti/vitepress-plugin-openspec (v0.3.1)
• ESM + CJS dual output via tsup

Install methods

npm install @stritti/vitepress-plugin-openspec
# or
bun add @stritti/vitepress-plugin-openspec

Tech stack

• Language: TypeScript (compiled to ESM + CJS via tsup)
• Dependencies: js-yaml, picocolors
• Peer dependencies: vite>=5.0.0, vitepress>=1.0.0
• Build: tsup (dual output)
• Tests: vitest
• Release: semantic-release with GitHub + npm plugins

Directory structure

vitepress-plugin-openspec/
├── src/
│   ├── index.ts       # Public exports
│   ├── plugin.ts      # Vite plugin + withOpenSpec + generateOpenSpecPages
│   ├── utils.ts       # generateOpenSpecSidebar, openspecNav, page generators
│   ├── types.ts       # TypeScript types
│   └── __tests__/
├── dist/              # Compiled output
├── docs/              # VitePress docs site (uses itself)
├── openspec/          # OpenSpec directory (dogfood)
└── tsup.config.ts

API surface

// Simple (recommended)
import { withOpenSpec } from '@stritti/vitepress-plugin-openspec'
export default defineConfig(withOpenSpec({ /* vitepress config */ }))

// Advanced (manual control)
import openspec, {
  generateOpenSpecPages,
  generateOpenSpecSidebar,
  openspecNav,
} from '@stritti/vitepress-plugin-openspec'

Options

Required runtime

• node>=18.0.0
• bun>=1.1.0 (optional, for dev)
• vite>=5.0.0, vitepress>=1.0.0 (peer)

vitepress-plugin-openspec — Components

Exported functions

withOpenSpec(config, options?) — primary API

• Wraps a VitePress defineConfig call
• Calls generateOpenSpecPages before VitePress route scanning
• Appends openspec() Vite plugin to vite.plugins
• Injects nav entry into themeConfig.nav
• Injects sidebar section into themeConfig.sidebar

openspec(options?) — Vite plugin

• Provides live-reload watching of the openspec/ directory
• Triggers page regeneration when spec files change

generateOpenSpecPages(options?) — page generation

• Reads openspec/ directory
• Generates per-spec Markdown pages at outDir/specs/<name>/index.md
• Generates specs index at outDir/specs/index.md
• Generates per-change Markdown pages (active + archived)
• Generates changes index at outDir/changes/index.md
• Generates root index at outDir/index.md

generateOpenSpecSidebar(specDir, options?) — sidebar generation

• Returns VitePress sidebar configuration object for the OpenSpec section

openspecNav(specDir, options?) — nav entry

• Returns a single VitePress nav item pointing to the OpenSpec section

Key types

• OpenSpecFolder — parsed representation of an openspec/ directory
• Change, ChangeArtifact, CapabilitySpec — domain types
• OpenSpecPluginOptions — {specDir, outDir, srcDir, nav, sidebar}
• WithOpenSpecOptions — extends OpenSpecPluginOptions with VitePress config fields

No AI-facing primitives

Zero commands, skills, hooks, subagents, or MCP servers.

vitepress-plugin-openspec — Uniqueness & Positioning

differs_from_seeds

No seed framework produces public documentation from OpenSpec content. This plugin targets the documentation publishing use case — turning openspec/ into a VitePress docs site — which none of the 11 seeds address. The closest seed in methodology is agent-os (manages structured markdown files), but agent-os targets Claude Code context injection (agent instructions), not published documentation. vitepress-plugin-openspec is entirely a build-time documentation tool with zero LLM interaction.

Positioning

• Category: OpenSpec ecosystem — documentation publishing
• User: Teams that maintain VitePress documentation sites and want to include their spec-driven development content as browsable, navigable pages
• Integration: Drop-in VitePress plugin added to .vitepress/config.ts
• Value: Zero-configuration OpenSpec → VitePress documentation pipeline with live reload

Observable failure modes

1. Page generation must precede defineConfig: If generateOpenSpecPages is called inside defineConfig, VitePress may have already scanned routes, missing the generated pages
2. specDir resolution: Relative paths resolved from process.cwd(), which may not match expectations when config.ts is in a subdirectory — README recommends path.resolve(__dirname, '../../openspec')
3. Generated files may conflict: If the outDir overlaps with manually authored docs content, generated files will overwrite
4. VitePress version sensitivity: Depends on vitepress>=1.0.0 API stability

Cross-references

• Depends on: OpenSpec file structure
• Complementary to: spek (which provides an interactive viewer), openspec-badge-action (which generates CI badges)
• Same ecosystem niche as the GitHub Action variant of spek — both convert OpenSpec to static docs, but this plugin integrates with an existing VitePress site while spek's Action generates a standalone static site