# excel2md

**Repository Path**: liudc0810/excel2md

## Basic Information

- **Project Name**: excel2md
- **Description**: excel文档转md格式，go语言实现。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# excel2md v2.0.0 — Excel/CSV 转 Markdown 表格工具

从 Excel、CSV 文件中提取表格，输出为 Markdown、CSV 或 JSON 格式。

## 安装

```bash
git clone <repo-url>
cd excel2md
go build -o excel2md.exe .
```

## 快速开始

```bash
excel2md -input data.xlsx                    # Excel → Markdown
excel2md -input data.csv -of markdown        # CSV → Markdown
excel2md -input data.xlsx -of json           # Excel → JSON
```

## 使用示例

### 基本转换

```bash
excel2md -input data.xlsx                    # 自动检测输出格式
excel2md -input data.xlsx -of markdown       # 指定输出 Markdown
excel2md -input data.xlsx -of csv            # 指定输出 CSV
excel2md -input data.xlsx -of json           # 指定输出 JSON
```

### 批量转换

```bash
excel2md -input *.xlsx                       # 批量处理
excel2md -input data/*.xlsx -of csv          # 批量转 CSV
excel2md -input data/*.xlsx -of markdown -j 4 # 4 并发处理
```

### stdin/stdout 管道

```bash
cat data.csv | excel2md -input - -of markdown    # stdin → stdout
cat data.xlsx | excel2md -input - -if excel -of json  # 管道处理
excel2md -input data.xlsx -of markdown -output -      # 输出到 stdout
```

### 数据处理

```bash
excel2md -input data.xlsx -of markdown -sheet "汇总"      # 自定义工作表名
excel2md -input data.xlsx -of markdown -all-in-one         # 合并所有表格
excel2md -input data.xlsx -of markdown -disable-num-detect # 禁用数字检测
excel2md -input data.xlsx -of markdown -transform filter,sort,dedup # 应用变换
excel2md -input data.xlsx -of markdown -transform "sort:1:desc"     # 按第2列降序排序
excel2md -input data.xlsx -of markdown -transform "dedup:0"         # 按第1列去重
```

### 查看信息

```bash
excel2md -version                                   # 显示版本
excel2md -list-plugins                              # 列出所有插件
excel2md -help                                      # 帮助信息
excel2md -input data.xlsx -of markdown -q           # 静默模式（不显示进度）
```

## 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-input <path>` | 输入文件路径（支持通配符 `*.xlsx`；`-` 表示 stdin） | 必填 |
| `-output <path>` | 输出文件路径（`-` 表示 stdout） | 自动 |
| `-if <format>` | 输入格式：excel, csv | 自动检测 |
| `-of <format>` | 输出格式：markdown, csv, json | 自动检测 |
| `-sheet <name>` | 自定义工作表名（仅 Excel 输入） | - |
| `-all-in-one` | 所有表格合并到同一文件 | false |
| `-disable-num-detect` | 禁用数字自动检测 | false |
| `-transform <list>` | 应用的变换插件（支持参数如 `sort:1:desc,dedup:0`） | normalize |
| `-j <num>` | 并发处理数（0=CPU核心数） | 1 |
| `-version` | 显示版本信息 | - |
| `-list-plugins` | 列出所有可用插件 | - |
| `-q` | 静默模式（不显示进度） | false |

## 格式支持

### 输入格式

| 格式 | 扩展名 | 说明 |
|------|--------|------|
| Excel | `.xlsx`, `.xls` | 支持多 Sheet、合并单元格 |
| CSV | `.csv`, `.tsv` | 自动检测逗号/制表符分隔 |

### 输出格式

| 格式 | 扩展名 | 说明 |
|------|--------|------|
| Markdown | `.md` | 标准 Markdown 表格格式 |
| CSV | `.csv` | UTF-8 BOM 兼容 Excel |
| JSON | `.json` | 格式化输出，含 headers/rows |

## 插件架构

excel2md 采用插件化设计，易于扩展：

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ InputPlugin │───▶│  Pipeline   │───▶│OutputPlugin │
└─────────────┘    └─────────────┘    └─────────────┘
                         │
                   ┌─────┴─────┐
                   │Transform  │
                   │Plugin     │
                   └───────────┘
