Skip to content

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:

LanguagePath prefixFolder
简体中文/ (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, editLink and footer under locales in config.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 from useData().lang to 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:

bash
# 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:preview

Build 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 ![caption](/screenshot-1.png).
  • The site is deployed on a custom domain, so base is /. If it moved to a GitHub Pages project site (/ZoneDeck/), VitePress would prefix public assets automatically — Markdown never needs to write base by hand.

VitePress features ​

The documentation uses VitePress custom containers extensively; please stay consistent:

md
::: 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_dispatch on 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.