@stritti/vitepress-plugin-openspec 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -22
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
A [VitePress](https://vitepress.dev/) plugin that renders your project's [OpenSpec](https://openspec.dev/) folder as structured documentation pages — specs, changes, and artifacts — with sidebar and nav integration.
|
|
4
4
|
|
|
5
|
+
[](https://www.npmjs.com/package/@stritti/vitepress-plugin-openspec)
|
|
6
|
+
[](https://www.npmjs.com/package/@stritti/vitepress-plugin-openspec)
|
|
7
|
+
[](https://github.com/stritti/vitepress-plugin-openspec/blob/main/LICENSE)
|
|
8
|
+
[](https://github.com/stritti/vitepress-plugin-openspec/actions/workflows/publish.yml)
|
|
9
|
+
|
|
5
10
|
---
|
|
6
11
|
|
|
7
12
|
## Installation
|
|
@@ -18,6 +23,59 @@ bun add @stritti/vitepress-plugin-openspec
|
|
|
18
23
|
|
|
19
24
|
Add the following to your `.vitepress/config.ts`:
|
|
20
25
|
|
|
26
|
+
```typescript
|
|
27
|
+
import { defineConfig } from 'vitepress'
|
|
28
|
+
import { withOpenSpec } from '@stritti/vitepress-plugin-openspec'
|
|
29
|
+
|
|
30
|
+
export default defineConfig(
|
|
31
|
+
withOpenSpec({
|
|
32
|
+
// your regular VitePress config
|
|
33
|
+
themeConfig: {
|
|
34
|
+
nav: [{ text: 'Home', link: '/' }],
|
|
35
|
+
sidebar: {},
|
|
36
|
+
},
|
|
37
|
+
})
|
|
38
|
+
)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`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.
|
|
42
|
+
|
|
43
|
+
**Other Vite plugins** go into `vite.plugins` as usual — `withOpenSpec` appends to the array without replacing it:
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { defineConfig } from 'vitepress'
|
|
47
|
+
import { withOpenSpec } from '@stritti/vitepress-plugin-openspec'
|
|
48
|
+
import myOtherPlugin from 'vitepress-plugin-something'
|
|
49
|
+
|
|
50
|
+
export default defineConfig(
|
|
51
|
+
withOpenSpec(
|
|
52
|
+
{
|
|
53
|
+
vite: { plugins: [myOtherPlugin()] }, // preserved alongside openspec
|
|
54
|
+
themeConfig: { nav: [], sidebar: {} },
|
|
55
|
+
},
|
|
56
|
+
{ specDir: '../openspec', outDir: 'openspec' } // options (all optional)
|
|
57
|
+
)
|
|
58
|
+
)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Options
|
|
64
|
+
|
|
65
|
+
| Option | Type | Default | Description |
|
|
66
|
+
| --- | --- | --- | --- |
|
|
67
|
+
| `specDir` | `string` | `'./openspec'` | Path to your project's `openspec/` directory |
|
|
68
|
+
| `outDir` | `string` | `'openspec'` | Output directory relative to VitePress `srcDir` |
|
|
69
|
+
| `srcDir` | `string` | `process.cwd()` | VitePress source directory (the `docs/` folder) |
|
|
70
|
+
| `nav` | `boolean` | `true` | Whether to prepend an openspec entry to `themeConfig.nav` |
|
|
71
|
+
| `sidebar` | `boolean` | `true` | Whether to inject the openspec sidebar section into `themeConfig.sidebar` |
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Advanced / manual setup
|
|
76
|
+
|
|
77
|
+
If you need full control over each integration point, you can wire up the lower-level APIs individually:
|
|
78
|
+
|
|
21
79
|
```typescript
|
|
22
80
|
import { defineConfig } from 'vitepress'
|
|
23
81
|
import path from 'node:path'
|
|
@@ -29,26 +87,21 @@ import openspec, {
|
|
|
29
87
|
} from '@stritti/vitepress-plugin-openspec'
|
|
30
88
|
|
|
31
89
|
const __dirname = path.dirname(fileURLToPath(import.meta.url))
|
|
32
|
-
const specDir = path.resolve(__dirname, '../openspec')
|
|
90
|
+
const specDir = path.resolve(__dirname, '../openspec')
|
|
33
91
|
|
|
34
92
|
// Must be called before defineConfig so pages exist when VitePress scans for routes.
|
|
35
|
-
// This is required for first builds and CI environments.
|
|
36
93
|
generateOpenSpecPages({
|
|
37
94
|
specDir,
|
|
38
|
-
outDir: 'openspec',
|
|
39
|
-
srcDir: path.resolve(__dirname, '..'),
|
|
95
|
+
outDir: 'openspec',
|
|
96
|
+
srcDir: path.resolve(__dirname, '..'),
|
|
40
97
|
})
|
|
41
98
|
|
|
42
99
|
export default defineConfig({
|
|
43
100
|
vite: {
|
|
44
|
-
plugins: [
|
|
45
|
-
openspec({ specDir, outDir: 'openspec' }), // keeps pages in sync during dev
|
|
46
|
-
],
|
|
101
|
+
plugins: [openspec({ specDir, outDir: 'openspec' })],
|
|
47
102
|
},
|
|
48
103
|
themeConfig: {
|
|
49
|
-
nav: [
|
|
50
|
-
openspecNav(specDir, { outDir: 'openspec', text: 'Docs' }),
|
|
51
|
-
],
|
|
104
|
+
nav: [openspecNav(specDir, { outDir: 'openspec', text: 'Docs' })],
|
|
52
105
|
sidebar: {
|
|
53
106
|
'/openspec/': generateOpenSpecSidebar(specDir, { outDir: 'openspec' }),
|
|
54
107
|
},
|
|
@@ -58,18 +111,6 @@ export default defineConfig({
|
|
|
58
111
|
|
|
59
112
|
---
|
|
60
113
|
|
|
61
|
-
## Options
|
|
62
|
-
|
|
63
|
-
All three APIs (`generateOpenSpecPages`, `openspec`, `generateOpenSpecSidebar`, `openspecNav`) accept the same options object:
|
|
64
|
-
|
|
65
|
-
| Option | Type | Default | Description |
|
|
66
|
-
| --- | --- | --- | --- |
|
|
67
|
-
| `specDir` | `string` | `'./openspec'` | Path to your project's `openspec/` directory |
|
|
68
|
-
| `outDir` | `string` | `'openspec'` | Output directory relative to VitePress `srcDir` |
|
|
69
|
-
| `srcDir` | `string` | `process.cwd()` | VitePress source directory (the `docs/` folder). Required for `generateOpenSpecPages`. |
|
|
70
|
-
|
|
71
|
-
---
|
|
72
|
-
|
|
73
114
|
## Output Structure
|
|
74
115
|
|
|
75
116
|
The plugin reads your `openspec/` folder and generates:
|