Maintaining the docs
The documentation website uses VitePress. Its Markdown sources live in doc/; the website's Node.js tooling is separate from the browser runtime in runtime/ and from the tools needed to build a CryKit application.
Run locally
From the repository root, install the documentation dependencies and start the development server:
npm install
npm run devFollow the local address printed by VitePress. Markdown changes refresh the site while the server is running.
To check the production output:
npm run build
npm run previewThe build writes a static website to doc/.vitepress/dist/. Preview serves that output locally. Generated output and caches are excluded from version control.
Publish to GitHub Pages
The site is configured for https://aristorap.github.io/crykit/, with /crykit/ as its base path. Local development and preview use the same base path.
After creating the GitHub repository, open Settings → Pages and select GitHub Actions under Build and deployment → Source. The .github/workflows/docs.yml workflow builds and deploys the site when documentation or its tooling changes on main. You can also run it manually from the Actions tab. The workflow publishes doc/.vitepress/dist/; no gh-pages branch is needed.
Source layout
| Location | Content |
|---|---|
doc/index.md | Website home page |
doc/guide/ | Introduction, onboarding, application guides, testing, and distribution |
doc/reference/ | API index, application and native APIs, CLI commands and configuration |
doc/contributing/ | Framework development and documentation maintenance |
doc/internals/ | Architecture, rendering, and the runtime protocol |
doc/.vitepress/ | Website configuration, navigation, and theme |
doc/README.md | Repository documentation index and local setup |
The introduction explains the reading order for application authors. Contributing covers work on the framework itself.
Write and organize pages
Keep task-oriented guides in guide/, capability and command details in reference/, and implementation contracts in internals/. Link to the next useful step at the end of an onboarding page. Keep prerequisites and current platform support explicit, and distinguish application setup from contributor tooling.
Use one page title and descriptive section headings. Keep examples aligned with the implemented API; identify snippets that require surrounding application code. Use fenced code blocks with a language such as crystal, ecr, sh, or yaml.
Start reference pages with a command or API inventory. Use tables for methods, options, return values and defaults; put a short example beside the relevant API. Keep tutorials in the guides and detailed lifecycle contracts below the lookup tables. Add new public APIs to the inventory as well as their detailed sections. The reference overview and sidebar should provide a direct path to every command and native manager.
Use relative Markdown links for other documentation pages, including section anchors where useful. When moving a page, update links from the rest of the repository as well as the site navigation. Preserve section anchors that are already used by readers.
Link to source files outside doc/ on GitHub under https://github.com/AristoRap/crykit/blob/main/; use tree/main/ for directories. These links work in both the documentation website and GitHub's Markdown view.
Document diagnostics using the exact error text as a heading or example, then explain the cause and resolution. Keep documentation paths and website links out of CLI errors so the message stays useful as documentation moves.
Check a change
Build the site after changing pages or navigation, and review the affected pages in the local preview. Check code blocks, diagrams, tables, search, and navigation on both narrow and wide screens when those areas change. Run git diff --check before submitting documentation changes.