文档自动化

本指南介绍用于维护 Hugo 网站文档的自动化系统和流程，包括定期维护、质量保障和持续集成工作流。

概述

文档自动化系统提供：

自动质量检查：持续验证内容和结构
定期维护：定期健康检查和新鲜度审计
CI/CD 集成：在拉取请求和部署时进行验证
指标与报告：全面分析与洞察
通知系统：维护问题和更新提醒

自动化维护脚本

核心维护命令

# 每日健康检查
npm run docs-health

# 每周新鲜度审计
npm run docs-freshness

# 综合维护（每周/每月）
npm run docs-maintenance

# 生成文档指标
npm run generate-docs-metrics

# 完整验证套件
npm run validate-docs

# 链接验证
npm run link-check

脚本说明

`npm run docs-health`

用途：快速检查文档系统健康频率：每日 检查内容：

必需文件和目录是否存在
基本结构验证
检测 TODO 项和过时内容
识别关键问题

输出：控制台报告，状态颜色标识

`npm run docs-freshness`

用途：内容新鲜度和相关性审计频率：每周 检查内容：

90 天未更新文件（警告）
180 天未更新文件（需审核）
最近更新活动
外部链接健康
图片引用验证

输出：详细新鲜度报告及建议

`npm run docs-maintenance`

用途：综合维护套件频率：每周（自动）或按需 包含内容：

完整健康检查
内容新鲜度审计
链接验证
文档结构验证
生成报告并通知

输出：综合维护报告，保存为文件

`npm run generate-docs-metrics`

用途：生成详细文档分析数据频率：每月或按需指标：

内容统计（字数、文件数、链接数）
健康指标（新鲜度、完整性）
结构分析（分类、组织）
质量评分（元数据、格式）

输出：JSON、文本和 CSV 报告

`npm run validate-docs`

用途：全面文档验证频率：每次拉取请求和部署 验证内容：

Markdown 语法和结构
前置元数据完整性
内外部链接检查
代码示例验证
交叉引用校验

输出：详细验证报告，包含错误和警告

自动化设置

GitHub Actions 集成

创建 .github/workflows/documentation.yml 实现自动维护：

name: Documentation Maintenance

on:
  # 拉取请求触发
  pull_request:
    paths:
      - 'docs/**'
      - 'README.md'
      - '*.md'

  # 定时维护
  schedule:
    - cron: '0 2 * * 1'  # 每周一凌晨 2 点
    - cron: '0 8 * * *'  # 每天早上 8 点健康检查

  # 手动触发
  workflow_dispatch:
    inputs:
      maintenance_type:
        description: '维护类型'
        required: true
        default: 'full'
        type: choice
        options:
          - 'health'
          - 'freshness'
          - 'full'
          - 'metrics'

