SuperAPI AI 工具集

mkdocs

通用与其它

查看项目

更新于 10-16 01:14

技能介绍

用途:该技能用于使用 MkDocs 和 Material 主题构建专业项目文档,适合开源或内部项目、需要快速可搜索的静态文档站点、希望无需自定义 CSS 即获得 Material Design 外观、需要多版本文档(如 v1.x、v2.x)、部署到 GitHub Pages、GitLab Pages 或 Netlify、Python 项目随代码附带文档、需要提示框、代码选项卡与内容格式化、基于 Markdown 的简单文档工作流、离线可用文档,以及指南与 API 文档并存的场景。

主要能力:覆盖站点配置、导航结构、插件生态、搜索优化、使用 mike 的版本管理、Mermaid 图表集成、自定义 CSS/JS 扩展、GitHub Pages 部署工作流,以及最佳实践与故障排查。子技能涉及项目初始化、导航结构、与 Python 包集成、文档结构、示例、常见问题,以及提示框(Note、Tip、Warning、Danger、Example、Info、Success、Question、Quote、可折叠提示框)、代码块功能(标题、行号、行高亮、起始行号、代码注释、选项卡式代码块)、Mermaid 图表(流程图、时序图、类图、状态图、实体关系图)、插件配置、缩写等。

使用方式:安装命令为 pip install mkdocs mkdocs-material,或使用 uv pip install mkdocs mkdocs-material;安装常用插件可用 pip install mkdocs mkdocs-material mkdocs-minify-plugin。系统要求 Python 3.8 或更高、pip 或 uv 包管理器、Git(用于 git-revision 插件和 mike),Node.js 可选(用于社交卡片)。

限制:不适合需要复杂 React 组件的文档(应使用 Docusaurus)、需要自动生成 Python API 文档(应使用 Sphinx)、单页文档(应使用简单 HTML)、文档格式转换(应使用 Pandoc)、实时协作编辑(应使用 GitBook)或幻灯片演示(应使用 Marp)。