Documentation site
The VitePress site combines the hand-written guides in docs/, component READMEs, component-level guides, and generated API references. It discovers plugins, tools and actions from package manifests and action metadata, then builds their navigation and reference links from those sources. Names and descriptions come from package manifests, plugin metadata, action metadata and guide introductions. On phones, the same sections open as compact accordions in the navigation screen.
Add a component guide
Create Markdown files under the component's docs/ folder. For example, a plugin can have an index.md plus additional pages such as configuration.md; tools and actions use the same layout. The site discovers each file and adds it to that component's sidebar and reference links. Relative links are checked by pnpm check.
For component-specific documentation settings, add a docs.yml file at the component root, next to its docs/ folder. Put navigation settings under navigation:
navigation:
category: Compatibility
type: card
icon: artwork/plugin-mark.svgcategory is optional; without it, the item appears in its menu's general group. type is optional and defaults to a regular link. Use card for a self-contained card or spotlight for a wide editorial row. The navigation namespace keeps menu settings separate from other documentation settings that may be added later. An icon path is relative to the component root, alongside docs.yml. Without an explicit icon, the site automatically uses icon.svg, icon.png, icon.webp, logo.svg, logo.png, or logo.webp from the component root when present, falling back to its docs/ folder. Discovered icons are included in the built site automatically and appear beside the title on the component's landing page as well as in navigation. Items without artwork keep the same alignment.
Add a category to a hand-written guide's frontmatter with navigation.category; navigation.type can also select card or spotlight. These categories are editorial labels and belong beside their docs, not in a second list in the site configuration.
To feature a component in the desktop Plugins menu, add navigation.featured: true to the frontmatter of its docs/index.md. It also remains a regular link in its category. A featured item defaults to the card treatment, and can use navigation.type: spotlight to show as a wide row instead. The title and description still come from the page heading and package manifest.
The component README is the overview when no custom docs/index.md exists. If a custom index exists, it becomes the component landing page and the README remains available as a separate README entry.
Each component README's reference block is refreshed by pnpm readme. Its API URL is derived from the discovered component path, and a link to a component guide appears when docs/index.md exists. The public documentation base comes from the repository URL in the root package.json. Keep the markers in place and edit the source metadata or docs files instead of maintaining those links by hand.
Reference
The Reference section brings together documented exports from plugin and tool source, action inputs and outputs from each action.yml, and exported repository script helpers. TypeDoc follows the source folders discovered from package manifests; action contracts come directly from the action metadata. Add JSDoc beside exported code and add action documentation to action.yml so the site stays in sync without a second list of names or settings.
TypeDoc reads whole source trees, including implementation modules, so excludeNotDocumented keeps symbols without JSDoc out of the reference. It is a presentation filter, not a completeness check; the JSDoc lint enforces descriptions on exported TypeScript APIs.
Generated Pumpkin and WASI bindings can appear by name in public signatures, but their generated declarations are not included as reference pages. The docs pipeline generates the needed bindings before TypeDoc runs. Generated pages are build output and ignored by Git; edit source comments, action metadata, or typedoc.json instead.
VitePress adds an Edit this page on GitHub link to Markdown pages. Generated API pages link that action to the corresponding source file where TypeDoc can identify one.
The site shows Last updated using Git history. The docs workflow fetches full history so pages that were not changed in the latest commit still show their latest edit time.
llms.txt
The site generates /llms.txt during the VitePress build from discovered guide pages, component documentation, package and action metadata, and API references. Guide and component links point to raw Markdown in the repository; generated API links point to the public docs site. The generated build-side copy is gitignored and stored under docs/. Update source docs or metadata to change its entries; update the generator in docs/.vitepress/config.mts to change its structure. The shared page head links to the file with rel="describedby", and the development server serves the same generated content at /llms.txt.
Theme
The site uses Pumpkin's #FF7518 accent. Light-mode text uses a darker orange for contrast; buttons, owner labels, and the home-page title use the primary color. Dark mode uses the primary orange for links, with a lighter hover shade.
Contributors and versions
The Team page lives at /team, with its own header link, and uses VitePress's native team components. Its data loader fetches all pages of the repository's GitHub contributor list during site builds and development, excluding accounts marked as bots and common automation accounts. When GITHUB_TOKEN is available, at most one GraphQL request per contributor page enriches the cards with public profile names. Without a token, or if that enrichment fails, cards use GitHub usernames. Avatars and profile links also come from GitHub; there is no contributor list to maintain. Each card shows GitHub's repository contribution count. filiphsps is explicitly marked as the owner and always sorted first; other contributors are sorted by contribution count. GitHub may take time to refresh contributor statistics. The contributor-list lookup requires network access and fails the build if GitHub is unavailable. Set GITHUB_TOKEN locally if unauthenticated requests are rate limited; the docs workflow supplies its read-only token. Only the contributor cards are included in the published site, not the loader or token.
Plugin and action landing pages, READMEs, and API overview pages show native VitePress version badges. Versions come from each plugin's package manifest or the action's version file. Badges link to the matching release when its tag exists in the checkout; unreleased versions remain linkless. Tag names come from the release configuration, and the workflow's full checkout includes the tags.
Local commands
Run pnpm run docs to generate bindings and the API reference, then build the complete static site. The two independent binding-generation steps run concurrently; TypeDoc and VitePress then run in order because the site reads the generated API pages. Use pnpm run dev:docs to generate the same inputs and start the VitePress development server, or pnpm run docs:preview to preview the last built site.
The pipeline can also be run in stages: pnpm run docs:types generates the binding declarations, pnpm run docs:api generates the TypeDoc reference after the bindings, and pnpm run docs:site builds the VitePress site from those generated pages. The binding steps can be run individually with pnpm run docs:types:plugin-kit or pnpm run docs:types:update-check. Plugin guest declarations can be generated with pnpm run docs:types:plugins. pnpm run docs:build is an alias for the complete production build.
The separate .github/workflows/docs.yml workflow checks docs on pull requests and publishes the site from pushes to master or main. It deploys a GitHub Pages artifact and mirrors the built files to the gh-pages branch. Configure the repository's Pages source to GitHub Actions.