yuque

Yuque Plugin for html-to-markdown

语雀编辑器 HTML 转 Markdown 插件

功能

• ✅ 转换语雀代码块 (<card name="codeblock">) 为 Markdown 代码块
• ✅ 转换语雀图片 (<card name="image">) 为 Markdown 图片
• ✅ 转换语雀分隔线 (<card name="hr">) 为 Markdown 分隔线
• ✅ 转换语雀复选框 (<card name="checkbox">) 为任务列表格式
• ✅ 转换语雀公式 (<card name="math">) 为 LaTeX 公式
• ✅ 转换语雀表格 (<table class="lake-table">) 为 Markdown 表格（支持对齐）
• ✅ 处理语雀嵌套列表 (data-lake-indent 属性)
• ✅ 保留代码格式（换行、缩进、空格）
• ✅ 支持多种编程语言语法高亮
• ✅ 兼容模式：只处理语雀特有标签

安装

# 直接安装带语雀插件的版本
go get github.com/lintstar/html-to-markdown/v2@main

快速开始

在代码中使用

package main

import (
    "fmt"
    "log"
    
    // 使用 lintstar 的 fork（包含语雀插件）
    "github.com/lintstar/html-to-markdown/v2/converter"
    "github.com/lintstar/html-to-markdown/v2/plugin/base"
    "github.com/lintstar/html-to-markdown/v2/plugin/commonmark"
    "github.com/lintstar/html-to-markdown/v2/plugin/yuque"
)

func main() {
    html := `<card type="inline" name="codeblock" 
             value="data:%7B%22mode%22%3A%22python%22%2C%22code%22%3A%22print(%5C%22Hello%5C%22)%22%7D">
             </card>`
    
    conv := converter.NewConverter(
        converter.WithPlugins(
            base.NewBasePlugin(),
            commonmark.NewCommonmarkPlugin(),
            yuque.NewYuquePlugin(),
        ),
    )
    
    markdown, err := conv.ConvertString(html)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(markdown)
}

命令行工具

cd examples/yuque
go run main.go input.html output.md

转换示例

代码块

语雀 HTML：

<card type="inline" name="codeblock" 
      value="data:%7B%22mode%22%3A%22python%22%2C%22code%22%3A%22def%20hello()%3A%5Cn%20%20print(%5C%22Hello%5C%22)%22%7D">
</card>

Markdown 输出：

```python
def hello():
  print("Hello")
```

图片

语雀 HTML：

<card type="inline" name="image"
      value="data:%7B%22src%22%3A%22https%3A//example.com/img.png%22%2C%22title%22%3A%22Logo%22%7D">
</card>

Markdown 输出：

![Logo](https://example.com/img.png)

公式

语雀 HTML：

<card type="inline" name="math" 
      value="data:%7B%22code%22%3A%22E%20%3D%20mc%5E2%22%7D">
</card>

Markdown 输出：

$E = mc^2$

复选框/任务列表

语雀 HTML：

<ul class="lake-list">
  <li class="lake-list-task">
    <card type="inline" name="checkbox" value="data:false"></card>
    <span>待办事项</span>
  </li>
  <li class="lake-list-task">
    <card type="inline" name="checkbox" value="data:true"></card>
    <span>已完成</span>
  </li>
</ul>

Markdown 输出：

- [ ] 待办事项
- [x] 已完成

表格（带对齐）

语雀 HTML：

<table class="lake-table">
  <tbody>
    <tr>
      <td><p style="text-align: left">左对齐</p></td>
      <td><p style="text-align: center">居中</p></td>
      <td><p style="text-align: right">右对齐</p></td>
    </tr>
  </tbody>
</table>

Markdown 输出：

| 左对齐 | 居中 | 右对齐 |
| :--- | :---: | ---: |

支持的语雀元素

技术实现

工作原理

1. 检测 <card> 标签并识别 name 属性
2. URL 解码 value 属性（从 data:%7B... 解码为 JSON）
3. 解析 JSON 提取关键字段
4. 生成标准 Markdown 格式

兼容性

• ✅ 只处理语雀特有的 <card> 标签和 lake-table
• ✅ 不影响其他 HTML 标签的转换
• ✅ 错误安全处理，解析失败会跳过

测试

# 运行单元测试
cd plugin/yuque
go test -v

# 测试转换
cd examples/yuque
go run main.go TEST.md output.md

项目结构

plugin/yuque/
├── yuque.go          # 插件实现
├── yuque_test.go     # 单元测试
└── README.md         # 本文档

examples/yuque/
├── main.go           # 命令行工具
└── complex_test.html # 测试文件

常见问题

Q: 如何在我的项目中使用？

go get github.com/lintstar/html-to-markdown/v2@main

import "github.com/lintstar/html-to-markdown/v2/plugin/yuque"

Q: 支持哪些语雀元素？

• ✅ 代码块（所有编程语言，自动检测 Mermaid）
• ✅ 图片（带标题和 alt 文本转义）
• ✅ 分隔线
• ✅ 复选框/任务列表
• ✅ 公式（LaTeX 格式）
• ✅ 表格（支持对齐）
• ✅ 嵌套列表

Q: 代码格式会丢失吗？

不会！插件完整保留换行符、缩进和空格。

Q: 如何扩展支持更多 card 类型？

编辑 yuque.go，在 renderCard 函数中添加新的 case：

switch cardName {
case "codeblock":
    return y.renderCodeBlock(ctx, w, decodedData)
case "image":
    return y.renderImage(ctx, w, decodedData)
case "file":  // 新增
    return y.renderFile(ctx, w, decodedData)
}

相关链接

• GitHub 仓库
• 原始项目