name: markdown-mdx description: 用于技术文档的高级Markdown和MDX处理。解析、验证、检查和转换Markdown内容，支持MDX组件、Front Matter和remark/rehype插件。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-005 metadata: author: babysitter-sdk version: “1.0.0”

Markdown/MDX 技能

用于技术文档的高级Markdown和MDX处理。

能力

解析和验证Markdown语法（CommonMark，GFM）
MDX组件开发和集成
配置remark/rehype插件
解析和验证Front Matter
Markdown代码检查（markdownlint规则）
表格格式化和生成
链接验证和URL检查
在文档格式之间转换

用法

当您需要时，调用此技能：

检查和验证Markdown文件
创建或集成MDX组件
配置remark/rehype处理管道
验证Front Matter模式
在文档格式之间转换

输入

参数	类型	必填	描述
inputPath	string	是	Markdown/MDX文件或目录的路径
action	string	是	lint, validate, transform, parse-frontmatter
outputPath	string	否	转换后内容的输出路径
configPath	string	否	markdownlint配置的路径
frontmatterSchema	object	否	用于Front Matter验证的JSON模式
plugins	array	否	要应用的remark/rehype插件

输入示例

{
  "inputPath": "./docs",
  "action": "lint",
  "configPath": ".markdownlint.json"
}

输出结构

检查输出

{
  "files": 42,
  "errors": 5,
  "warnings": 12,
  "issues": [
    {
      "file": "docs/getting-started.md",
      "line": 15,
      "rule": "MD022",
      "message": "标题周围应有空行",
      "severity": "error"
    }
  ],
  "fixable": 8
}

Front Matter 解析输出

{
  "file": "docs/api/users.md",
  "frontmatter": {
    "title": "Users API",
    "description": "用户管理端点",
    "tags": ["api", "users"],
    "sidebar_position": 3
  },
  "valid": true,
  "content": "# Users API

本文档..."
}

Markdown 模式

CommonMark 扩展

# 标题 1

## 标题 2 {#custom-id}

段落包含 **粗体**、*斜体* 和 `代码`。

> 多行
> 引用块

- 无序列表
- 包含项目
  - 嵌套项目

1. 有序列表
2. 带数字

| 列 1 | 列 2 |
|----------|----------|
| 单元格 1   | 单元格 2   |

[链接文本](https://example.com "标题")

![替代文本](image.png)

```javascript
const code = '块';

上面的水平线。


### GitHub Flavored Markdown (GFM)

```markdown
## GFM 扩展

### 任务列表
- [x] 已完成任务
- [ ] 未完成任务

### 表格
| 左对齐 | 居中 | 右对齐 |
|:-----|:------:|------:|
| L    |   C    |     R |

### 删除线
~~已删除文本~~

### 自动链接
https://example.com

### 脚注
这是一个带有脚注的句子[^1]。

[^1]: 这是脚注。

### 提示
> [!NOTE]
> 有用信息。

> [!WARNING]
> 关键内容。

MDX 模式

MDX 组件

---
title: 交互式指南
---

import { Tabs, TabItem } from '@site/src/components/Tabs';
import CodeBlock from '@theme/CodeBlock';

# 入门指南

<Tabs>
  <TabItem value="npm" label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem value="yarn" label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
</Tabs>

## 配置

<CodeBlock language="json" title="config.json">
{`{
  "setting": "value"
}`}
</CodeBlock>

export const Highlight = ({children, color}) => (
  <span style={{backgroundColor: color, padding: '0.2rem'}}>
    {children}
  </span>
);

这是 <Highlight color="#25c2a0">高亮文本</Highlight>。

MDX 组件库

// components/Callout.jsx
export function Callout({ type = 'info', title, children }) {
  const styles = {
    info: { bg: '#e7f5ff', border: '#339af0' },
    warning: { bg: '#fff3bf', border: '#fab005' },
    error: { bg: '#ffe3e3', border: '#fa5252' },
    success: { bg: '#d3f9d8', border: '#40c057' }
  };

  return (
    <div style={{
      backgroundColor: styles[type].bg,
      borderLeft: `4px solid ${styles[type].border}`,
      padding: '1rem',
      margin: '1rem 0'
    }}>
      {title && <strong>{title}</strong>}
      {children}
    </div>
  );
}

import { Callout } from '@site/src/components/Callout';

<Callout type="warning" title="弃用通知">
  此API将在版本3.0中移除。
</Callout>

Markdownlint 配置

.markdownlint.json

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["details", "summary", "Tabs", "TabItem"]
  },
  "MD041": false,
  "MD024": {
    "siblings_only": true
  },
  "MD046": {
    "style": "fenced"
  },
  "MD048": {
    "style": "backtick"
  }
}

