⚡

Markdown文档处理器 markdown-processor

Markdown文档处理器是一款专业的文档处理工具，专门用于解析、渲染、验证和转换Markdown与MDX格式的技术文档。支持自动生成目录、链接验证、前置元数据处理、图表嵌入（Mermaid/PlantUML）和多种格式转换（HTML/PDF/DOCX等）。适用于技术文档编写、API文档生成、架构设计文档、开发文档管理等场景，提升文档质量和维护效率。关键词：Markdown处理，MDX解析，文档自动化，技术文档，目录生成，链接验证，图表嵌入，文档转换，开发文档工具。

前端开发 0 次安装 0 次浏览 更新于 2/26/2026

name: markdown-processor description: 专门用于处理Markdown和MDX文档的专业技能。支持解析、渲染、目录生成、链接验证、前置元数据处理和图表嵌入。 allowed-tools: Bash(*) Read Write Edit Glob Grep WebFetch metadata: author: babysitter-sdk version: “1.0.0” category: documentation backlog-id: SK-SA-004

markdown-processor

你是 markdown-processor - 一个专门用于处理Markdown和MDX文档的专业技能。此技能支持在所有架构文档工作流中进行AI驱动的文档处理和验证。

概述

此技能支持全面的Markdown/MDX处理，包括：

  • 使用扩展语法解析和渲染Markdown/MDX
  • 生成和更新目录
  • 验证内部和外部链接
  • 处理和验证前置元数据（YAML/TOML）
  • 嵌入和验证图表（Mermaid, PlantUML）
  • 格式转换（Markdown转HTML、PDF等）

先决条件

  • Node.js（v18+）用于工具链
  • 可选：remark、unified、markdown-it、mdx-js

能力

1. Markdown解析与抽象语法树

将Markdown解析为AST以进行操作：

// 使用remark
import { remark } from 'remark';
import remarkParse from 'remark-parse';
import remarkStringify from 'remark-stringify';

const processor = remark()
  .use(remarkParse)
  .use(remarkStringify);

const ast = processor.parse(`
# 文档标题

这是一个包含**粗体**和*斜体*文本的段落。

## 章节

- 列表项 1
- 列表项 2
`);

// AST操作示例
function transformHeadings(tree) {
  visit(tree, 'heading', (node) => {
    if (node.depth === 1) {
      // 为h1添加锚点
      node.children = [{
        type: 'link',
        url: `#${slugify(toString(node))}`,
        children: node.children
      }];
    }
  });
}

2. 目录生成

生成并插入目录：

<!-- 原始文档 -->
# 文档标题

## 简介

内容在这里...

## 架构

### 系统概述

内容在这里...

### 组件

内容在这里...

## 结论

内容在这里...

---

<!-- 生成的目录 -->
## 目录

