Communitygithub.com

abertanha/md-to-wiki-docs-skills

将 Markdown 规范文件转换为文档站点。

md-to-wiki-docs-skills 是什么?

该技能可以将 Markdown 规范文件转换为多种格式的文档站点,例如 MkDocs Material 站点、OpenAPI/Swagger UI、GitHub Wiki、DokuWiki 和 PDF 书籍。它通过一个智能的路由系统根据用户意图(如“build wiki”或“generate docs”)自动选择合适的处理路径,并支持从多个源目录合并输入。技能还提供引用增强(GitHub Issue/PR 引用)和部署选项,让开发者能高效地创建、丰富和发布技术文档。此技能设计用于 Open Interpreter、OpenCode 等兼容的 AI 代理平台。

兼容平台~Claude Code~Codex CLI~Cursor✓OpenCode
npx skills add abertanha/md-to-wiki-docs-skills

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

md-to-wiki — 轻量路由器(阶段 2)

将 Markdown 规范文件转换为文档站点。

触发词: "build wiki", "generate docs", "publish specs", "make a site", "wiki from markdown", "draw diagram", "flow chart", "architecture diagram", "state diagram", "sequence diagram"

阶段路由器

分析用户请求以确定要采取哪条路径:

lower=$(echo "$1" | tr '[:upper:]' '[:lower:]')
case "$lower" in
  *"not sure"*|*"help"*|*"recommend"*)     ROUTE="onboarding" ;;
  *"html"*|*"site"*|*"mkdocs"*|*"material"*)  ROUTE="mkdocs" ;;
  *"swagger"*|*"openapi"*|*"api"*)          ROUTE="swagger" ;;
  *"github wiki"*|*"wiki tab"*)             ROUTE="github-wiki" ;;
  *"dokuwiki"*|*"doku"*)                    ROUTE="dokuwiki" ;;
  *"pdf"*|*"print"*|*"book"*)               ROUTE="pdf" ;;
  *"reference"*|*"issue"*|*"pr"*|*"pull"*)  ROUTE="references" ;;
  *"deploy"*|*"publish"*|*"go live"*)       ROUTE="deploy" ;;
  *)                                          ROUTE="onboarding" ;;
esac

然后启动相应的代理:

路由代理描述
onboardingagents/onboarding.md与用户对话,检测操作系统,设置 SKILL_DIR
mkdocsagents/format-mkdocs.md生成 MkDocs Material 站点
swaggeragents/format-swagger.md生成 OpenAPI 3.0 + Swagger UI
github-wikiagents/format-github-wiki.md发布到 GitHub Wiki
dokuwikiagents/format-dokuwiki.md转换为 DokuWiki 格式
pdfagents/format-pdf.md通过 Pandoc 生成 PDF
referencesagents/references.md用 GitHub Issue/PR 引用丰富文档
deployagents/deploy.md将生成的文档部署到托管平台

执行流程

  1. 入导 → 询问问题:项目名称、源目录、受众(开发者/利益相关者/普通用户)、期望格式。一旦检测到操作系统,存储 SKILL_DIR、SCRIPT_EXT、SCRIPT_RUNNER。
  2. 格式生成 → 加载相应的格式代理。使用 $SCRIPT_RUNNER 从 scripts/ 目录调用配套脚本。
  3. 引用 → 如果用户需要 Issue/PR 引用,加载 references.md。
  4. 部署 → 生成完成后,加载 deploy.md 提供托管选项。

全局变量(入导阶段设置一次)

  • SKILL_DIR — 解析到此技能文件夹的路径
  • SCRIPT_EXT — .sh 或 .ps1
  • SCRIPT_RUNNER — "" 或 "powershell -File"
  • OS_TYPE — unix 或 windows
  • PROJECT_NAME — 来自用户
  • SOURCES — 规范文件路径
  • AUDIENCE — developer、stakeholder 或 general

配套脚本

所有脚本在 .sh 和 .ps1 版本中都以相同方式接受位置参数:

脚本用途
discover-sources扫描目录查找规范/项目/代码库/快速文件
generate-mkdocs创建完整的 mkdocs.yml + 页面结构
generate-index构建适合受众的登录页面
to-dokuwiki将 markdown 转换为 DokuWiki 语法
to-pdf合并并通过 pandoc 转换为 PDF
fetch-issues缓存 GitHub Issue/PR 元数据

多目录输入

在运行前将多个源目录合并到 merged-specs/:

mkdir -p merged-specs && cp -r .specs/* docs/* merged-specs/

共享

将 md-to-wiki/ 复制到同事的 .config/opencode/skills/ 或 .opencode/skills/ 目录。依赖项因格式而异。

相关技能