使用golang开发的markdown文档的解析api工具

📝 go-markdown

一个使用 Go + fasthttp + goldmark 构建的高性能 Markdown 转 HTML API 服务。 支持 GitHub Flavored Markdown、数学公式、语法高亮、安全清理与目录（TOC）提取。 支持远程 Markdown URL 解析、请求缓存、标准 JSON 响应格式、请求 ID 与可配置超时/体积限制。

下载地址：pan.quark.cn/s/078b4a3e0…

🚀 功能特性

• ✅ 支持 GitHub Flavored Markdown (GFM)
• ✅ 支持 MathJax 数学公式（$...$ / $$...$$）
• ✅ 支持代码块语法高亮（基于 goldmark-highlighting + chroma）
• ✅ 支持安全 HTML 清理（bluemonday 过滤 XSS）
• ✅ 支持自动目录提取（TOC）
• ✅ 支持远程 Markdown URL 解析（url 字段）
• ✅ 支持 LRU + TTL + 最大项/字节缓存
• ✅ 支持跨域访问 (CORS)
• ✅ 请求返回标准 JSON 格式 { "err": ..., "data": ..., "msg": ... }
• ✅ 每个请求包含 X-Request-ID，便于追踪
• ✅ 高性能服务，基于 fasthttp 实现
• ✅ 支持可配置超时和最大请求体：--read-timeout, --write-timeout, --max-body-size

---

📦 安装与构建

1️⃣ 克隆项目

git clone https://git.local.m4m4.cn/qiaofu/go-markdown.git
cd go-markdown

2️⃣ 安装依赖

go mod tidy

3️⃣ 构建可执行文件

go build -o go-markdown main.go

4️⃣ 运行服务

./go-markdown --port 8080

可选参数：

• --read-timeout 最大接收超时（秒，默认 5）
• --write-timeout 最大发送超时（秒，默认 5）
• --max-body-size 最大请求体大小（KB，默认 5120）
• --debug 启用调试日志
• --log 打印详细 HTTP 请求信息

默认监听端口：

http://localhost:8080

---

⚙️ API 说明

📍 POST /parse — Markdown 解析

请求示例：

curl -X POST http://localhost:8080/parse \
-H "Content-Type: application/json" \
-d '{
    "markdown": "# Hello, Markdown!\n\nThis is **bold text** and $a^2+b^2=c^2$",
    "options": {
        "gfm": true,
        "math": true,
        "highlight": true,
        "unsafe": false,
        "sanitize": true,
        "toc": true
    }
}'

请求参数说明：

字段	类型	默认值	说明
markdown	string	-	Markdown 原文内容，可为空，但 url 和 markdown 不可同时为空
url	string	-	远程 Markdown 文件 URL，可为空，但 url 和 markdown 不可同时为空
options.gfm	bool	true	启用 GitHub Flavored Markdown
options.math	bool	true	启用 MathJax 公式解析
options.highlight	bool	false	启用语法高亮
options.unsafe	bool	false	允许渲染原始 HTML
options.sanitize	bool	true	输出前使用 bluemonday 过滤 XSS
options.toc	bool	true	是否提取目录（TOC）

---

响应示例：

{
    "err": 0,
    "data": {
        "html": "<h1 id="hello-markdown">Hello, Markdown!</h1><p>This is <strong>bold text</strong> and <span class="math">a^2+b^2=c^2</span></p>",
        "toc": [
            {
                "level": 1,
                "text": "Hello, Markdown!",
                "id": "hello-markdown",
                "anchor": "#hello-markdown"
            }
        ],
        "elapsed": "2"
    },
    "msg": "success"
}

响应字段说明：

字段	类型	说明
err	int	错误码，0 表示成功
data	object	包含解析结果
data.html	string	转换后的 HTML 字符串
data.toc	array	目录列表（每个包含标题文本、级别和锚点）
data.elapsed	string	处理耗时（毫秒）
data.errors	array	解析或渲染错误（可选）
msg	string	状态信息

---

📍 GET /health — 健康检查

示例：

curl http://localhost:8080/health

返回：

{
    "err": 0,
    "data": {
        "status": "ok",
        "uptime_ms": 12345,
        "start_at": "2025-10-29T14:00:00Z"
    },
    "msg": "success"
}

字段说明：

字段	类型	说明
data.status	string	服务状态
data.uptime_ms	string	启动至今耗时
data.start_at	string	服务启动时间（UTC）

---

🧩 TOC 提取逻辑

• 自动遍历 Markdown AST 中的标题节点（Heading）
• 自动生成 ID（与 goldmark 的 AutoHeadingID 一致）
• 支持中英文标题混排
• 格式示例：

[
    {
        "level": 1,
        "text": "简介",
        "id": "简介",
        "anchor": "#简介"
    },
    {
        "level": 2,
        "text": "安装",
        "id": "安装",
        "anchor": "#安装"
    }
]

---

🔒 安全策略

• 默认启用 XSS 防御（bluemonday.UGCPolicy）
• 允许：
• <span class="math"> 用于 MathJax
• <script type="math/tex">
• 标题标签的 id 属性
• Data URI 图片（Base64 图像）

---

🧠 技术栈

模块	功能
fasthttp	高性能 HTTP 服务
goldmark	Markdown 解析
goldmark-highlighting	代码语法高亮
mathjax	数学公式支持
bluemonday	HTML 安全过滤
chroma	代码高亮后端

---

🧪 性能表现

• 基于 fasthttp，相比标准 net/http 平均提升 30~50% 请求吞吐
• 适合嵌入 Markdown 预览器、静态网站生成器或 SaaS 文档系统

---

🧾 License

MIT License Copyright © 2025