jobs:
  # 拉取请求快速验证
  validate:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: 安装依赖
        run: npm ci

      - name: 验证文档
        run: npm run validate-docs

      - name: 检查文档健康
        run: npm run docs-health

      - name: 验证链接
        run: npm run link-check

  # 每日健康检查
  daily-health:
    if: github.event.schedule == '0 8 * * *'
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: 安装依赖
        run: npm ci

      - name: 运行健康检查
        run: npm run docs-health

      - name: 失败时创建 Issue
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            const title = '每日文档健康检查失败';
            const body = `
            ${new Date().toISOString().split('T')[0]} 的每日文档健康检查失败。

            请查看工作流日志并解决发现的问题。

            **后续步骤:**
            1. 查看失败的工作流日志
            2. 本地运行 \`npm run docs-health\` 复现问题
            3. 修复所有已识别问题
            4. 问题解决后关闭此 Issue

            此 Issue 由文档维护工作流自动创建。
            `;

            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: title,
              body: body,
              labels: ['documentation', 'maintenance', 'automated']
            });

  # 每周综合维护
  weekly-maintenance:
    if: github.event.schedule == '0 2 * * 1' || (github.event_name == 'workflow_dispatch' && github.event.inputs.maintenance_type == 'full')
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: 安装依赖
        run: npm ci

      - name: 运行综合维护
        run: npm run docs-maintenance
        env:
          SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}
          EMAIL_REPORT: 'false'

      - name: 生成指标
        run: npm run generate-docs-metrics

      - name: 上传维护报告
        uses: actions/upload-artifact@v4
        with:
          name: maintenance-reports-${{ github.run_number }}
          path: |
            docs-maintenance-report-*.txt
            docs-metrics-*.json
            docs-metrics-*.txt
            docs-metrics-*.csv
          retention-days: 30

      - name: 创建维护汇总 Issue
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const path = require('path');

            // 查找最新维护报告
            const files = fs.readdirSync('.');
            const reportFile = files.find(f => f.startsWith('docs-maintenance-report-'));

            let reportContent = '未找到报告文件';
            if (reportFile) {
              reportContent = fs.readFileSync(reportFile, 'utf8');
              // 超长时截断
              if (reportContent.length > 60000) {
                reportContent = reportContent.substring(0, 60000) + '\n\n... (已截断)';
              }
            }

            const title = `每周文档维护报告 - ${new Date().toISOString().split('T')[0]}`;
            const body = `
            ## 每周文档维护报告

            **生成时间**: ${new Date().toISOString()}
            **工作流运行**: [#${context.runNumber}](${context.payload.repository.html_url}/actions/runs/${context.runId})

            ### 报告详情

            \`\`\`
            ${reportContent}
            \`\`\`

            ### 附件

            详细报告可在工作流附件中获取：
            - 维护报告（文本）
            - 文档指标（JSON、文本、CSV）

            ### 后续步骤

            请审核上述报告并处理所有问题或建议。
            若无关键问题，此 Issue 将于 7 天后自动关闭。

            ---
            *本报告由文档维护工作流自动生成。*
            `;

            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: title,
              body: body,
              labels: ['documentation', 'maintenance', 'weekly-report']
            });

  # 手动维护任务
  manual-maintenance:
    if: github.event_name == 'workflow_dispatch' && github.event.inputs.maintenance_type != 'full'
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 设置 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: 安装依赖
        run: npm ci

      - name: 运行健康检查
        if: github.event.inputs.maintenance_type == 'health'
        run: npm run docs-health

      - name: 运行新鲜度审计
        if: github.event.inputs.maintenance_type == 'freshness'
        run: npm run docs-freshness

      - name: 生成指标
        if: github.event.inputs.maintenance_type == 'metrics'
        run: npm run generate-docs-metrics

      - name: 上传报告
        uses: actions/upload-artifact@v4
        with:
          name: manual-maintenance-${{ github.event.inputs.maintenance_type }}-${{ github.run_number }}
          path: |
            docs-maintenance-report-*.txt
            docs-metrics-*.json
            docs-metrics-*.txt
            docs-metrics-*.csv
          retention-days: 7

本地自动化设置

Cron 定时任务（Linux/macOS）

# 编辑 crontab
crontab -e

# 添加以下条目实现自动维护
# 每天早上 8 点健康检查
0 8 * * * cd /path/to/project && npm run docs-health >> /var/log/docs-health.log 2>&1

# 每周一凌晨 2 点综合维护
0 2 * * 1 cd /path/to/project && npm run docs-maintenance >> /var/log/docs-maintenance.log 2>&1

# 每月 1 日凌晨 3 点生成指标
0 3 1 * * cd /path/to/project && npm run generate-docs-metrics >> /var/log/docs-metrics.log 2>&1

Windows 任务计划

为每个维护任务创建批处理文件：

docs-health.bat:

@echo off
cd /d "C:\path\to\project"
npm run docs-health >> C:\logs\docs-health.log 2>&1

docs-maintenance.bat:

@echo off
cd /d "C:\path\to\project"
npm run docs-maintenance >> C:\logs\docs-maintenance.log 2>&1

然后使用 Windows 任务计划程序按需调度。

通知系统

Slack 集成

设置 Slack 通知用于维护提醒：

# 设置 Slack webhook 地址
export SLACK_WEBHOOK="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

# 运行维护并发送 Slack 通知
npm run docs-maintenance

Slack 消息格式：

✅ 成功："文档维护已成功完成"
⚠️ 警告："文档维护完成，发现 N 个警告"
❌ 错误："文档维护失败 - 需立即处理"

邮件通知

配置邮件提醒关键问题：

