VitePress文档站搭建

二月 2, 2025 80 1092 3 分钟

笔记

过年闲来无事研究了下Vitepress文档站，记录一些使用上的问题。

1. 简介

VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面，适用于文档站、博客等静态网站。

1.1. 对比

VitePress：
- 适用场景：适合快速开发和部署的文档项目，尤其是技术文档和博客。
- 编辑内容：支持 Markdown 和 Vue 组件，适合技术类内容的编写，编辑体验流畅。
- 特点：性能出色（冷启动快、热更新快），配置简单，内置搜索和多语言支持。
VuePress：
- 适用场景：适合复杂的文档网站和博客。
- 编辑内容：支持 Markdown 和 Vue 组件，但配置相对复杂，适合有一定技术背景的用户。
- 特点：功能丰富，生态系统成熟，插件和主题丰富。
Hexo：
- 适用场景：适合个人博客和大型文档站点。
- 编辑内容：支持 Markdown，配置灵活，但需要一定的 Node.js 知识。
- 特点：构建速度快，主题丰富，适合对性能要求高的项目。
Nuxt Content：
- 适用场景：适合需要 SSR 和复杂自定义的项目。
- 编辑内容：支持 Markdown 和 Vue 组件，依托 Nuxt 生态，适合复杂内容的编写。
- 特点：支持 SSR 和静态生成，自定义能力强。
GitBook：
- 适用场景：适合企业知识库和文档协作。
- 编辑内容：用户友好，适合非技术用户，但自定义能力有限。
- 特点：优秀的版本控制和协作功能，适合团队使用。

2. 常见问题

2.1. 国际化

要使用内置的 i18n (国际化) 功能，需要特定的目录结构：

docs/
├─ es/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ foo.md

然后配置vite.config.ts

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 共享属性和其他顶层内容...

  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    fr: {
      label: 'French',
      lang: 'fr', // 可选，将作为 `lang` 属性添加到 `html` 标签中
      link: '/fr/guide' // 默认 /fr/ -- 显示在导航栏翻译菜单上，可以是外部的

      // 其余 locale 特定属性...
    }
  }
})

也可以直接使用vitepress-i18n插件快速配置，默认主题搜索、弹窗不是中文的。

import { defineConfig, UserConfig } from 'vitepress'
import { withI18n } from 'vitepress-i18n'
import type { VitePressI18nOptions } from 'vitepress-i18n/types'

const vitePressConfig: UserConfig = {
  title: "文档站",
  description: "这是网站描述",
  lang: 'zh',
  cleanUrls: true,
  themeConfig: {
    logo: '/images/logo.png',
    siteTitle: '',

    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: '首页', link: '/' },
      { text: '开始', link: '/start/' },
    ],

    footer: {
      copyright: 'Copyright © 2024-2025 Timeless All rights reserved. '
    },

    socialLinks: [
      { icon: {
          svg: '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200" class="icon" viewBox="0 0 1024 1024"><path fill="#5A5A5A" d="M512 0C230.4 0 0 230.4 0 512s230.4 512 512 512 512-230.4 512-512S793.6 0 512 0M364.089 813.511l-71.111-17.067 2.844-14.222c25.6-99.555 76.8-187.733 147.911-258.844-22.755-36.978-19.91-85.334 8.534-119.467 34.133-36.978 88.177-45.511 130.844-17.067s56.889 82.49 34.133 128c-19.91 42.667-68.266 62.578-113.777 54.045C435.2 631.467 386.844 711.11 364.089 802.133zM768 605.867C719.644 691.2 628.622 742.4 531.911 742.4c-14.222 0-28.444 0-45.511-2.844l-14.222-2.845 11.378-71.111 14.222 2.844C583.11 682.667 668.444 640 708.267 563.2c39.822-76.8 25.6-170.667-36.978-230.4-65.422-65.422-170.667-76.8-250.311-25.6s-110.934 153.6-73.956 241.778l5.69 14.222-68.268 28.444-5.688-14.222c-14.223-31.289-19.912-68.266-19.912-102.4 0-113.778 71.112-216.178 179.2-256 108.09-39.822 227.556-8.533 301.512 79.645 73.955 82.489 85.333 207.644 28.444 307.2"/></svg>'
        }, 
        link: 'https://www.timelessq.com'
      },
      { icon: 'github', link: 'https://github.com/spacesless' }
    ],

    lastUpdated: true
  },

  sitemap: {
    hostname: 'https://docs.timelessq.com'
  }
}

