Writing documentation

The OpenKAI Guide is generated from the Markdown files in docs/ with VitePress. It uses the standard VitePress documentation theme, as used by the PX4 documentation, with OpenKAI's blue accent and logo.

The build pins stable VitePress 1.6.4 and overrides its Vite dependency to patched 6.4.5. Keep this override until VitePress's own dependency range includes a patched version; verify the production build and local preview when updating it.

Preview locally

Install Node.js 24 or newer, then run from the repository root:

cd docs
npm ci
npm run dev

Open the local address printed in the terminal. Edits to Markdown pages update the preview automatically. After adding or moving a page, restart the development server so that the sidebar discovers its new path.

Before submitting changes, build the complete site:

npm run build
npm run preview

The build checks internal page links. Fix a broken link rather than disabling link validation. The output is generated in docs/.vitepress/dist/ and is excluded from Git.

Add or edit a guide

1. Add a .md file anywhere under docs/, outside public/, .vitepress/, and node_modules/.
2. Start with one # Page title, followed by ## and ### sections. These headings appear in the page outline.
3. Link to another guide using a relative Markdown path, such as [Setup](../1-setup.md). Add a heading fragment when helpful.
4. Put images and other website assets in docs/public/. Link to them from the site root, such as /images/example.png.
5. Run npm run build and open the preview to check the result.

Keep existing filenames when possible so that published links remain valid. For links to repository source files outside docs/, use a full GitHub URL, for example https://github.com/yankailab/OpenKAI/blob/master/src/main.cpp.

The sidebar is generated by .vitepress/sidebar.ts. Existing guides have a curated order and short labels. New Markdown files appear automatically in their folder's section; new top-level files appear under Other guides. Update the section definitions or title map when a new guide needs a particular order or label.

Fenced code blocks should name their language, such as cpp, bash, or json. Put C++ templates, placeholders such as <device>, and other literal angle-bracket text in code spans or code blocks so that Vue does not treat them as HTML.

Files and responsibilities

Path	Purpose
docs/**/*.md	Documentation source pages
docs/index.md	Home page
docs/.vitepress/config.ts	Site title, navigation, search, and metadata
docs/.vitepress/sidebar.ts	Automatic sidebar and curated page labels
docs/.vitepress/theme/	Standard VitePress theme with OpenKAI colors
docs/public/	Site assets copied directly into the build
docs/package.json and docs/package-lock.json	Pinned build dependencies
.github/workflows/docs.yml	Pull-request checks and GitHub Pages deployment

Existing shell scripts, archives, and other non-Markdown notes elsewhere under docs/ are kept as repository files. They do not become documentation pages. Convert them to Markdown when they are ready for the guide.

Publish changes

Open a pull request against master. The documentation workflow builds the site to validate the change. After a change is merged into master, the workflow builds and deploys the site through GitHub Pages. Maintainers can also run Deploy documentation → Run workflow for master in GitHub Actions.

See Hosting and domain setup for the repository Pages settings and DNS configuration.