Mkdocs Shadcn

mkdocs-shadcn 主题排版技能

目录

1. 工作流程
2. 页面模板
3. 资源文件速查
4. 决策流程
5. 反例清单

工作流程（每次运行技能时必须运行该工作流程中的所有步骤）

🔴 CHECKPOINT · 🛑 STOP：开始前确认项目目录和 mkdocs.yml 路径正确。

1. 检查项目配置

输入：项目目录路径 输出：配置检查报告，列出问题和建议修复

运行配置检查脚本：

python <mkdocs-shadcn-path>/scripts/check_config.py <项目目录> [--apply]

脚本会自动检查并补充：

• theme.name 是否为 shadcn
• plugins 是否包含必要插件（search）
• markdown_extensions 是否包含推荐的扩展（admonition, codehilite, fenced_code, footnotes, pymdownx.blocks.details, pymdownx.blocks.tab, pymdownx.progressbar, pymdownx.tabbed, attr_list）
• nav 导航配置
• site_name 站点名称

如需自动应用修复，添加 --apply 参数。

示例：

# 仅检查
python skills/mkdocs-shadcn/scripts/check_config.py ./my-project

# 检查并自动修复
python skills/mkdocs-shadcn/scripts/check_config.py ./my-project --apply

失败处理：

• 如果脚本不存在 → 检查 <mkdocs-shadcn-path>/scripts/ 目录是否完整，重新下载或克隆仓库
• 如果 Python 未安装 → 提示用户安装 Python 3.8+，或使用系统包管理器安装
• 如果 YAML 解析失败 → 检查 mkdocs.yml 语法是否正确，使用在线 YAML 验证器
• 如果 --apply 后配置未生效 → 手动检查 mkdocs.yml 文件权限，确保可写

2. 智能排版内容

根据内容特征选择合适语法，进行排版：

详细语法和示例参考 syntax-guide.md 和 examples.md。

失败处理：

• 如果语法不生效 → 检查 markdown_extensions 是否包含对应扩展，参考配置文档
• 如果 Tab/Details 渲染异常 → 检查 | 两侧是否有空格，结尾是否有 ///
• 如果不确定使用哪种语法 → 参考决策流程章节或查看 examples.md

3. 格式化文档

输入：Markdown 文件或目录路径 输出：格式化后的文件，符合 mkdocs-shadcn 规范

排版内容完成后，必须运行格式化脚本：

python <mkdocs-shadcn-path>/scripts/format.py <文件或目录路径>

脚本自动处理：

• 标题分割线（H2 下方 ---，H3 上方 ---，H2 后第一个 H3 除外）

• 图片居中（统一转为 ` <img ...>

• 资源路径（assets/ 路径转为 /assets 绝对路径）

• 列表间距（统一空行规范）

失败处理：

• 如果脚本报错 → 检查文件编码是否为 UTF-8
• 如果格式化后内容异常 → 使用 git diff 查看具体改动，手动回滚
• 如果目录下有非 Markdown 文件 → 脚本会自动跳过，无需处理

页面模板

🔴 CHECKPOINT · 🛑 STOP：新建页面前确认使用正确的模板。

新建页面时，使用终端命令复制 assets/page-template.md 作为起点。

项目初始化时，参考 assets/mkdocs-template.yml 创建配置文件。

资源文件速查

决策流程

🔴 CHECKPOINT · 🛑 STOP：排版前确认内容类型，选择正确的语法。不确定时参考 examples.md。

内容是否需要折叠？
├── 是 → /// details
│   └── FAQ 形式？→ 标题用 ❓ 开头
│
内容是否有多个互斥选项？
├── 是 → /// tab
│   └── 按平台/方式/工具分类
│
内容是否需要突出强调？
├── 是 → !!! tip/note/warning/danger
│
└── 默认 → 直接展示

🔴 CHECKPOINT · 🛑 STOP：排版完成后必须运行格式化脚本，不要跳过。

反例清单（不要做什么）

排版反例

配置反例

内容反例