Website Guidelines

How to build, edit, and deploy the qzjs documentation website.

Tech Stack

• VitePress — static site generator
• Mermaid — architecture diagrams (via vitepress-plugin-mermaid)
• Node.js — build toolchain (npm run build)
• GitHub Pages — hosting (auto-deployed on push to master)

Quick Start

cd docs
npm install        # first time only
npm run dev        # dev server at http://localhost:5173/qzjs/
npm run build      # production build → .vitepress/dist/
npm run preview    # preview production build

Content Rules

Page Structure

Every .md file must have frontmatter:

---
title: Page Title
description: SEO description — one sentence summary for search engines.
---

Language

• English pages in docs/ root
• Chinese pages in docs/zh/ (mirror directory structure)
• When adding a new English page, create the Chinese version immediately
• Both versions must be linked in docs/.vitepress/config.mjs sidebar

Writing Style

• Code blocks must specify language: ```c, ```js, ```bash
• Keep technical identifiers unchanged across translations (C99, CMake, QuickJS-ng, WinterTC, WAMR)
• Link to other pages using root-relative paths: /guide/quickstart, /zh/guide/quickstart
• Do not expose internal implementation details (bridge internals)
• C API reference exists at /c-api/ but is NOT in main navigation — it's for embedders

SEO

• Every page must have a unique <title> (from frontmatter) and <meta description>
• Sitemap auto-generated by scripts/generate-sitemap.mjs (run after build)
• robots.txt auto-generated
• Open Graph tags configured in config.mjs head section
• Schema.org SoftwareApplication on homepage

Navigation

Sidebar structure defined in docs/.vitepress/config.mjs:

const sidebar = {
  guide: [...],   // Getting Started, Core Concepts, Advanced
  jsApi: [...],   // Web APIs, Platform APIs, Data & Events
}
const nav = [
  { text: 'Guide', link: '/guide/' },
  { text: 'JS API', link: '/js-api/' },
  { text: 'GitHub', link: 'https://github.com/adam-ikari/qzjs' },
]

Rules:

• C API pages exist but are NOT in nav (search-only for embedders)
• Chinese nav mirrors English but with translated labels
• Every new page must be added to both en and zh sidebars

Adding a New Page

1. Create docs/section/new-page.md with frontmatter
2. Add to sidebar in docs/.vitepress/config.mjs (en section)
3. Add to sidebar in docs/.vitepress/config.mjs (zh section)
4. Create docs/zh/section/new-page.md with Chinese translation
5. Build: cd docs && npm run build — must show 0 dead links
6. Verify sitemap URL count increased correctly
7. Commit and push — GitHub Pages deploys automatically

Polyfill Rebuild

When editing polyfill/src/*.js:

cd polyfill
QJSC=../build/deps/quickjs-ng/qjsc npm run build
# This regenerates src/polyfill_<mode>.c (rodata default: src/polyfill_default.c)
# Then rebuild qzjs: cmake --build build

Pre-commit Checklist

• [ ] npm run build passes with 0 dead links
• [ ] New pages have frontmatter (title + description)
• [ ] Both en and zh versions exist (or explicit decision to skip zh)
• [ ] Sidebar entries added for both languages
• [ ] Code blocks have language annotations
• [ ] No internal implementation details exposed
• [ ] Links use root-relative paths
• [ ] No reference to "polyfill" in user-facing content (use "WinterTC runtime" instead)