# md2cardplus

**Repository Path**: codecomb/md2cardplus

## Basic Information

- **Project Name**: md2cardplus
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-21
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown to Knowledge Cards Converter (MD2CardPuls)

将Markdown文件转换为美观的知识卡片HTML页面的AI驱动工具。

<!-- ![知识卡片示例](demo/2025.11-1_cards.png) -->
<!-- 注意：示例图片文件需要通过安装weasyprint并运行处理脚本生成 -->

## 功能特点

- 📝 **AI增强排版**：使用DeepSeek或Qwen3-Max大语言模型自动优化Markdown内容排版
- 🎨 **精美知识卡片**：将优化后的内容转换为响应式、美观的HTML知识卡片
- 🖼️ **图片导出支持**：可将HTML卡片转换为PNG图片（需安装weasyprint）
- 📱 **响应式设计**：自动适配不同屏幕尺寸，在移动端完美展示
- 🎯 **多模型支持**：同时支持DeepSeek和Qwen3-Max两种AI模型
- 🔄 **完整处理流程**：从原始Markdown到优化排版再到知识卡片的全流程自动化
- 💡 **智能内容增强**：自动添加emoji表情、视觉元素和图片链接提升可读性

## 项目结构

```
md2cardpuls/
├── card.py                             # 主处理脚本和入口
├── markdown_to_knowledge_cards.py      # Qwen3-Max卡片生成模块
├── markdown_to_knowledge_cards_ds.py   # DeepSeek卡片生成模块
├── requirements.txt                    # 项目依赖
├── README.md                           # 项目说明文档
├── demo/                               # 示例文件目录
│   ├── test_input.md                   # 示例Markdown源文件
│   ├── test_input_optimized.md         # 优化后的Markdown文件
│   ├── test_input_cards.html           # 生成的知识卡片HTML
│   ├── 2025.11-1.md                    # 更多示例文件
│   ├── 反对党八股.md                   # 更多示例文件
│   └── 课件1.md                        # 更多示例文件
└── .venv/                              # Python虚拟环境目录
```

## 安装依赖

1. **创建并激活虚拟环境**（可选但推荐）
```bash
python3 -m venv .venv
source .venv/bin/activate  # MacOS/Linux
# .venv\Scripts\activate  # Windows
```

2. **安装基础依赖**
```bash
pip install -r requirements.txt
```

3. **安装图片导出依赖**（可选）

项目支持将HTML知识卡片转换为PNG图片，需要额外安装weasyprint：

```bash
pip install weasyprint
```

注意：weasyprint在某些系统上可能需要额外的依赖，请参考[weasyprint官方安装指南](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html)。

## API密钥配置

项目支持两种AI模型进行Markdown优化和知识卡片生成：

### DeepSeek API（默认）

设置环境变量：
```bash
export DEEPSEEK_API_KEY=your_deepseek_api_key
```

或在代码中直接设置默认值（不推荐用于生产环境）。

### Qwen3-Max API（阿里云DashScope）

设置环境变量以使用Qwen3-Max：
```bash
export Qwen_API_KEY=your_qwen_api_key
```

或设置DASHSCOPE_API_KEY环境变量，程序会优先使用Qwen3-Max模型：
```bash
export DASHSCOPE_API_KEY=your_dashscope_api_key
```

## 命令行使用

### 基本用法

使用提供的命令行工具可以直接将本地Markdown文件转换为知识卡片：

```bash
python card.py <markdown_file_path> [output_directory]
```

参数说明：
- `markdown_file_path`: 输入的Markdown文件路径（必需）
- `output_directory`: 输出目录路径（可选，默认为输入文件所在目录）

### 处理流程

当运行命令时，程序会自动执行以下步骤：

1. **Markdown排版优化**：使用DeepSeek API对原始Markdown进行排版优化，生成更易读的版本
2. **知识卡片HTML生成**：根据环境变量配置，使用DeepSeek或Qwen3-Max API将优化后的Markdown转换为美观的知识卡片HTML页面
3. **图片导出**（可选）：如果安装了weasyprint，还会将HTML转换为PNG图片

### 示例

```bash
# 转换demo目录下的示例文件
python card.py demo/test_input.md

# 转换文件并指定输出目录
python card.py demo/test_input.md output/

# 使用Qwen3-Max模型（需先设置相关环境变量）
export DASHSCOPE_API_KEY=your_key
python card.py demo/2025.11-1.md
```

生成的文件包括：
- `*_optimized.md`：优化排版后的Markdown文件
- `*_cards.html`：知识卡片HTML文件
- `*_cards.png`：知识卡片PNG图片（需要安装weasyprint）