markdownlint-cli2 配置

# .markdownlint-cli2.yaml
config:
  default: true
  MD013: false

globs:
  - "docs/**/*.md"
  - "!node_modules"
  - "!.git"

ignores:
  - "CHANGELOG.md"

customRules:
  - markdownlint-rule-search-replace

Remark/Rehype 插件

remark.config.mjs

import remarkGfm from 'remark-gfm';
import remarkFrontmatter from 'remark-frontmatter';
import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
import remarkToc from 'remark-toc';
import remarkSlug from 'remark-slug';

export default {
  plugins: [
    remarkGfm,
    remarkFrontmatter,
    remarkMdxFrontmatter,
    [remarkToc, { heading: 'contents', tight: true }],
    remarkSlug
  ]
};

rehype.config.mjs

import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
import rehypePrism from 'rehype-prism-plus';

export default {
  plugins: [
    rehypeSlug,
    [rehypeAutolinkHeadings, { behavior: 'wrap' }],
    [rehypePrism, { showLineNumbers: true }]
  ]
};

Front Matter 模式

用于验证的JSON模式

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["title"],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "maxLength": 300
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "sidebar_position": {
      "type": "integer",
      "minimum": 0
    },
    "draft": {
      "type": "boolean",
      "default": false
    }
  },
  "additionalProperties": false
}

工作流程

解析内容 - 加载Markdown/MDX文件
提取Front Matter - 解析YAML Front Matter
验证结构 - 根据模式检查
检查内容 - 应用markdownlint规则
转换 - 应用remark/rehype插件
报告发现 - 输出验证结果

依赖项

{
  "devDependencies": {
    "markdownlint-cli2": "^0.12.0",
    "remark": "^15.0.0",
    "remark-gfm": "^4.0.0",
    "remark-frontmatter": "^5.0.0",
    "remark-mdx": "^3.0.0",
    "rehype": "^13.0.0",
    "gray-matter": "^4.0.0",
    "ajv": "^8.0.0"
  }
}

CLI 命令

# 检查所有Markdown文件
npx markdownlint-cli2 "docs/**/*.md"

# 修复可自动修复的问题
npx markdownlint-cli2 --fix "docs/**/*.md"

# 解析和验证Front Matter
node scripts/validate-frontmatter.js docs/

# 将Markdown转换为HTML
npx remark docs/guide.md -o build/guide.html

应用的最佳实践

使用ATX样式标题（#）
一致的列表标记（无序列表使用 -）
带有语言标识符的围栏代码块
用于元数据的Front Matter
描述性链接文本（非“点击这里”）
所有图像的替代文本
每行一个句子以获得更好的差异对比

参考

CommonMark: https://commonmark.org/
GFM: https://github.github.com/gfm/
MDX: https://mdxjs.com/
markdownlint: https://github.com/DavidAnson/markdownlint
remark: https://remark.js.org/
rehype: https://github.com/rehypejs/rehype

目标流程

style-guide-enforcement.js
docs-testing.js
docs-audit.js
content-strategy.js