CSV到MD实时同步工具集
Time: 6 min
Words: 1.6k words
Updated: 2026-05-27
Reads: 0 times
这是一套用于将CSV数据实时同步到Markdown文件的Python工具集，支持三种不同类型的内容同步：数据集、文档库和学术论文。
脚本概览
datasets_csv_to_md.py - 数据集同步工具
- 功能：将CSV格式的数据集信息同步到Markdown表格中
- 目标：更新包含
id="datasets-table"的HTML表格的tbody内容 - CSV格式：7列数据（数据集名称, 产品, 分析软件, 物种, 样品类型, 数据信息, 数据下载）
documents_csv_to_md.py - 文档库同步工具
- 功能：将CSV格式的文档信息同步到Markdown文档卡片中
- 目标：更新文档卡片区域的内容
- CSV格式：5列数据（标题, 描述, 标签, 链接, 日期）
publications_csv_to_md.py - 学术论文同步工具
- 功能：将CSV格式的论文信息同步到Markdown表格中
- 目标：更新包含
id="publications-table"的HTML表格的tbody内容 - CSV格式：8列数据（年份, 文章标题, 期刊, 影响因子, 样品类型, 产品类型, DOI, 文章解读）
功能特性
核心功能
- ✅ 实时监控：监控CSV文件变化，自动同步到MD文件
- ✅ 单次同步：支持手动执行单次同步操作
- ✅ 智能解析：自动处理特殊格式的字段（如链接、DOI、标签等）
- ✅ HTML生成：将CSV数据转换为格式化的HTML内容
- ✅ 错误处理：完善的错误处理和日志输出
特殊字段处理
数据集工具 (datasets_csv_to_md.py)
- 下载链接字段：支持
label: url | label: url格式，自动转换为HTML链接 - 示例：
数据下载: https://example.com | 说明文档: https://docs.com
文档库工具 (documents_csv_to_md.py)
- 标签字段：支持逗号分隔的标签，自动转换为
data-tags属性 - 卡片样式：生成美观的文档卡片HTML结构
论文工具 (publications_csv_to_md.py)
- DOI字段：自动标准化DOI链接格式
- 文章解读字段：支持
导语内容 | 链接URL格式 - 富文本支持：支持在解读字段中插入HTML内容
使用方法
基本语法
bash
python script_name.py --csv <CSV文件路径> --md <MD文件路径> [选项]参数说明
| 参数 | 必需 | 默认值 | 说明 |
|---|---|---|---|
--csv | ✅ | - | CSV源文件路径 |
--md | ✅ | - | 目标MD文件路径 |
--encoding | ❌ | utf-8 | 文件编码格式 |
--watch | ❌ | false | 启用监控模式 |
--interval | ❌ | 1.0 | 监控间隔（秒） |
使用示例
单次同步
bash
# 同步数据集
python ./zh/General/csv.src/datasets_csv_to_md.py --csv ./zh/General/csv.src/datasets.csv --md ./zh/General/datasets.md
# 同步文档库
python ./zh/General/csv.src/documents_csv_to_md.py --csv ./zh/General/csv.src/documents.csv --md ./zh/General/document_library.md
# 同步论文
python ./zh/General/csv.src/publications_csv_to_md.py --csv ./zh/General/csv.src/publications.csv --md ./zh/General/publications.md实时监控模式
bash
# 监控数据集CSV变化
python datasets_csv_to_md.py --csv datasets.csv --md datasets.md --watch
# 自定义监控间隔（每2秒检查一次）
python documents_csv_to_md.py --csv documents.csv --md document_library.md --watch --interval 2.0指定编码格式
bash
# 使用GBK编码
python publications_csv_to_md.py --csv publications.csv --md publications.md --encoding utf-8CSV文件格式要求
数据集CSV格式
csv
数据集名称,产品,分析软件,物种,样品类型,数据信息,数据下载
单细胞数据集,scRNA-seq,Seurat,人类,血液,1000个细胞,数据下载: https://example.com | 说明: https://docs.com文档库CSV格式
csv
标题,描述,标签,链接,日期
用户手册,详细的使用说明文档,教程,用户指南,https://docs.example.com,2024-01-15
API文档,完整的API接口文档,开发,API,https://api.example.com,2024-01-10论文CSV格式
csv
年份,文章标题,期刊,影响因子,样品类型,产品类型,DOI,文章解读
2024,单细胞转录组分析新方法,Nature,69.5,血液,scRNA-seq,10.1038/s41586-024-12345-6,本研究提出了新的分析方法 | https://blog.example.com目标MD文件要求
数据集MD文件
需要包含以下HTML结构：
html
<table id="datasets-table">
<thead>...</thead>
<tbody>
<!-- 脚本会替换此区域的内容 -->
</tbody>
</table>文档库MD文件
需要包含以下HTML结构：
html
<div style="display:flex;flex-direction:column;gap:14px;">
<!-- 脚本会替换此区域的内容 -->
</div>论文MD文件
需要包含以下HTML结构：
html
<table id="publications-table">
<thead>...</thead>
<tbody>
<!-- 脚本会替换此区域的内容 -->
</tbody>
</table>监控模式说明
工作原理
- 脚本持续监控CSV文件的修改时间
- 检测到文件变化时，自动执行同步操作
- 输出详细的日志信息，包括时间戳和操作结果
- 支持Ctrl+C优雅停止监控
日志输出示例
开始监控 datasets.csv
目标文件 datasets.md
检查间隔 1.0秒
按 Ctrl+C 停止监控
检测到CSV文件变化 (14:30:25)
文件修改时间: 1705122625.0 > 1705122600.0
已更新 15 条数据集记录到 datasets.md
更新成功，继续监控...错误处理
常见错误及解决方案
文件不存在
CSV文件不存在: datasets.csv- 检查文件路径是否正确
- 确认文件是否存在
表格结构错误
未找到 id="datasets-table" 的表格- 检查MD文件是否包含正确的HTML结构
- 确认表格ID是否正确
编码问题
读取CSV文件失败: 'utf-8' codec can't decode- 使用
--encoding参数指定正确的编码格式 - 常见编码：utf-8, gbk, gb2312
- 使用
依赖要求
- Python 3.6+
- 标准库模块：
argparse,csv,html,os,re,time,pathlib,typing
注意事项
- 备份重要文件：脚本会直接修改MD文件，建议先备份
- CSV格式：确保CSV文件包含表头，脚本会自动跳过第一行
- HTML结构：目标MD文件必须包含正确的HTML结构标记
- 文件权限：确保脚本有读写目标文件的权限
- 监控模式：长时间运行时注意系统资源使用情况
扩展开发
如需添加新的同步类型，可以参考现有脚本的结构：
- 定义CSV列数和字段处理逻辑
- 实现HTML内容生成函数
- 添加目标文件结构识别逻辑
- 保持与现有脚本相同的命令行接口
许可证
本项目采用MIT许可证，详见LICENSE文件。