Maintaining the docs site
This documentation site is built with VitePress. The source lives in the repository's docs/ folder and is deployed to GitHub Pages automatically by GitHub Actions.
Folder structure
docs/
├── .vitepress/
│ ├── config.mts Site configuration (three locales: nav, sidebar, theme)
│ └── theme/ Custom theme (component strings follow useData().lang)
├── public/ Static assets (images / icons, referenced from the root path; shared by all languages)
├── index.md Simplified Chinese home page (hero + features)
├── guide/ Simplified Chinese user guide
├── dev/ Simplified Chinese development docs
├── changelog/ Changelog (generated dynamically from GitHub Releases)
├── en/ English, same structure as the root
│ ├── index.md
│ ├── guide/
│ ├── dev/
│ └── changelog/
└── zh-tw/ Traditional Chinese, same structure as the root
├── index.md
├── guide/
├── dev/
└── changelog/The two kinds of documentation live under guide/ and dev/, each with its own top navigation entry and separate sidebar configured in config.mts.
Localisation
The site uses VitePress locales to provide three languages:
| Language | Path prefix | Folder |
|---|---|---|
| 简体中文 | / (root) | docs/ |
| English | /en/ | docs/en/ |
| 繁體中文 | /zh-tw/ | docs/zh-tw/ |
- Simplified Chinese is the source of truth and stays at the root path, so existing inbound links and SEO are unaffected. When adding or changing documentation, write Simplified Chinese first, then mirror it into the other two.
- Each language has its own
nav,sidebar,editLinkandfooterunderlocalesinconfig.mts; sidebar links must carry the matching path prefix (for example/en/guide/binding). - Internal links must point at pages in the same language, or readers are thrown out of their locale.
- The custom components under
.vitepress/theme/(StatusBar.vue,ReleaseMeta.vue) read the current language fromuseData().langto switch their strings; a single component serves all three languages.
Changelog content is not translated
The version pages under changelog/ are generated by [version].paths.ts from GitHub Releases, and the body is the release body (written in Simplified Chinese). It is shown as published in all three languages; only the page shell (title, "Downloads", publication date) follows the locale.
Local preview
The documentation scripts are in the root package.json:
# Install dependencies (pnpm; npm also works)
pnpm install
# Local development preview (hot reload)
pnpm docs:dev
# Production build
pnpm docs:build
# Preview the production build
pnpm docs:previewBuild output is ignored
docs/.vitepress/dist and docs/.vitepress/cache are in .gitignore; do not commit them.
Images and screenshots
- Put images in
docs/public/and reference them from the root path in Markdown, for example. - The site is deployed on a custom domain, so
baseis/. If it moved to a GitHub Pages project site (/ZoneDeck/), VitePress would prefixpublicassets automatically — Markdown never needs to writebaseby hand.
VitePress features
The documentation uses VitePress custom containers extensively; please stay consistent:
::: tip Tip
For extra advice and best practices.
:::
::: warning Warning
For potential risks and common mistakes.
:::
::: danger Danger
For destructive operations.
:::
::: info Info
Neutral additional information.
:::
::: details Expand
Secondary content, collapsed by default.
:::Deployment workflow
The documentation is deployed to GitHub Pages by .github/workflows/deploy-docs.yml:
- Automatic: when changes touch
docs/**or the workflow itself. - Manual: via
workflow_dispatchon the GitHub Actions page.
The workflow runs pnpm install → pnpm docs:build → upload and deploy to Pages.
Writing conventions
- Use professional, objective descriptions.
- Always call the product ZoneDeck in user-facing text (never lowercase
zonedeck). - When adding a feature, document it in the user guide and, where relevant, update Configuration fields.
- Update all three languages together when changing documentation. Traditional Chinese uses Taiwanese terminology (視窗, 程式, 檔案, 滑鼠, 快速鍵); do not simply convert Simplified characters to Traditional ones.