# 启用邮件报告
export EMAIL_REPORT=true
export EMAIL_TO="[email protected]"

# 运行并发送邮件通知
npm run docs-maintenance

GitHub Issues 集成

自动创建 Issue 用于：

每日健康检查失败：创建带 maintenance 标签的 Issue
每周维护报告：创建汇总报告 Issue
关键验证失败：创建紧急 Issue，带 critical 标签

指标与分析

关键绩效指标

内容健康指标：

文档覆盖率：已文档化功能占比
内容新鲜度：文档文件平均年龄
链接健康：有效链接占比
验证得分：通过验证文件占比

质量指标：

完整性得分：有完整元数据文件占比
结构得分：文档标准符合度
用户参与度：文档站点分析
维护速度：代码变更后文档更新时长

指标仪表盘

生成全面指标：

# 生成所有指标
npm run generate-docs-metrics

# 控制台查看摘要
npm run generate-docs-metrics | grep "SUMMARY"

# 导出供外部分析
npm run generate-docs-metrics && echo "报告已生成在当前目录"

生成报告：

docs-metrics-YYYY-MM-DD.json：机器可读指标
docs-metrics-YYYY-MM-DD.txt：人类可读报告
docs-metrics-YYYY-MM-DD.csv：表格数据

分析集成

Google Analytics 设置（如有文档站点）：

跟踪页面浏览和用户参与
监控搜索查询和热门内容
识别内容缺口和用户需求

GitHub 分析：

跟踪仓库活动和贡献
统计 Issue 创建与解决时长
分析文档相关拉取请求模式

自动化故障排查

常见问题

脚本执行失败：

# 检查 Node.js 版本
node --version  # 应为 18+

# 验证依赖
npm list

# 调试输出运行
DEBUG=* npm run docs-health

权限问题：

# 使脚本可执行
chmod +x scripts/*.sh

# 检查文件权限
ls -la scripts/

GitHub Actions 失败：

检查 GitHub Actions 标签下的工作流日志
验证 secrets 配置
确认 Node.js 版本兼容

调试命令

# 测试单个组件
npm run validate-docs -- --verbose
npm run link-check -- --debug
npm run docs-health -- --detailed

# 检查脚本语法
bash -n scripts/check-docs-health.sh
node --check scripts/validate-documentation.js

# 手动验证
markdownlint docs/
htmlproofer --check-html --check-opengraph --check-favicon --check-img-http public/

最佳实践

自动化指南

逐步实施：先做基础健康检查，再逐步完善综合维护
容错设计：脚本需优雅处理错误并反馈
通知平衡：避免过度提醒，确保关键问题及时报告
性能优化：尽量使用缓存和增量检查
文档完善：维护脚本需有良好文档和可维护性

维护调度

每日：快速健康检查和关键问题检测每周：综合维护和新鲜度审计每月：详细指标生成和战略回顾 每季度：文档策略全面回顾与流程优化

质量保障

先在开发环境测试自动化脚本
监控自动化性能并调整频率
定期评估通知有效性和相关性
持续改进，结合指标和用户反馈

与开发流程集成

提交前钩子

设置 Git 钩子自动验证文档：

# .git/hooks/pre-commit
#!/bin/bash
# 提交前验证文档变更

if git diff --cached --name-only | grep -E '\.(md|yml|yaml)$' > /dev/null; then
    echo "正在验证文档变更..."
    npm run validate-docs:test
    if [ $? -ne 0 ]; then
        echo "文档验证失败，请修复后再提交。"
        exit 1
    fi
fi

拉取请求模板

在 PR 模板中加入文档检查清单：

## 文档检查清单

- [ ] 新功能已更新文档
- [ ] 链接已验证且可用
- [ ] 代码示例已测试
- [ ] 前置元数据完整
- [ ] 本地验证通过（`npm run validate-docs`）

发布流程集成

在发布流程中包含文档更新：

# 发布前文档检查
npm run validate-docs
npm run generate-docs-metrics

# 发布后文档更新
# 更新版本引用
# 生成变更日志
# 更新兼容性矩阵

此自动化系统可确保文档维护一致、高质量，最大限度减少人工干预，并提供全面的文档健康和使用洞察。