Hugo 整合 VitePress 文档

本文档详细记录了将 Hugo 主题升级并整合 VitePress 文档的完整步骤。

1. 项目结构

在开始升级之前，确保项目结构如下：

devin-site/
├── docs/                    # VitePress 文档目录
│   ├── .vitepress/         # VitePress 配置目录
│   │   └── config.mjs      # VitePress 配置文件
│   ├── guide/              # 文档内容目录
│   └── index.md            # 文档首页
├── content/                # Hugo 内容目录
├── layouts/                # Hugo 布局目录
├── static/                 # 静态资源目录
├── hugo.yaml              # Hugo 配置文件
└── package.json           # 项目依赖配置

2. 安装依赖

1. 安装 VitePress 相关依赖：

npm install vitepress vue --save-dev

2. 在 package.json 中添加 VitePress 相关脚本：

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs",
    "build": "npm run docs:build && hugo"
  }
}

3. 配置 VitePress

1. 创建 VitePress 配置文件 docs/.vitepress/config.mjs：

export default {
  title: 'Devin的文档',
  description: 'Devin 的个人文档库',
  base: '/docs/',
  lang: 'zh-CN',
  themeConfig: {
    logo: '/images/site/favicon.webp',
    nav: [
      { text: '首页', link: '/' },
      {
        text: '面试',
        items: [
           {text: 'Java', link: '/interview/java/jvm.md'}, 
           {text: 'Database', link: '/interview/database/base.md'}, 
           {text: 'Spring', link: '/interview/spring/Spring.md'},
           {text: 'MyBatis', link: '/interview/MyBatis.md'}
        ]
      },
      { text: '返回主站', link: 'http://devinkong.cn' },
      {
        text: '导航',
        items: [
          {text: 'it-tools', link: 'http://ittools.devinkong.cn/'},
          {text: 'answer', link: 'http://answer.devinkong.cn/'}
        ]
      }
    ],
    sidebar: {
      '/interview/java/': [
        {
          text: 'Java 编程语言',
          items: [
            {text: 'JVM', link: '/interview/java/jvm.md'},
            {text: '创建对象', link: '/interview/java/createObject.md'},
            {text: 'GC', link: '/interview/java/gc.md'},
            {text: 'JMM', link: '/interview/java/jmm.md'},
            {text: '线程', link: '/interview/java/thread.md'},
            {text: 'JUC', link: '/interview/java/juc.md'},
          ]
        }
      ],
      '/interview/database/': [
        {
          text: '数据库',
          items: [
            {text: '数据库基础', link: '/interview/database/base.md'},
            {text: 'MySQL', link: '/interview/database/mysql.md'},
            {text: 'Redis', link: '/interview/database/redis.md'},
            {text: 'MongoDB', link: '/interview/database/mongoDB.md'},
          ]
        }
      ]
    },
    socialLinks: [
      {icon: 'github', link: 'https://github.com/KongDian'}
    ],
    footer: {
      message: '基于 MIT 许可发布',
      copyright: 'Copyright © 2020-现在 Devin Kong'
    }
  }
}

4. 配置 Hugo

1. 修改 hugo.yaml 配置文件，添加 VitePress 文档目录的挂载：

module:
  mounts:
    - source: docs/.vitepress/dist
      target: static/docs

2. 配置导航菜单，在 data/zh-cn/site.yaml 中添加：

customMenus:
  - name: 首页
    url: /
    weight: 1
  - name: 文档
    url: /docs/
    weight: 2
  - name: 博客
    url: /posts
    weight: 3
  - name: 关于
    url: /#about
    weight: 4

5. 构建和运行

1. 构建 VitePress 文档：

npm run docs:build

2. 启动 Hugo 开发服务器：

hugo server -w

6. 注意事项

1. 确保 VitePress 的 base 配置与 Hugo 的挂载路径一致
2. 文档链接使用相对路径，避免使用绝对路径
3. 返回主站链接使用完整的 URL（开发环境使用 http://localhost:1313）
4. 定期更新文档内容，保持文档的时效性

7. 常见问题

1. 文档链接无法跳转

   • 检查 VitePress 的 base 配置
   • 确保链接路径正确
   • 验证 Hugo 的挂载配置

2. 导航菜单不显示

   • 检查 data/zh-cn/site.yaml 中的 customMenus 配置
   • 确保菜单项的 URL 正确

3. 样式问题

   • 检查 VitePress 和 Hugo 的样式冲突
   • 确保静态资源路径正确

8. 后续优化

1. 添加文档搜索功能
2. 优化文档导航结构
3. 添加文档版本控制
4. 实现文档评论功能
5. 添加文档统计和分析