配置参考

本页面面向希望修改或自定义本文档站的用户，说明站点配置的关键项和调整方法。文档站基于 VuePress 2 构建，使用 @vuepress/theme-default 默认主题。

站点基本信息

在 docs/.vuepress/config.ts 中，你可以修改以下核心配置项：

标题与描述

export default defineUserConfig({
  lang: 'zh-CN',                    // 站点语言
  title: 'OVEROUTES',               // 站点标题（显示在导航栏和浏览器标签页）
  description: 'OVEROUTES 文档站',   // 站点描述（用于 SEO）
})

域名与 SEO

head: [
  ['link', { rel: 'canonical', href: 'https://overoutes.com/' }],
],

canonical 标签告诉搜索引擎你的网站的权威地址，防止重复内容问题。如果你使用不同的域名，务必修改这里。

导航栏配置

导航栏（Navbar）定义了页面顶部的菜单结构。配置位于 theme 选项的 navbar 字段中：

navbar: [
  { text: '首页', link: '/' },
  { text: '阅读须知', link: '/guide/' },
  {
    text: '机场',
    children: [
      { text: '总览', link: '/airport/' },
      { text: '选购要点', link: '/airport/selection' },
      { text: '协议详解', link: '/airport/protocol' },
      { text: '客户端使用', link: '/airport/client' },
    ],
  },
  // ...更多菜单项
],

注意事项：

  • link 使用相对路径，从 docs 目录开始
  • children 可以嵌套，形成下拉菜单
  • 以 / 结尾的链接会自动指向该目录下的 README.md

侧边栏配置

侧边栏（Sidebar）定义了每个板块的左侧导航结构：

sidebar: {
  '/airport/': [
    {
      text: '机场',
      children: [
        '/airport/README.md',
        '/airport/selection.md',
        '/airport/protocol.md',
        '/airport/client.md',
      ],
    },
  ],
  // ...更多板块
},

提示：添加新页面时，需要同时更新 sidebar 配置以使其出现在侧边栏导航中。

搜索配置

本站集成了 Algolia DocSearch。搜索功能通过环境变量配置：

环境变量说明
ALGOLIA_APP_IDAlgolia 应用 ID
ALGOLIA_API_KEYAlgolia 搜索 API Key（只读）
ALGOLIA_INDEX_NAMEAlgolia 索引名称

如果你暂时没有 Algolia 配置，搜索功能会自动关闭，不影响构建和使用。

如何获取 Algolia DocSearch？

  1. 前往 DocSearch 官网 申请
  2. 申请通过后会获得 App ID、API Key 和 Index Name
  3. 将它们设置为环境变量或写入 .env 文件

主题定制

颜色

在 docs/.vuepress/styles/index.scss 中自定义主题颜色：

:root {
  --vp-c-brand: #3eaf7c;        // 主品牌色
  --vp-c-brand-light: #4abf8a;  // 品牌色（亮）
  --vp-c-brand-dark: #33a067;   // 品牌色（暗）
}

Logo 与 Favicon

将你的 Logo 和 Favicon 文件放在 docs/.vuepress/public/ 目录下：

  • logo.png — 导航栏 Logo
  • favicon.png — 浏览器标签页图标

本地开发

环境要求

  • Node.js 18+
  • npm 9+

启动开发服务器

npm install    # 首次运行时安装依赖
npm run dev    # 启动开发服务器

构建生产版本

npm run build  # 输出到 docs/.vuepress/dist

构建产物位于 docs/.vuepress/dist 目录下，可以直接部署到任意静态托管服务。

部署

GitHub Pages

可以通过 GitHub Actions 自动构建和部署。创建 .github/workflows/deploy.yml：

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vuepress/dist

自有服务器

将构建产物上传到你的 Web 服务器即可。推荐使用 Nginx 或 Caddy 作为静态文件服务器。

最近更新: