# flowy_doc_convert

**Repository Path**: git_gz_admin/flowy_doc_convert

## Basic Information

- **Project Name**: flowy_doc_convert
- **Description**: flowy_doc_convert
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-12
- **Last Updated**: 2026-02-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flowy Doc Convert

这是一个独立的 CLI 工具，用于将 Markdown 格式的文本转换为 AppFlowy 兼容的 Document JSON 格式。

该工具使用 Go 语言编写，支持跨平台运行（Linux, macOS, Windows），专为服务器端或非 Flutter 环境下的文档转换需求设计。

## 功能特性

支持以下 Markdown 语法的解析与转换：

*   **基础块级元素**:
    *   标题 (Heading H1-H6)
    *   段落 (Paragraph)
    *   引用 (Blockquote)
    *   无序列表 (Bulleted List)
    *   有序列表 (Numbered List)
    *   代码块 (Code Block，支持语言标识)
    *   水平分割线 (Divider)
*   **行内样式**:
    *   加粗 (**Bold**)
    *   斜体 (*Italic*)
    *   行内代码 (`Inline Code`)
    *   超链接 ([Link](url))
*   **扩展支持**:
    *   **任务列表 (Todo List)**: 支持 `[ ]` 和 `[x]` 语法
    *   **数学公式**:
        *   块级公式: `$$ E=mc^2 $$`
        *   行内公式: `$ E=mc^2 $`
    *   **表格**: 支持 GFM 标准表格
    *   **图片**: 独占一行的图片语法 `![alt](url)` 会转换为 Image Block

## 编译与安装

确保您的环境中已安装 Go (1.18+)。

```bash
# 进入项目目录
cd flowy_doc_convert

# 编译
go build -o flowy-convert main.go

# (可选) 移动到系统路径
# mv flowy-convert /usr/local/bin/
```

## 使用方法

### 1. 从文件读取

```bash
./flowy-convert input.md
```

### 2. 从标准输入读取 (Stdin)

```bash
echo "# Hello World" | ./flowy-convert
```

### 3. 直接通过参数传递字符串

支持通过 `-i` 参数直接传递 Markdown 字符串。支持使用 `\n` 进行换行。

```bash
./flowy-convert -i "# Title\n\n- Item 1\n- Item 2"
```

## 输出格式

工具会将转换结果输出为标准的 JSON 字符串至 `stdout`。

**示例输入**:
```markdown
# Hello
- [x] Task
```

**示例输出**:
```json
{
  "document": {
    "type": "page",
    "id": "R4nD0m",
    "children": [
      {
        "type": "heading",
        "id": "k8L1vP",
        "data": {
          "delta": [ { "insert": "Hello" } ],
          "level": 1
        }
      },
      {
        "type": "todo_list",
        "id": "j9M3nQ",
        "attributes": { "checked": true },
        "data": {
          "delta": [ { "insert": "Task" } ]
        }
      }
    ]
  }
}
```

## 集成指南

### 在 Node.js 中调用

```javascript
const { execFile } = require('child_process');

const markdown = "# Title\n\nContent";

execFile('./flowy-convert', ['-i', markdown], (error, stdout, stderr) => {
  if (error) {
    console.error('转换失败:', stderr);
    return;
  }
  const document = JSON.parse(stdout);
  console.log(document);
});
```

### 在 Python 中调用

```python
import subprocess
import json

markdown = "# Title\n\nContent"

result = subprocess.run(
    ['./flowy-convert', '-i', markdown],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    document = json.loads(result.stdout)
    print(document)
else:
    print("Error:", result.stderr)
```

## 作为 Go SDK 集成

如果您需要在现有的 Go 工程中直接调用转换功能，而不是通过 CLI，可以按照以下步骤操作。

### 1. 引入依赖

在您的 `go.mod` 文件中添加本项目依赖：

```bash
go get gitee.com/git_gz_admin/flowy_doc_convert
```

或者如果是本地模块，可以使用 `replace` 指令：

```go
replace gitee.com/git_gz_admin/flowy_doc_convert => /path/to/local/flowy_doc_convert
```

### 2. 代码调用示例

```go
package main

import (
    "fmt"
    "log"
    
    // 引入转换器包
    "gitee.com/git_gz_admin/flowy_doc_convert/converter"
    // 引入数据模型包 (如果需要处理结构体)
    "gitee.com/git_gz_admin/flowy_doc_convert/model"
)

func main() {
    markdown := "# Hello SDK\n\nThis is a programmatic usage."
    
    // 1. 调用核心转换函数
    // MarkdownToDocument 接收 []byte 并返回 *model.Document
    doc, err := converter.MarkdownToDocument([]byte(markdown))
    if err != nil {
        log.Fatalf("转换失败: %v", err)
    }
    
    // 2. 获取 JSON 字符串
    jsonStr, err := doc.ToJSON()
    if err != nil {
        log.Fatalf("JSON 序列化失败: %v", err)
    }
    
    fmt.Println(jsonStr)
    
    // 3. 或者直接操作 Document 结构体
    fmt.Printf("Document ID: %s\n", doc.Document.ID)
    fmt.Printf("Child Count: %d\n", len(doc.Document.Children))
}
```

### 3. 包结构说明

*   `flowy_doc_convert/converter`: 包含核心转换逻辑 `MarkdownToDocument`。
*   `flowy_doc_convert/model`: 包含 AppFlowy 的数据结构定义 (`Document`, `Node`, `Op` 等)。

## 开发与贡献

*   **依赖管理**: 使用 `go mod tidy` 更新依赖。
*   **核心逻辑**: 位于 `converter/markdown.go`，基于 `goldmark` 库实现 AST 遍历与转换。
*   **数据模型**: 位于 `model/document.go`，对应 AppFlowy 的 Document/Node/Delta 结构。