| name | mkdocs-shadcn |
| description | mkdocs-shadcn 主题 Markdown 排版与项目编排。当用户需要编写或修改 mkdocs-shadcn 主题的文档、配置 mkdocs.yml、或询问排版语法时，使用此技能。触发词：mkdocs、shadcn、排版、配置、Markdown、文档、admonition、details、tab、提示框、折叠、标签页、格式化、模板。 |
mkdocs-shadcn 主题排版技能
目录
- 工作流程
- 页面模板
- 资源文件速查
- 决策流程
- 反例清单
工作流程（每次运行技能时必须运行该工作流程中的所有步骤）
🔴 CHECKPOINT · 🛑 STOP：开始前确认项目目录和 mkdocs.yml 路径正确。
1. 检查项目配置
输入：项目目录路径
输出：配置检查报告，列出问题和建议修复
运行配置检查脚本：
python <mkdocs-shadcn-path>/scripts/check_config.py <项目目录> [--apply]
脚本会自动检查并补充：
theme.name 是否为 shadcnplugins 是否包含必要插件（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. 智能排版内容
根据内容特征选择合适语法，进行排版：
| 内容特征 | 选择语法 | 示例 |
|---|
| 内容较长，非必需阅读 | /// details | /// details | 📖 点击查看详细配置 |
| 问答形式的 FAQ | /// details | ❓ 问题 | /// details | ❓ 什么是 XXX？ |
| 多平台/互斥选项 | /// tab | /// tab | Windows / /// tab | macOS |
| 技巧、建议 | !!! tip | !!! tip "最佳实践" |
| 警告、风险 | !!! warning/danger | !!! warning "安全提示" |
| 补充说明 | !!! note/info | !!! note "说明" |
详细语法和示例参考 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 创建配置文件。
资源文件速查
| 路径 | 用途 | 使用场景 | 依赖 |
|---|
scripts/check_config.py | 检查并补充 mkdocs.yml 配置 | 项目初始化、配置检查 | Python 3.8+, PyYAML |
scripts/format.py | 格式化 Markdown 文件 | 排版完成后、提交前 | Python 3.8+ |
assets/page-template.md | 页面模板 | 新建页面时复制使用 | 无 |
assets/mkdocs-template.yml | mkdocs.yml 配置模板 | 项目初始化时参考 | 无 |
references/syntax-guide.md | 完整语法手册 | 查询语法细节 | 无 |
references/examples.md | 排版示例 | 参考排版实践 | 无 |
references/configuration.md | 项目配置参考 | 配置 mkdocs.yml | 无 |
决策流程
🔴 CHECKPOINT · 🛑 STOP：排版前确认内容类型，选择正确的语法。不确定时参考 examples.md。
内容是否需要折叠？
├── 是 → /// details
│ └── FAQ 形式？→ 标题用 ❓ 开头
│
内容是否有多个互斥选项？
├── 是 → /// tab
│ └── 按平台/方式/工具分类
│
内容是否需要突出强调？
├── 是 → !!! tip/note/warning/danger
│
└── 默认 → 直接展示
🔴 CHECKPOINT · 🛑 STOP：排版完成后必须运行格式化脚本，不要跳过。
反例清单（不要做什么）
排版反例
| # | 反模式 | 为什么不要做 | 替代做法 |
|---|
| 1 | 滥用 /// details 折叠重要内容 | 关键信息被隐藏，用户可能错过 | 核心概念、关键步骤直接展示，仅折叠可选阅读内容 |
| 2 | 使用 !!! warning 强调所有内容 | 警告框失去警示效果，用户产生视觉疲劳 | 区分 tip/note/warning/danger，按严重程度选择 |
| 3 | Tab 标签页内放有依赖关系的内容 | 用户可能跳过前置步骤直接看后续内容 | 有依赖关系的内容使用顺序列表，不要 Tab |
| 4 | H2/H3 标题后不加 --- 分割线 | 章节之间视觉分隔不清晰 | 严格遵循格式化脚本的标题分割线规则 |
| 5 | 图片使用相对路径 ./assets/... | 不同页面层级下路径可能失效 | 使用 /assets/... 绝对路径 |
| 6 | 列表项之间留空行 | 列表间距不一致，影响阅读流畅性 | 同一组列表的列表项之间不留空行 |
配置反例
| # | 反模式 | 为什么不要做 | 替代做法 |
|---|
| 1 | 缺少 pymdownx.blocks.details 扩展 | /// details 语法无法渲染 | 确保 markdown_extensions 包含所有必需扩展 |
| 2 | theme.name 设置为非 shadcn | 主题样式不生效 | 必须设置为 shadcn |
| 3 | 不运行格式化脚本直接提交 | 标题分割线、图片居中等格式不统一 | 每次排版后必须运行 format.py |
内容反例
| # | 反模式 | 为什么不要做 | 替代做法 |
|---|
| 1 | 在 Tab 中放完全相同的重复内容 | 浪费空间，没有实际价值 | 每个 Tab 展示有差异的内容（如不同平台的命令） |
| 2 | Details 标题写"点击查看详情" | 标题无信息量，用户不知道内容是什么 | 使用具体描述：❓ 什么是 XXX？ 或 📖 XXX 配置说明 |
| 3 | Warning 框内写长篇大论 | 警告框应该简短有力 | 长内容放在正文中，Warning 只保留关键警示 |
| 4 | 在代码块中放配置文件路径 | 路径容易出错，且不易维护 | 使用相对路径或变量，避免硬编码 |
| 5 | 使用过时的语法或插件 | 可能导致兼容性问题 | 参考最新的官方文档，使用推荐的语法 |
| 6 | 在 Details 中放核心概念 | 用户可能错过关键信息 | 核心概念直接展示，仅折叠可选阅读内容 |
