Development Guide

This guide is for contributors to the HealthGuard website.

Requirements

• Node.js: >= 18.0.0
• npm: >= 9.0.0 (this repo uses npm)

Quick Start

git clone https://github.com/Claud-Lu/healthguard-website.git
cd healthguard-website

npm install
npm run dev

The dev server runs at http://localhost:5173 by default.

Commands

Command	Description
npm run dev	Start dev server with HMR
npm run build	Production build to .vitepress/dist/
npm run preview	Preview build output (run after build)
npm run lint	TypeScript type check (tsc --noEmit)

Project Structure

healthguard-website/
├── .github/workflows/      # CI/CD (GitHub Actions)
├── .vitepress/
│   ├── config.ts           # Site config (nav, sidebar, i18n)
│   ├── theme/
│   │   ├── index.ts        # Theme entry
│   │   ├── Layout.vue      # Custom layout (home / docs switch)
│   │   └── style.css       # Brand style overrides
│   └── dist/               # Build output (gitignored)
├── src/
│   └── components/         # Vue components (landing page sections)
│       ├── home/           # Homepage components
│       └── shared/         # Shared components
├── zh/                     # Chinese content
├── en/                     # English content (mirrors zh/)
├── public/                 # Static assets (logo, screenshots, OG image)
├── package.json
├── tsconfig.json
└── README.md

Content Workflow

Adding a Document

Example: adding a "Deployment Guide":

1. Create zh/guide/deployment.md
2. Add frontmatter:

   ---
   title: Deployment Guide
   description: Deploy HealthGuard with Docker Compose
   ---

3. Write the Markdown body
4. Register the link in .vitepress/config.ts sidebar
5. Create the English version en/guide/deployment.md
6. Register in the English sidebar

Editing the Homepage

Homepage components are in src/components/home/. Edit the corresponding Vue file.

Adding Images

1. Place images in public/
2. Reference with /xxx.png in Markdown or Vue

i18n Sync Checklist

After editing any document:

• [ ] Chinese document updated
• [ ] English document synced
• [ ] Sidebars in .vitepress/config.ts synced for both languages
• [ ] Homepage text synced (if affected)
• [ ] Both language versions accessible in dev server

Commit Convention

This project uses Conventional Commits:

feat: new feature
docs: documentation update
fix: bug fix
style: style adjustment
refactor: code refactoring

Pre-deployment Checklist

• [ ] npm run build succeeds without errors
• [ ] npm run lint has no type errors
• [ ] All pages display correctly in npm run preview
• [ ] Language switching works
• [ ] Mobile view looks good
• [ ] All external links are accessible