```

### 已注册插件

**输入插件 (2)**
- `excel` — Excel 文件读取（支持多 Sheet、合并单元格）
- `csv` — CSV/TSV 解析

**输出插件 (3)**
- `markdown` — Markdown 表格生成
- `csv` — CSV 文件生成
- `json` — JSON 文件生成

**变换插件 (5)**
- `normalize` — 列数统一
- `filter` — 过滤空行
- `sort` — 按列排序
- `dedup` — 去除重复行
- `merge` — 合并多个表格

### 扩展插件

实现相应接口即可添加新插件：

```go
// 输入插件
type InputPlugin interface {
    Name() string
    Extensions() []string
    Parse(data []byte) ([]TableData, error)
}

// 输出插件
type OutputPlugin interface {
    Name() string
    Extension() string
    Write(tables []TableData, path string, opts OutputOptions) error
}

// 变换插件
type TransformPlugin interface {
    Name() string
    Transform(tables []TableData) ([]TableData, error)
}
```

## 特性

| 特性 | 说明 |
|------|------|
| 插件架构 | 输入/输出/变换三类插件，Registry + Pipeline 模式 |
| 多格式支持 | 2 种输入格式 × 3 种输出格式 = 6 种组合 |
| Excel 读取 | 支持多 Sheet、合并单元格、数值类型转换 |
| Markdown 输出 | 标准表格格式，自动列宽对齐 |
| 数据标准化 | 自动去除空白、统一列数、数字识别 |
| 批量处理 | 支持通配符和并发（`-j`） |
| 管道支持 | stdin/stdout，可与其他工具组合 |
| 彩色输出 | 终端友好，自动检测是否为 TTY |

## 项目结构

```
excel2md/
├── main.go                 # CLI 入口
├── pkg/
│   ├── plugin/             # 插件接口和管道
│   │   ├── types.go        # 接口定义
│   │   ├── registry.go     # 插件注册表
│   │   └── pipeline.go     # 执行管道
│   ├── input/              # 输入插件
│   │   ├── excel.go        # Excel 读取
│   │   └── csv.go          # CSV/TSV 解析
│   ├── output/             # 输出插件
│   │   ├── markdown.go     # Markdown 生成
│   │   ├── csv.go          # CSV 写入
│   │   └── json.go         # JSON 写入
│   ├── transform/          # 变换插件
│   │   ├── normalize.go    # 列数统一
│   │   ├── filter.go       # 行过滤
│   │   ├── sort.go         # 行排序
│   │   ├── dedup.go        # 去重
│   │   └── merge.go        # 合并表格
│   └── term/               # 终端输出
│       ├── colors.go       # ANSI 颜色
│       └── progress.go     # 进度指示
```

## 测试

```bash
go test -v ./...           # 运行所有测试
go test -v -run TestName   # 运行指定测试
```

## 更新日志

### v2.0.0 (2026-06-25)
- **重大变更**: 反转转换方向，从 Excel/CSV → Markdown（原为 Markdown → Excel）
- 新增 Excel 输入插件（支持多 Sheet、合并单元格）
- 新增 Markdown 输出插件（标准表格格式）
- 移除 Markdown 和 HTML 输入插件
- 移除 Excel 输出插件
- 保留 CSV 和 JSON 输出插件
- 更新 CLI 帮助文本和参数
- 更新测试用例

### v1.0.1 (2026-06-21)
- 修复 Markdown 表格中行内代码（`code`）解析 panic 问题
- 新增 `TestMarkdownInput_CodeSpan` 测试用例
- 新增 `md2excel` skill（`~/.mimocode/skills/md2excel/SKILL.md`）

### v1.0.0 (2026-06-20)
- 插件化架构：Input/Output/Transform 三类插件
- 支持 Markdown、HTML、CSV 输入；Excel、CSV、JSON 输出
- 双引擎解析：goldmark AST + 行解析降级
- 批量处理、管道支持、智能列宽

## 许可证

MIT