系统覆写 // SYSTEM OVERRIDE

Appearance

Customization Guide ​

Learn how to customize your VitePress documentation site to match your needs.

Site Configuration ​

All site configuration is centralized in site.config.js at the project root.

Site Metadata ​

javascript
site: {
  title: "My Documentation Site",
  description: "A VitePress documentation site template",
  lang: "en-US",
  base: "/",
}
  • title: Appears in browser tabs and the site header
  • description: Used for SEO and meta tags
  • lang: Language code (e.g., 'en-US', 'zh-CN', 'ja-JP')
  • base: Base URL path if deploying to a subdirectory

Customize the navigation menu in the header:

javascript
theme: {
  nav: [
    { text: "Home", link: "/" },
    { text: "Guide", link: "/guide/getting-started" },
    {
      text: "Dropdown",
      items: [
        { text: "Item A", link: "/item-a" },
        { text: "Item B", link: "/item-b" },
      ],
    },
  ],
}
javascript
theme: {
  logo: "/logo.svg",
  socialLinks: [
    { icon: "github", link: "https://github.com/yourusername/yourproject" },
    { icon: "twitter", link: "https://twitter.com/yourusername" },
    { icon: "discord", link: "https://discord.gg/yourinvite" },
  ],
}

This template includes an automatic sidebar generator utility located at docs/utils/auto-gen-sidebar.mjs.

Using the Sidebar Generator ​

Import and use the set_sidebar function in your VitePress config:

typescript
import { set_sidebar } from "../utils/auto-gen-sidebar.mjs"

export default defineConfig({
  themeConfig: {
    sidebar: set_sidebar("docs/guide"),
  }
})

The generator will automatically create a sidebar based on your directory structure.

Theme Customization ​

Custom Styles ​

The template includes custom theme styles in docs/.vitepress/theme/style.css:

  • Wide screen layout support
  • Custom color schemes
  • Image zoom functionality
  • Responsive design

To modify styles, edit docs/.vitepress/theme/style.css.

Theme Configuration ​

Advanced theme options can be configured in docs/.vitepress/config.mts:

typescript
themeConfig: {
  aside: "left",              // Sidebar position
  outline: [2, 6],            // Heading levels in outline
  outlineTitle: "On This Page",
}

Adding Content ​

Creating New Pages ​

  1. Create a new .md file in the docs directory
  2. Add frontmatter if needed:
markdown
---
title: My Page
description: Page description
---

# My Page Content
  1. Link to it from your navigation or other pages

Organizing Content ​

Create subdirectories to organize your content:

docs/
├── guide/
│   ├── getting-started.md
│   └── advanced.md
├── api/
│   ├── reference.md
│   └── examples.md
└── tutorials/
    └── tutorial-1.md

Deployment ​

See the Deployment Guide for instructions on deploying your site.