Agent Skills
返回列表
💻

Material 版本化技术文档站

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/build-versioned-technical-docs-sites-with-search-and-nav-using-material-for-mkdocs。

技能介绍

技术文档的三大痛点

  • 版本混乱：多版本文档并存导致内容交叉污染
  • 导航复杂：三级目录结构让关键信息深埋于页面
  • 搜索低效：跨模块检索需要反复跳转浏览器标签页

技能如何解决问题

核心能力

  • 自动导航系统：通过 mkdocs.yml 配置实现版本切换器与目录树联动
  • 实时搜索功能：基于 Lunr.js 的前端搜索引擎，支持模糊匹配与高亮显示
  • 版本隔离机制：利用 Git 标签实现文档分支的物理隔离，避免内容污染

关键步骤

  1. 将 Markdown 文档按 version/ 目录分类
  2. 在配置文件中启用 versions 与 search 插件
  3. 通过 mkdocs build 生成多版本静态站点
  4. 部署至支持 SPA 路由的托管平台（如 GitHub Pages）

适用边界与注意点

  • 环境要求：需要 Python 3.8+ 或 Docker 运行环境
  • 定制限制：主题深度定制需修改 Material 的 CSS/SCSS 源文件
  • 多语言支持：需额外配置 i18n 插件实现文档翻译

使用场景

  • SDK 团队需要为 v1.0 和 v2.0 两个版本分别维护 API 文档，同时提供全文搜索功能
  • 开源项目维护者希望将散落的 README 和教程整合为带目录树的结构化文档站点
  • 企业内部 API 文档散落在多个 Markdown 文件中，需要统一生成可搜索的内部文档站

适合人员

  • SDK 文档工程师需要为多版本 API 维护独立文档并确保用户能快速定位关键接口
  • 开源项目维护者需要将零散的 GitHub README 和 Issue 回复整理成结构清晰、可检索的项目文档
  • 后端团队技术负责人需要为内部微服务 API 构建统一的可搜索文档门户，替代分散的 Wiki 页面