## 核心功能模块

### 1. Markdown优化模块 (`card.py`)
- 使用AI对原始Markdown内容进行排版优化
- 添加emoji表情、图片链接增强可读性
- 重组内容结构，优化层级和格式

### 2. Qwen3-Max卡片生成 (`markdown_to_knowledge_cards.py`)
- 使用阿里云DashScope平台的Qwen3-Max模型
- 生成符合设计规范的响应式HTML知识卡片
- 支持流式输出和思考过程可视化
- 具有完善的错误处理和重试机制

### 3. DeepSeek卡片生成 (`markdown_to_knowledge_cards_ds.py`)
- 使用DeepSeek API生成知识卡片
- 提供现代化、美观的CSS样式
- 支持响应式设计和交互效果

### 4. HTML转图片功能 (`card.py`)
- 通过weasyprint库将HTML卡片转换为PNG图片
- 自动处理临时文件和错误情况

## 输出示例

### 1. 优化后的Markdown文件

原始Markdown经过AI优化后，会添加emoji表情、更好的格式和图片链接：

```markdown
# 项目复盘会议纪要

## 📅 会议基本信息
- **会议时间**：2025年11月1日 14:00-16:00
- **会议地点**：会议室A
- **参会人员**：张三、李四、王五、赵六
- **会议主持**：张三
- **记录人**：李四

![会议现场](https://images.unsplash.com/photo-1542744173-8e7e53415bb0?w=600)
```

### 2. 知识卡片HTML文件

生成的HTML知识卡片具有以下特点：
- 固定宽度440px，高度自适应的设计
- 紫→红→橙的垂直线性渐变背景
- 浅粉色系(#FFF9F9)的卡片底色
- 圆角和阴影效果提升立体感
- 黑体加粗的标题设计
- 使用Font Awesome图标增强视觉效果
- 响应式设计，移动端自动缩放至视口宽度95%

### 3. 知识卡片图片

如果安装了weasyprint，系统会自动将HTML卡片转换为PNG图片，便于分享和使用。

## 模型选择逻辑

程序会根据环境变量自动选择使用的AI模型：

1. 如果设置了`DASHSCOPE_API_KEY`环境变量，将优先使用Qwen3-Max模型
2. 否则将使用DeepSeek模型进行处理
3. 对于Markdown排版优化，始终使用DeepSeek API

## 注意事项

1. **API密钥安全**：请妥善保管您的API密钥，不要将其提交到公开仓库
2. **网络连接**：处理过程需要访问AI模型API，请确保网络连接正常
3. **API调用限制**：注意各平台的API调用频率限制和费用
4. **文件编码**：请确保Markdown文件使用UTF-8编码
5. **图片导出**：如需导出PNG图片，请安装weasyprint依赖
6. **模型选择**：根据环境变量自动选择使用的AI模型

## 故障排除

常见问题及解决方案：

1. **API调用失败**：
   - 检查API密钥是否正确设置
   - 确认网络连接正常
   - 查看错误日志获取详细信息
   - 程序内置了重试机制，会自动尝试多次

2. **缺少依赖**：
   - 运行`pip install -r requirements.txt`安装所有依赖
   - 如需图片导出功能，还需安装weasyprint

3. **文件编码问题**：
   - 确保Markdown文件使用UTF-8编码
   - 避免使用特殊字符集

4. **输出文件为空**：
   - 检查输入文件路径是否正确
   - 确认文件具有读取权限
   - 查看控制台输出的错误信息

5. **HTML转图片失败**：
   - 确保已正确安装weasyprint
   - 对于复杂的HTML内容，可能需要调整CSS样式以确保正确渲染

## 使用场景

- 📚 **学习笔记整理**：将学习笔记转换为美观的知识卡片
- 📝 **会议记录分享**：将会议纪要转换为易读的卡片形式
- 🏫 **教学资料准备**：为课件内容创建视觉吸引力强的教学卡片
- 📊 **报告摘要展示**：将长文档的关键信息提取为卡片形式
- 📱 **移动端阅读优化**：生成专为手机阅读优化的内容格式

## 技术栈

- **Python 3**：核心编程语言
- **OpenAI SDK**：用于调用Qwen3-Max API
- **Requests**：HTTP请求库，用于调用DeepSeek API
- **WeasyPrint**（可选）：HTML转图片工具
- **Font Awesome**：用于卡片中的图标
- **CSS3/Flexbox**：用于响应式卡片设计