Documentation Website Builder

This document describes how to build the DDNS documentation website using VitePress.

Overview

The documentation is built using VitePress - a Vue-powered static site generator specifically designed for documentation websites.

Why VitePress?

专为文档设计 - Purpose-built for documentation sites
快速构建 - Lightning-fast build times with Vite
现代化 - Vue 3 + Vite stack, modern developer experience
内置功能丰富 - Search, i18n, dark mode, responsive design out of the box
中文友好 - Created by Evan You (Vue creator), excellent Chinese community support

Features

Built-in Features

响应式导航
- Automatic navigation from directory structure
- Collapsible sidebar sections
- Mobile-friendly hamburger menu
- Active page highlighting
双语支持 (Bilingual Support)
- Built-in i18n (internationalization)
- Chinese (简体中文) and English versions
- Language switcher in navigation
- Separate navigation for each language
页内目录 (Table of Contents)
- Automatically generated from H2-H3 headers
- Sticky sidebar on desktop
- Integrated into content on mobile
- Smooth scroll navigation
搜索功能 (Search)
- Full-text local search
- Keyboard shortcuts
- Instant results
主题切换 (Theme Toggle)
- Light/Dark mode toggle
- Smooth transitions
- Persistent user preference
GitHub 集成
- "Edit this page" link on every page
- Repository link in navigation
- Last updated timestamp
代码高亮 (Code Highlighting)
- Syntax highlighting for multiple languages
- Line numbers
- Code groups and tabs

Requirements

Node.js 18+ or 20+
npm (comes with Node.js)

Installation

Quick Start

One command to install, setup, and build:

npm install
npm run build

This automatically:

Installs dependencies
Sets up directory structure
Builds the static site

Usage

One-Command Build

npm run build

This command automatically:

Sets up the docs directory structure
Copies README and doc/ files
Builds the production site

Output: docs/.vitepress/dist/ directory

Development

Start the development server (auto-setup included):

npm run docs:dev

Then open http://localhost:5173 in your browser.

Building

Build the static site:

npm run docs:build

Preview

Preview the production build locally:

npm run docs:preview

Directory Structure

.
├── package.json              # Node.js dependencies and scripts
├── build_docs.sh            # Build script
├── docs/                    # VitePress docs directory
│   ├── .vitepress/         # VitePress configuration
│   │   ├── config.mts      # Main configuration file
│   │   └── dist/           # Built static site (after build)
│   ├── index.md            # Homepage (Chinese)
│   ├── doc/                # Documentation files (Chinese)
│   │   ├── config/         # Configuration guides
│   │   ├── providers/      # DNS provider documentation
│   │   └── dev/            # Developer documentation
│   └── en/                 # English version
│       ├── index.md        # Homepage (English)
│       └── doc/            # Documentation files (English)

Configuration

The main configuration file is docs/.vitepress/config.mts. It includes:

Site metadata - Title, description, base URL
Navigation - Top navbar structure
Sidebar - Side navigation for different sections
i18n - Multi-language configuration
Theme - Colors, logos, social links
Search - Local search configuration
Markdown - Code highlighting, line numbers

Customizing

To customize the documentation:

Edit docs/.vitepress/config.mts for configuration
Add/edit markdown files in docs/ directory
For Chinese version: docs/doc/**/*.md
For English version: docs/en/doc/**/*.en.md

Adding Documentation

Chinese Documentation

Create markdown file in docs/doc/ directory
Add to sidebar configuration in config.mts
Run npm run docs:dev to preview

English Documentation

Create markdown file with .en.md extension
Place in corresponding directory structure under docs/en/doc/
Add to English sidebar configuration
Run npm run docs:dev to preview

Markdown Features

VitePress supports enhanced markdown features:

Code Blocks

```js
console.log('Hello, World!')
```

Containers (Admonitions)

::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a danger notice
:::

::: details Click to expand
This is hidden by default
:::

Code Groups

::: code-group

sh [npm] npm install vitepress

sh [pnpm] pnpm add vitepress

:::

Custom Containers

::: info Custom Title
This is an info box with custom title
:::

See VitePress Markdown Features for more.

Deployment

The built static site in docs/.vitepress/dist/ can be deployed to:

GitHub Pages - Use GitHub Actions or gh-pages branch
Netlify - Drag & drop or CI/CD
Vercel - Import from GitHub
Any static hosting - Upload dist/ contents

GitHub Pages Example

# .github/workflows/deploy.yml
name: Deploy Docs

on:
  push:
    branches: [master]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: bash build_docs.sh
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vitepress/dist

Advantages Over Other Solutions

✅ Faster than Jekyll/Hugo - Vite-powered instant HMR
✅ More flexible than Docusaurus - Lighter weight, Vue ecosystem
✅ Better i18n than Sphinx - Built-in multi-language support
✅ Easier than custom solutions - Configuration over code
✅ Modern developer experience - Vue 3, TypeScript, Vite
✅ Chinese-friendly - Excellent Chinese documentation and community

Troubleshooting

Node.js Version

If you encounter errors, ensure you're using Node.js 18+ or 20+:

node --version  # Should be v18.x.x or v20.x.x

Port Already in Use

If port 5173 is in use, specify a different port:

npm run docs:dev -- --port 8080

Build Errors

Clear cache and reinstall:

rm -rf node_modules package-lock.json docs/.vitepress/cache
npm install
npm run docs:build

Resources

License

This build configuration is part of the DDNS project and is licensed under the MIT License.

BUILD_DOCS.md 7.1 KB Постоянная ссылка История Исходник