配置说明

本文档详细介绍 AutoDoc 系统的各种配置选项和自定义方法。

📁 基础配置

VuePress 配置文件

主要配置文件位于 docs/.vuepress/config.js：

import { defineUserConfig } from 'vuepress'
import { defaultTheme } from '@vuepress/theme-default'
import { searchPlugin } from '@vuepress/plugin-search'

export default defineUserConfig({
  lang: 'zh-CN',
  title: 'AutoDoc - 智能文档系统',
  description: '基于 VuePress 的智能文档系统，支持自动发现和全文搜索',

  theme: defaultTheme({
    // 主题配置
  }),

  plugins: [
    // 插件配置
  ]
})

目录结构配置

AutoDoc 使用约定优于配置的原则，推荐的目录结构：

docs/
├── README.md           # 首页
├── guide/              # 使用指南
├── api/                # API 文档
├── automation/         # 自动化相关
├── ai/                 # AI 助手
└── .vuepress/          # VuePress 配置
    ├── config.js       # 主配置
    └── public/         # 静态资源

🎨 主题配置

导航栏配置

theme: defaultTheme({
  navbar: [
    { text: '首页', link: '/' },
    { text: '使用指南', link: '/guide/' },
    { text: 'API 文档', link: '/api/' },
    {
      text: '更多',
      children: [
        { text: '自动化', link: '/automation/' },
        { text: 'AI 助手', link: '/ai/' }
      ]
    }
  ]
})

侧边栏配置

AutoDoc 支持自动侧边栏生成：

theme: defaultTheme({
  // 自动生成侧边栏
  sidebar: 'auto',
  
  // 或者手动配置特定目录
  sidebar: {
    '/guide/': [
      {
        text: '使用指南',
        children: [
          '/guide/README.md',
          '/guide/getting-started.md',
          '/guide/configuration.md'
        ]
      }
    ]
  }
})

仓库配置

theme: defaultTheme({
  repo: 'your-username/autodoc',
  editLink: true,
  editLinkText: '在 GitHub 上编辑此页',
  lastUpdated: true,
  lastUpdatedText: '最后更新',
  contributors: true,
  contributorsText: '贡献者'
})

🔍 搜索配置

搜索插件配置

plugins: [
  searchPlugin({
    locales: {
      '/': {
        placeholder: '搜索文档',
      },
    },
    hotKeys: ['s', '/'],
    maxSuggestions: 10,
    isSearchable: (page) => page.path !== '/',
  })
]

搜索选项说明

placeholder: 搜索框占位符文本
hotKeys: 搜索快捷键
maxSuggestions: 最大搜索建议数
isSearchable: 控制哪些页面可被搜索

🔧 高级配置

自定义样式

在 docs/.vuepress/styles/ 目录下创建样式文件：

/* docs/.vuepress/styles/index.css */
:root {
  --c-brand: #3eaf7c;
  --c-brand-light: #4abf8a;
}

.navbar-brand {
  font-weight: bold;
}

自定义组件

在 docs/.vuepress/components/ 目录下创建 Vue 组件：

<!-- docs/.vuepress/components/CustomComponent.vue -->
<template>
  <div class="custom-component">
    <h3>{{ title }}</h3>
    <p>{{ content }}</p>
  </div>
</template>

<script>
export default {
  props: {
    title: String,
    content: String
  }
}
</script>

插件配置

添加更多插件来扩展功能：

import { pwaPlugin } from '@vuepress/plugin-pwa'
import { seoPlugin } from '@vuepress/plugin-seo'

export default defineUserConfig({
  plugins: [
    searchPlugin({
      // 搜索配置
    }),
    pwaPlugin({
      // PWA 配置
    }),
    seoPlugin({
      // SEO 配置
    })
  ]
})

📱 响应式配置

移动端优化

theme: defaultTheme({
  // 移动端侧边栏配置
  sidebarDepth: 2,
  
  // 移动端导航栏配置
  navbar: [
    { text: '首页', link: '/' },
    { text: '指南', link: '/guide/' }
  ]
})

多语言配置

export default defineUserConfig({
  locales: {
    '/': {
      lang: 'zh-CN',
      title: 'AutoDoc',
      description: '智能文档系统'
    },
    '/en/': {
      lang: 'en-US',
      title: 'AutoDoc',
      description: 'Intelligent Documentation System'
    }
  },
  
  theme: defaultTheme({
    locales: {
      '/': {
        navbar: [
          { text: '首页', link: '/' },
          { text: '指南', link: '/guide/' }
        ]
      },
      '/en/': {
        navbar: [
          { text: 'Home', link: '/en/' },
          { text: 'Guide', link: '/en/guide/' }
        ]
      }
    }
  })
})

🚀 构建配置

构建选项

export default defineUserConfig({
  // 基础路径
  base: '/autodoc/',
  
  // 输出目录
  dest: 'dist',
  
  // 构建时的临时目录
  temp: '.vuepress/.temp',
  
  // 缓存目录
  cache: '.vuepress/.cache'
})

性能优化

export default defineUserConfig({
  bundler: '@vuepress/bundler-vite',
  bundlerConfig: {
    viteOptions: {
      build: {
        rollupOptions: {
          output: {
            manualChunks: {
              vendor: ['vue', 'vue-router']
            }
          }
        }
      }
    }
  }
})

📋 环境配置

开发环境

// 开发环境特定配置
if (process.env.NODE_ENV === 'development') {
  config.plugins.push(
    // 开发环境插件
  )
}

生产环境

// 生产环境特定配置
if (process.env.NODE_ENV === 'production') {
  config.plugins.push(
    // 生产环境插件
  )
}