- [简介](#简介)
- [架构](#架构)
  - [系统概述](#系统概述)
  - [组件](#组件)
- [结论](#结论)

3. 前置元数据处理

解析和验证YAML/TOML前置元数据：

---
title: 架构概述
author: 张三
date: 2026-01-24
tags: [架构, 文档]
status: draft
custom:
  reviewers: [李四, 王五]
  category: technical
---

# 架构概述

文档内容...

// 前置元数据模式验证
const frontmatterSchema = {
  type: 'object',
  required: ['title', 'date'],
  properties: {
    title: { type: 'string', maxLength: 100 },
    author: { type: 'string' },
    date: { type: 'string', format: 'date' },
    tags: { type: 'array', items: { type: 'string' } },
    status: { type: 'string', enum: ['draft', 'review', 'published'] }
  }
};

4. 链接验证

验证内部和外部链接：

// 链接验证报告
const validationReport = {
  totalLinks: 45,
  internal: {
    valid: 30,
    broken: 2,
    details: [
      { file: 'overview.md', link: './api.md', status: 'valid' },
      { file: 'setup.md', link: './missing.md', status: 'broken' }
    ]
  },
  external: {
    valid: 10,
    broken: 1,
    skipped: 2,
    details: [
      { file: 'resources.md', link: 'https://example.com', status: 'valid' },
      { file: 'references.md', link: 'https://dead-link.com', status: 'broken', error: '404' }
    ]
  },
  anchors: {
    valid: 20,
    broken: 1,
    details: [
      { file: 'guide.md', anchor: '#installation', status: 'broken' }
    ]
  }
};

5. 图表嵌入

嵌入和验证图表：

# 系统架构

## C4上下文图

```mermaid
C4Context
    title 系统上下文图

    Person(user, "用户", "系统的使用者")
    System(system, "我们的系统", "主系统")
    System_Ext(ext, "外部服务", "第三方服务")

    Rel(user, system, "使用")
    Rel(system, ext, "调用")
```

## 序列图

```plantuml
@startuml
participant 用户
participant 系统
participant 数据库

用户 -> 系统: 请求
系统 -> 数据库: 查询
数据库 --> 系统: 结果
系统 --> 用户: 响应
@enduml
```

6. MDX处理

使用React组件处理MDX：

---
title: 交互式文档
---

import { CodeBlock, Alert, Tabs } from '@components';

# 交互式指南

<Alert type="info">
  这是一个交互式文档页面。
</Alert>

## 代码示例

<Tabs>
  <Tab label="JavaScript">
    ```javascript
    const hello = () => console.log('Hello');
    ```
  </Tab>
  <Tab label="Python">
    ```python
    def hello():
        print('Hello')
    ```
  </Tab>
</Tabs>

## API参考

<CodeBlock
  language="typescript"
  live={true}
  code={`
    interface User {
      id: string;
      name: string;
    }
  `}
/>

7. 格式转换

将Markdown转换为其他格式：

# Markdown转HTML
pandoc input.md -o output.html

# Markdown转PDF
pandoc input.md -o output.pdf --pdf-engine=xelatex

# Markdown转DOCX
pandoc input.md -o output.docx

# Markdown转RST
pandoc input.md -o output.rst -t rst

MCP服务器集成

此技能是基础性的，可与以下服务器集成：

服务器 描述 用途
所有文档MCP服务器 Markdown是通用输出格式 渲染和验证

最佳实践

文档结构

# 文档标题

> 简要描述或摘要

## 目录

<!-- toc -->

## 简介

概述和背景...

## 主要内容

### 子章节 1

内容...

### 子章节 2

内容...

## 结论

总结和后续步骤...

## 参考文献

- [参考文献 1](url)
- [参考文献 2](url)

## 附录

附加信息...

Markdown风格指南

style_rules:
  headings:
    - "使用ATX风格的标题（#）"
    - "每个文档只有一个H1标题"
    - "不要跳过标题层级"

  lists:
    - "使用 - 表示无序列表"
    - "使用 1. 表示有序列表"
    - "使用2个空格缩进"

  code:
    - "使用带语言标识的代码块"
    - "使用行内代码表示短引用"

  links:
    - "对重复的URL使用引用式链接"
    - "添加有意义的链接文本"

  images:
    - "始终包含替代文本"
    - "对本地图片使用相对路径"

可访问性

<!-- 良好：描述性替代文本 -->
![显示微服务连接的系统架构图](./architecture.png)

<!-- 良好：描述性链接文本 -->
查看[安装指南](./install.md)获取设置说明。

<!-- 不良：非描述性 -->
点击[这里](./install.md)。

流程集成

此技能与所有文档生成流程集成：

  • c4-model-documentation.js - 架构文档
  • adr-documentation.js - 决策记录
  • api-design-specification.js - API文档
  • 所有其他文档流程

输出格式

处理文档时，提供结构化输出：

{
  "operation": "process",
  "status": "success",
  "document": {
    "path": "./docs/architecture.md",
    "title": "架构概述",
    "wordCount": 1234,
    "headings": 15,
    "codeBlocks": 8,
    "diagrams": 3
  },
  "toc": {
    "generated": true,
    "items": 12,
    "maxDepth": 3
  },
  "links": {
    "total": 25,
    "internal": 18,
    "external": 7,
    "broken": 0
  },
  "frontmatter": {
    "valid": true,
    "fields": ["title", "date", "author", "tags"]
  },
  "diagrams": {
    "mermaid": 2,
    "plantuml": 1,
    "valid": true
  },
  "artifacts": ["architecture.md", "architecture.html"],
  "warnings": [
    "第45行：图片缺少替代文本"
  ],
  "errors": []
}

错误处理

常见错误

错误 原因 解决方案
无效的前置元数据 YAML语法错误 修复YAML格式
损坏的内部链接 文件未找到 更新链接或创建文件
无效的图表语法 Mermaid/PlantUML错误 修复图表语法
标题层级问题 跳过了标题层级 使用连续的标题层级

约束

  • 遵循一致的Markdown风格
  • 发布前验证所有链接
  • 包含用于元数据的前置元数据
  • 使用语义化的标题层级
  • 为图片提供替代文本