Docs and Website
This skill covers updating documentation and the Docusaurus website for Invowk.
Use this skill when working on:
website/ - Docusaurus documentation sitewebsite/docs/ - Documentation pageswebsite/i18n/ - Internationalization- Schema changes that require documentation updates
Required Workflow
- Read
website/WEBSITE_DOCS.md before any website edits.
- Use MDX +
<Snippet> for all code/CLI/CUE blocks.
- Define snippets in
website/src/components/Snippet/snippets.ts and reuse IDs across locales.
- Escape
${...} inside snippets as \${...}.
Documentation Sync Map
| Change |
Update |
pkg/invkfile/invkfile_schema.cue |
website/docs/reference/invkfile-schema.mdx + affected docs/snippets |
pkg/invkmod/invkmod_schema.cue |
website/docs/modules/ pages |
pkg/invkmod/operations*.go |
website/docs/modules/ pages (validation, create, packaging, vendoring) |
internal/config/config_schema.cue |
website/docs/reference/config-schema.mdx, website/docs/configuration/options.mdx |
internal/runtime/container*.go |
website/docs/runtime-modes/container.mdx |
cmd/invowk/*.go |
website/docs/reference/cli.mdx + relevant feature docs |
cmd/invowk/module*.go |
website/docs/modules/ pages + website/docs/reference/cli.mdx |
cmd/invowk/cmd_validate*.go |
website/docs/dependencies/ pages |
cmd/invowk/tui_*.go |
website/docs/tui/ pages + snippets |
| New features |
Add/update docs under website/docs/ and snippets as needed |
Documentation Structure
website/docs/
|-- getting-started/ # Installation, quickstart, first invkfile
|-- core-concepts/ # Invkfile format, commands, implementations
|-- runtime-modes/ # Native, virtual, container execution
|-- dependencies/ # Tools, filepaths, capabilities, custom checks
|-- flags-and-arguments/ # CLI flags and positional arguments
|-- environment/ # Env files, env vars, precedence
|-- advanced/ # Interpreters, workdir, platform-specific
|-- modules/ # Module creation, validation, distribution
|-- tui/ # TUI components reference
|-- configuration/ # Config file and options
`-- reference/ # CLI, invkfile schema, config schema
Documentation Style Guide
- Use a friendly, approachable tone with occasional humor.
- Follow progressive disclosure: start simple, add complexity gradually.
- Include practical examples for each feature.
- Use admonitions for important callouts.
- Keep code examples concise and focused.
Docs + i18n Checklist
- Always use
.mdx (not .md) in website/docs/ and translations.
- Treat
website/docs/ as the upcoming version; only touch versioned docs for backport fixes (see website/WEBSITE_DOCS.md).
- Update English first, then mirror the same
.mdx path in website/i18n/pt-BR/docusaurus-plugin-content-docs/current/.
- Keep translations prose-only and reuse identical snippet IDs.
- Regenerate translation JSON when UI strings change:
cd website && npx docusaurus write-translations --locale pt-BR.
Documentation Testing
# Single locale development
cd website && npm start
# Brazilian Portuguese locale
cd website && npm start -- --locale pt-BR
# Full build (tests all locales)
cd website && npm run build
# Serve built site (for locale switching)
cd website && npm run serve
Common Pitfalls
- Missing i18n - Website changes require updates to both
docs/ and i18n/pt-BR/.
- Outdated documentation - Check the Documentation Sync Map when modifying schemas or CLI.
1---2name: docs-73description: Documentation workflow for website/ directory, Docusaurus, MDX snippets, i18n localization. Use when editing docs/, creating documentation pages, or updating WEBSITE_DOCS.md.4---5
6# Docs and Website
7
8This skill covers updating documentation and the Docusaurus website for Invowk.
9
10Use this skill when working on:
11- `website/` - Docusaurus documentation site
12- `website/docs/` - Documentation pages
13- `website/i18n/` - Internationalization
14- Schema changes that require documentation updates
15
16---
17
18## Required Workflow
19
20- Read `website/WEBSITE_DOCS.md` before any website edits.
21- Use MDX + `<Snippet>` for all code/CLI/CUE blocks.
22- Define snippets in `website/src/components/Snippet/snippets.ts` and reuse IDs across locales.
23- Escape `${...}` inside snippets as `\${...}`.
24
25---
26
27## Documentation Sync Map
28
29| Change | Update |
30| --- | --- |
31| `pkg/invkfile/invkfile_schema.cue` | `website/docs/reference/invkfile-schema.mdx` + affected docs/snippets |
32| `pkg/invkmod/invkmod_schema.cue` | `website/docs/modules/` pages |
33| `pkg/invkmod/operations*.go` | `website/docs/modules/` pages (validation, create, packaging, vendoring) |
34| `internal/config/config_schema.cue` | `website/docs/reference/config-schema.mdx`, `website/docs/configuration/options.mdx` |
35| `internal/runtime/container*.go` | `website/docs/runtime-modes/container.mdx` |
36| `cmd/invowk/*.go` | `website/docs/reference/cli.mdx` + relevant feature docs |
37| `cmd/invowk/module*.go` | `website/docs/modules/` pages + `website/docs/reference/cli.mdx` |
38| `cmd/invowk/cmd_validate*.go` | `website/docs/dependencies/` pages |
39| `cmd/invowk/tui_*.go` | `website/docs/tui/` pages + snippets |
40| New features | Add/update docs under `website/docs/` and snippets as needed |
41
42---
43
44## Documentation Structure
45
46```
47website/docs/
48|-- getting-started/ # Installation, quickstart, first invkfile
49|-- core-concepts/ # Invkfile format, commands, implementations
50|-- runtime-modes/ # Native, virtual, container execution
51|-- dependencies/ # Tools, filepaths, capabilities, custom checks
52|-- flags-and-arguments/ # CLI flags and positional arguments
53|-- environment/ # Env files, env vars, precedence
54|-- advanced/ # Interpreters, workdir, platform-specific
55|-- modules/ # Module creation, validation, distribution
56|-- tui/ # TUI components reference
57|-- configuration/ # Config file and options
58`-- reference/ # CLI, invkfile schema, config schema
59```
60
61---
62
63## Documentation Style Guide
64
65- Use a friendly, approachable tone with occasional humor.
66- Follow progressive disclosure: start simple, add complexity gradually.
67- Include practical examples for each feature.
68- Use admonitions for important callouts.
69- Keep code examples concise and focused.
70
71---
72
73## Docs + i18n Checklist
74
75- Always use `.mdx` (not `.md`) in `website/docs/` and translations.
76- Treat `website/docs/` as the upcoming version; only touch versioned docs for backport fixes (see `website/WEBSITE_DOCS.md`).
77- Update English first, then mirror the same `.mdx` path in `website/i18n/pt-BR/docusaurus-plugin-content-docs/current/`.
78- Keep translations prose-only and reuse identical snippet IDs.
79- Regenerate translation JSON when UI strings change: `cd website && npx docusaurus write-translations --locale pt-BR`.
80
81---
82
83## Documentation Testing
84
85```bash
86# Single locale development
87cd website && npm start
88
89# Brazilian Portuguese locale
90cd website && npm start -- --locale pt-BR
91
92# Full build (tests all locales)
93cd website && npm run build
94
95# Serve built site (for locale switching)
96cd website && npm run serve
97```
98
99---
100
101## Common Pitfalls
102
103- **Missing i18n** - Website changes require updates to both `docs/` and `i18n/pt-BR/`.
104- **Outdated documentation** - Check the Documentation Sync Map when modifying schemas or CLI.
majiayu000