# markdown-to-word

**Repository Path**: cutecuteyu/markdown-to-word

## Basic Information

- **Project Name**: markdown-to-word
- **Description**: markdown-to-word
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown 转 Word 转换器

<div align="center">

![Python](https://img.shields.io/badge/Python-3.13+-blue.svg)
![Flask](https://img.shields.io/badge/Flask-3.1+-green.svg)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)
![Status](https://img.shields.io/badge/Status-Production-ready-brightgreen.svg)

一个基于Flask的Markdown到Word文档转换工具，支持完整的样式映射和实时预览。

[功能特性](#功能特性) • [快速开始](#快速开始) • [使用说明](#使用说明) • [项目结构](#项目结构) • [开发指南](#开发指南)

</div>

---

## 📖 项目简介

Markdown转Word转换器是一个功能完整的Web应用程序，能够将Markdown格式的文本转换为Microsoft Word文档（.docx格式），同时保留原文档的所有格式元素。

本项目采用**简约线条设计风格**，提供直观的用户界面和实时预览功能，是文档处理和格式转换的理想工具。

### 核心特性

- 🔄 **完整样式映射** - 支持所有Markdown元素的样式转换
- 👁️ **实时预览** - 左侧编辑，右侧实时显示渲染效果
- 📁 **多种输入方式** - 支持文本输入和文件上传
- 🎨 **现代UI设计** - 简约线条风格，响应式布局
- ⚡ **高性能** - 本地处理，快速转换
- 🔒 **数据安全** - 文档在本地生成，无需上传服务器

---

## ✨ 功能特性

### 支持的Markdown元素

| 元素 | Markdown语法 | Word效果 | 状态 |
|------|--------------|----------|------|
| 标题 | `# H1` ~ `###### H6` | Heading 1-6样式 | ✅ |
| 粗体 | `**粗体**` | 粗体 | ✅ |
| 斜体 | `*斜体*` | 斜体 | ✅ |
| 删除线 | `~~删除线~~` | 删除线 | ✅ |
| 行内代码 | `` `代码` `` | 等宽字体+红色 | ✅ |
| 代码块 | ` ```代码``` ` | 等宽字体+边框+背景 | ✅ |
| 有序列表 | `1. 项目` | 带缩进编号 | ✅ |
| 无序列表 | `- 项目` | 带缩进圆点 | ✅ |
| 嵌套列表 | 缩进2空格 | 多级缩进 | ✅ |
| 引用 | `> 引用` | 左绿边框+斜体 | ✅ |
| 分隔线 | `---` | 水平线 | ✅ |
| 链接 | `[文本](URL)` | 蓝色下划线超链接 | ✅ |
| 表格 | `| 表头 |` | 标准Word表格 | ✅ |

### 界面功能

- **双栏编辑器** - 左侧Markdown输入，右侧实时预览
- **同步滚动** - 编辑器和预览区域滚动同步
- **文档统计** - 实时显示标题、段落、代码块等元素数量
- **示例模板** - 内置基础、代码、表格示例
- **拖拽上传** - 支持拖拽Markdown文件到上传区域
- **一键转换** - 点击按钮即可完成转换并下载

---

## 🚀 快速开始

### 环境要求

- Python 3.13 或更高版本
- uv 包管理器（推荐）或 pip
- 现代Web浏览器（Chrome、Firefox、Edge等）

### 安装步骤

#### 方法一：使用 uv（推荐）

```bash
# 1. 进入项目目录
cd markdown-to-word-converter

# 2. 依赖已通过 uv 安装
# 如需重新安装：
uv sync

# 3. 运行应用
uv run python app.py
```

#### 方法二：使用 pip

```bash
# 1. 进入项目目录
cd markdown-to-word-converter

# 2. 创建虚拟环境（可选）
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

# 3. 安装依赖
pip install flask markdown2 python-docx beautifulsoup4 lxml

# 4. 运行应用
python app.py
```

### 访问应用

启动成功后，在浏览器中打开：

```
http://localhost:5000
```

---

## 📖 使用说明

### 方式一：文本输入

1. 在左侧编辑器中输入或粘贴Markdown文本
2. 右侧实时预览渲染效果
3. 点击"转换为 Word"按钮
4. 浏览器自动下载生成的Word文档

### 方式二：文件上传

1. 点击左侧导航的"文件上传"
2. 点击上传区域或拖拽Markdown文件
3. 点击"转换为 Word"按钮
4. 浏览器自动下载生成的Word文档

### 快捷操作

- **清空** - 清除输入内容
- **基础** - 加载基础示例
- **代码** - 加载代码示例
- **表格** - 加载表格示例

---

## 📁 项目结构

```
markdown-to-word-converter/
├── app.py                  # Flask应用主文件
├── converter.py            # Markdown转换器核心模块
├── static/                 # 静态资源目录
│   ├── css/
│   │   └── style.css       # 样式表（简约线条设计）
│   └── js/
│       └── app.js          # 前端JavaScript
├── templates/              # 模板目录
│   └── index.html          # 主页面模板
├── uploads/                # 文件上传目录（自动创建）
├── pyproject.toml          # 项目配置文件
├── README.md               # 项目说明文档（中文）
├── README.en.md            # 项目说明文档（英文）
└── 使用说明.md             # 用户使用指南
```

### 模块说明

#### app.py
Flask应用程序的主入口文件，负责：
- 路由配置和请求处理
- API接口定义（/convert, /preview）
- 文件上传和下载处理
- 应用配置和启动

#### converter.py
Markdown到Word转换的核心模块，提供：
- `MarkdownToWordConverter` 类
- HTML解析和Word文档生成
- 样式映射和格式处理
- 超链接、表格、代码块等元素处理

#### static/css/style.css
采用简约线条设计风格的样式表：
- CSS自定义属性（设计令牌）
- 响应式布局和移动端适配
- Markdown预览样式
- 动画和交互效果

#### static/js/app.js
前端应用逻辑，包含：
- 导航切换处理
- 实时预览功能
- 文件上传处理
- API调用和文档下载
- UI状态管理

#### templates/index.html
主页面模板，使用Jinja2语法：
- 语义化HTML结构
- 响应式双栏布局
- 模块化组件设计

---

## 🛠️ 开发指南

### 技术栈

**后端**
- **Python 3.13+** - 编程语言
- **Flask 3.1+** - Web框架
- **python-docx** - Word文档生成
- **markdown2** - Markdown解析
- **BeautifulSoup4** - HTML解析
- **lxml** - XML处理

**前端**
- **原生JavaScript (ES6+)** - 前端逻辑
- **Marked.js** - Markdown实时解析
- **CSS3** - 样式和动画
- **CSS Grid** - 响应式布局

**开发工具**
- **uv** - Python包管理器
- **Jinja2** - 模板引擎（Flask内置）

### 开发环境设置

```bash
# 1. 克隆或下载项目
cd markdown-to-word-converter

# 2. 安装开发依赖
uv add --dev pytest black mypy pylint

# 3. 运行代码检查
uv run black app.py converter.py
uv run mypy app.py converter.py
```

### 调试模式

应用默认以调试模式运行，支持：
- 代码修改后自动重载
- 详细的错误信息输出
- Flask调试工具栏

### 添加新功能

#### 添加新的Markdown元素支持

1. 在 `converter.py` 的 `_process_inline_elements()` 方法中添加新元素的处理
2. 在 `static/css/style.css` 的 `.markdown-preview` 部分添加样式
3. 测试转换效果

#### 修改UI样式

1. 编辑 `static/css/style.css`
2. CSS变量在 `:root` 中定义
3. 修改后会自动重载（调试模式）

#### 添加新的API接口

1. 在 `app.py` 中使用 `@app.route` 装饰器添加路由
2. 在 `static/js/app.js` 中添加对应的API调用函数
3. 更新HTML模板添加必要的UI元素

### 测试

```bash
# 运行测试
uv run pytest

# 代码格式化
uv run black .

# 类型检查
uv run mypy .
```

---

## 🎨 设计说明

### 简约线条设计风格

本项目采用**简约线条设计（Minimal Line Design）**风格，核心理念：

- **极简主义** - 去除所有不必要的装饰元素
- **几何精度** - 使用精确的1px线条和8px网格系统
- **负空间** - 充分利用空白创造视觉呼吸感
- **功能性** - 每个样式元素都有明确的用途

### 设计令牌

```css
--black: #0a0a0a;      /* 主黑色 */
--white: #fafafa;      /* 主白色 */
--gray-200: #d4d4d4;   /* 边框色 */
--line: 1px;           /* 线条粗细 */
--space: 8px;          /* 间距单位 */
```

### 响应式断点

- **桌面**：> 1200px - 双栏布局
- **平板**：768px - 1200px - 单栏堆叠
- **手机**：< 768px - 单栏优化

---

## 📋 配置选项

### Flask应用配置

在 `app.py` 中可以修改：

```python
# 最大上传文件大小
app.config['MAX_CONTENT_LENGTH'] = 16 * 1024 * 1024  # 16MB

# 上传目录
app.config['UPLOAD_FOLDER'] = 'uploads'

# 调试模式
app.run(debug=True)  # 生产环境设为False
```

### 服务器配置

```python
# 主机地址
app.run(host='0.0.0.0')  # 0.0.0.0 允许外部访问

# 端口号
app.run(port=5000)      # 可更改为其他端口
```

### Word文档样式配置

在 `converter.py` 的 `_setup_styles()` 方法中可以修改：

- 默认字体
- 字号大小
- 颜色方案
- 行间距等

---

## 🔧 常见问题

### Q: 转换后的Word文档格式不正确？

A: 确保输入的Markdown语法正确。某些复杂格式可能需要调整。尝试使用示例模板测试。

### Q: 无法启动服务器，提示端口被占用？

A: 端口5000可能被其他程序占用。可以：
1. 关闭占用端口的程序
2. 在 `app.py` 中修改端口号

### Q: 中文字体显示异常？

A: 确保系统安装了"微软雅黑"字体。可在 `converter.py` 中修改为其他字体。

### Q: 代码块显示不完整？

A: 长代码行可能被截断。可以在Word中调整页面边距或缩小代码字号。

### Q: 表格样式不满意？

A: 当前使用Word内置表格样式。可在 `converter.py` 的 `_add_table()` 方法中自定义样式。

---

## 📄 许可证

本项目采用 MIT 许可证开源。

---

## 🤝 贡献

欢迎贡献代码、报告问题或提出改进建议！

### 贡献方式

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交Pull Request

---

## 📞 联系方式

- **项目地址**：[GitHub仓库链接]
- **问题反馈**：[Issues页面]

---

## 🙏 致谢

本项目使用以下优秀的开源库：

- [Flask](https://flask.palletsprojects.com/) - Web框架
- [python-docx](https://python-docx.readthedocs.io/) - Word文档生成
- [markdown2](https://github.com/trentm/python-markdown2) - Markdown解析
- [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) - HTML解析
- [Marked.js](https://marked.js.org/) - Markdown实时预览

---

<div align="center">

**Made with ❤️ by Claude Code**

</div>