@stritti/vitepress-plugin-openspec 0.4.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 +65 -34
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -2,27 +2,79 @@
|
|
|
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
|
|
8
13
|
|
|
9
14
|
```bash
|
|
15
|
+
npm install @stritti/vitepress-plugin-openspec
|
|
16
|
+
# or with bun:
|
|
10
17
|
bun add @stritti/vitepress-plugin-openspec
|
|
11
|
-
# or: npm install @stritti/vitepress-plugin-openspec
|
|
12
18
|
```
|
|
13
19
|
|
|
14
|
-
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
Add the following to your `.vitepress/config.ts`:
|
|
15
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
|
+
)
|
|
16
39
|
```
|
|
17
|
-
|
|
18
|
-
|
|
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
|
+
)
|
|
19
59
|
```
|
|
20
60
|
|
|
21
61
|
---
|
|
22
62
|
|
|
23
|
-
##
|
|
63
|
+
## Options
|
|
24
64
|
|
|
25
|
-
|
|
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:
|
|
26
78
|
|
|
27
79
|
```typescript
|
|
28
80
|
import { defineConfig } from 'vitepress'
|
|
@@ -35,26 +87,21 @@ import openspec, {
|
|
|
35
87
|
} from '@stritti/vitepress-plugin-openspec'
|
|
36
88
|
|
|
37
89
|
const __dirname = path.dirname(fileURLToPath(import.meta.url))
|
|
38
|
-
const specDir = path.resolve(__dirname, '../openspec')
|
|
90
|
+
const specDir = path.resolve(__dirname, '../openspec')
|
|
39
91
|
|
|
40
92
|
// Must be called before defineConfig so pages exist when VitePress scans for routes.
|
|
41
|
-
// This is required for first builds and CI environments.
|
|
42
93
|
generateOpenSpecPages({
|
|
43
94
|
specDir,
|
|
44
|
-
outDir: 'openspec',
|
|
45
|
-
srcDir: path.resolve(__dirname, '..'),
|
|
95
|
+
outDir: 'openspec',
|
|
96
|
+
srcDir: path.resolve(__dirname, '..'),
|
|
46
97
|
})
|
|
47
98
|
|
|
48
99
|
export default defineConfig({
|
|
49
100
|
vite: {
|
|
50
|
-
plugins: [
|
|
51
|
-
openspec({ specDir, outDir: 'openspec' }), // keeps pages in sync during dev
|
|
52
|
-
],
|
|
101
|
+
plugins: [openspec({ specDir, outDir: 'openspec' })],
|
|
53
102
|
},
|
|
54
103
|
themeConfig: {
|
|
55
|
-
nav: [
|
|
56
|
-
openspecNav(specDir, { outDir: 'openspec', text: 'Docs' }),
|
|
57
|
-
],
|
|
104
|
+
nav: [openspecNav(specDir, { outDir: 'openspec', text: 'Docs' })],
|
|
58
105
|
sidebar: {
|
|
59
106
|
'/openspec/': generateOpenSpecSidebar(specDir, { outDir: 'openspec' }),
|
|
60
107
|
},
|
|
@@ -64,18 +111,6 @@ export default defineConfig({
|
|
|
64
111
|
|
|
65
112
|
---
|
|
66
113
|
|
|
67
|
-
## Options
|
|
68
|
-
|
|
69
|
-
All three APIs (`generateOpenSpecPages`, `openspec`, `generateOpenSpecSidebar`, `openspecNav`) accept the same options object:
|
|
70
|
-
|
|
71
|
-
| Option | Type | Default | Description |
|
|
72
|
-
| --- | --- | --- | --- |
|
|
73
|
-
| `specDir` | `string` | `'./openspec'` | Path to your project's `openspec/` directory |
|
|
74
|
-
| `outDir` | `string` | `'openspec'` | Output directory relative to VitePress `srcDir` |
|
|
75
|
-
| `srcDir` | `string` | `process.cwd()` | VitePress source directory (the `docs/` folder). Required for `generateOpenSpecPages`. |
|
|
76
|
-
|
|
77
|
-
---
|
|
78
|
-
|
|
79
114
|
## Output Structure
|
|
80
115
|
|
|
81
116
|
The plugin reads your `openspec/` folder and generates:
|
|
@@ -94,7 +129,7 @@ openspec/ ← your source (not committed if used as output)
|
|
|
94
129
|
└── archive/
|
|
95
130
|
└── YYYY-MM-DD-<change-name>/
|
|
96
131
|
|
|
97
|
-
docs/openspec/ ← generated by the plugin (
|
|
132
|
+
docs/openspec/ ← generated by the plugin (automatically gitignored)
|
|
98
133
|
├── index.md
|
|
99
134
|
├── specs/
|
|
100
135
|
│ ├── index.md
|
|
@@ -111,11 +146,7 @@ docs/openspec/ ← generated by the plugin (add to .gitignore)
|
|
|
111
146
|
└── ...
|
|
112
147
|
```
|
|
113
148
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
```
|
|
117
|
-
docs/openspec/
|
|
118
|
-
```
|
|
149
|
+
The plugin automatically writes a `.gitignore` into the output directory that excludes all generated files from version control. No manual `.gitignore` entry is needed.
|
|
119
150
|
|
|
120
151
|
---
|
|
121
152
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@stritti/vitepress-plugin-openspec",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "A VitePress plugin that integrates OpenSpec documentation into your VitePress site",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"openspec",
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
"docs:build": "cd docs && bun run build"
|
|
42
42
|
},
|
|
43
43
|
"dependencies": {
|
|
44
|
-
"js-yaml": "^4.1.
|
|
44
|
+
"js-yaml": "^4.1.1",
|
|
45
45
|
"picocolors": "^1.1.1"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
@@ -52,10 +52,10 @@
|
|
|
52
52
|
"@types/js-yaml": "^4.0.9",
|
|
53
53
|
"@types/node": "^25.4.0",
|
|
54
54
|
"semantic-release": "^25.0.3",
|
|
55
|
-
"tsup": "^8.
|
|
56
|
-
"typescript": "^5.
|
|
55
|
+
"tsup": "^8.5.1",
|
|
56
|
+
"typescript": "^5.9.3",
|
|
57
57
|
"vite": "^7.3.1",
|
|
58
|
-
"vitepress": "^1.
|
|
58
|
+
"vitepress": "^1.6.4",
|
|
59
59
|
"vitest": "^4.0.18"
|
|
60
60
|
},
|
|
61
61
|
"peerDependencies": {
|