const vitePressI18nConfig: VitePressI18nOptions = {
  locales: ['zhHans'],
  rootLocale: 'zhHans',
  searchProvider: 'local',
}

// https://vitepress.dev/reference/site-config
export default defineConfig(
  withI18n(vitePressConfig, vitePressI18nConfig)
)

2.2. 菜单

使用vitepress-sidebar插件可以快速配置侧边菜单

import { defineConfig, UserConfig } from 'vitepress'
import { withSidebar } from 'vitepress-sidebar'
import { withI18n } from 'vitepress-i18n'
import type { VitePressSidebarOptions } from 'vitepress-sidebar/types'
import type { VitePressI18nOptions } from 'vitepress-i18n/types'

const vitePressConfig: UserConfig = {
  title: "文档站",
  description: "这是网站描述",
  lang: 'zh',
  cleanUrls: true,
  themeConfig: {
    logo: '/images/logo.png',
    siteTitle: '',

    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: '首页', link: '/' },
      { text: '开始', link: '/start/' },
    ],

    footer: {
      copyright: 'Copyright © 2024-2025 Timeless All rights reserved. 8003656号-1</a>'
    },

    socialLinks: [
      { icon: {
          svg: '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200" class="icon" viewBox="0 0 1024 1024"><path fill="#5A5A5A" d="M512 0C230.4 0 0 230.4 0 512s230.4 512 512 512 512-230.4 512-512S793.6 0 512 0M364.089 813.511l-71.111-17.067 2.844-14.222c25.6-99.555 76.8-187.733 147.911-258.844-22.755-36.978-19.91-85.334 8.534-119.467 34.133-36.978 88.177-45.511 130.844-17.067s56.889 82.49 34.133 128c-19.91 42.667-68.266 62.578-113.777 54.045C435.2 631.467 386.844 711.11 364.089 802.133zM768 605.867C719.644 691.2 628.622 742.4 531.911 742.4c-14.222 0-28.444 0-45.511-2.844l-14.222-2.845 11.378-71.111 14.222 2.844C583.11 682.667 668.444 640 708.267 563.2c39.822-76.8 25.6-170.667-36.978-230.4-65.422-65.422-170.667-76.8-250.311-25.6s-110.934 153.6-73.956 241.778l5.69 14.222-68.268 28.444-5.688-14.222c-14.223-31.289-19.912-68.266-19.912-102.4 0-113.778 71.112-216.178 179.2-256 108.09-39.822 227.556-8.533 301.512 79.645 73.955 82.489 85.333 207.644 28.444 307.2"/></svg>'
        }, 
        link: 'https://www.timelessq.com'
      },
      { icon: 'github', link: 'https://github.com/spacesless' }
    ],

    lastUpdated: true
  },

  sitemap: {
    hostname: 'https://docs.timelessq.com'
  }
}
const commonSidebarConfig: VitePressSidebarOptions = {
  collapsed: true,
  capitalizeFirst: true,
  useTitleFromFileHeading: true,
  useTitleFromFrontmatter: true,
  useFolderTitleFromIndexFile: true,
  frontmatterOrderDefaultValue: 9,
  sortMenusByFrontmatterOrder: true
};

const vitePressSidebarConfig = [
  {
    ...commonSidebarConfig,
    scanStartPath: 'start',
    resolvePath: '/start/'
  }
]

const vitePressI18nConfig: VitePressI18nOptions = {
  locales: ['zhHans'],
  rootLocale: 'zhHans',
  searchProvider: 'local',
}

// https://vitepress.dev/reference/site-config
export default defineConfig(
  withSidebar(withI18n(vitePressConfig, vitePressI18nConfig), vitePressSidebarConfig)
)

2.3. 自定义主题

在.vitepress目录下，新增style、component文件，然后配置index.ts，引入style修改样式，并规定在哪里渲染组件

// index.css
:root {  
  --vp-layout-max-width: 100%;
  --vp-c-indigo-1: #13C2C2;
  --vp-c-indigo-2: #36cfc9;
  --vp-c-indigo-3: #5cdbd3;
  --vp-nav-logo-height: 32px;
}

比如在文档结尾添加Waline评论，在广告区域添加谷歌广告

// index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import WalineComment from './WalineComment.vue'
import Adsense from './Adsense.vue'
//引入样式文件
import './style.css';  

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'doc-after': () => h(WalineComment),
      'aside-ads-before': () => h(Adsense)
    })
  }
}

恰饭区

广告位招租

Power by Node.js + Nuxt.js，由腾讯云提供服务, 已经稳稳地存活了 8年95天