Skip to content

Latest commit

 

History

History
80 lines (65 loc) · 4.08 KB

README_CN.md

File metadata and controls

80 lines (65 loc) · 4.08 KB

Google Docs Markdown 修复工具说明书

1. 项目背景

本工具旨在解决从 Google Docs 下载的 Markdown 文件中存在的格式问题。

适用场景: 特别针对 Gemini 生成的内容（尤其是包含数学公式的内容）保存至 Google Docs 后，再导出为 Markdown 时出现的格式崩溃问题。由于 Google Docs 的导出机制会对特殊字符进行“过度转义”（Aggressive Escaping），导致 LaTeX 公式无法解析。

主要问题示例：

  • 公式错误: \tau 被转义为 \\tau，导致渲染失败。
  • 排版错误: _ 被转义为 \_，导致斜体或下标失效。
  • 列表错误: 1. 被转义为 1\.，导致列表无法识别。

2. 脚本详解

本项目包含以下几个主要脚本，各司其职：

  • main.py: 主程序入口。负责扫描目录（当前目录或 google_md）、调用修复逻辑，并最终调用 Pandoc 进行转换。建议直接运行此脚本。
  • fix_md.py: 核心修复逻辑。包含所有用于修复格式的正则表达式规则。您可以单独运行它，仅对文件进行修复而不转换。
  • md_to_docx.py: 格式转换工具。封装了 Pandoc 命令，用于将 Markdown 转换为 Word 文档。
  • reset_test.py: 测试重置工具。用于将一个正常的 Markdown 文件“故意损坏”（重新进行过度转义），以便开发者测试 fix_md.py 的修复效果。

3. 核心逻辑

脚本按照特定的顺序执行以下替换操作（顺序至关重要）：

  1. 还原反斜杠 (\\ → \): 修复 LaTeX 命令（如 \\boldsymbol 变为 \boldsymbol）。必须最先执行，防止误伤其他转义符。
  2. 还原下划线 (\_ → _): 修复数学公式中的下标（\tau_m）和文本中的斜体。
  3. 还原等号 (\= → =): 修复数学公式中的等式。
  4. 还原减号 (\- → -): 修复负号和无序列表。
  5. 还原加号 (\+ → +): 修复数学公式中的加法。
  6. 还原点号 (\. → .): 修复有序列表（如 1\.）。
  7. 还原方括号 (\[, \] → [, ]): 修复链接和引用。
  8. 还原其他符号: 包括 < (小于号), > (大于号), { (花括号), } (花括号), | (竖线)。

4. 使用方法

环境要求

  • Windows (或其他支持 Python 的系统)
  • Python 3.x

操作步骤

  1. 准备文件:

    • 方式 A (.md): 将需要修复的 .md 文件放入项目的 google_md 目录中。
    • 方式 B (.docx): 将 Google Docs 下载的 .docx 文件放入 google_docx 目录（或项目根目录）中。脚本会自动预处理。

  2. 运行脚本: 在终端（VS Code Terminal 或 PowerShell）中运行以下命令：

    py fix_md.py

    (或者使用 python fix_md.py，取决于您的 Python 安装设置)

  3. 查看结果: 脚本会输出处理的文件名和状态：

    • Fixed.: 检测到错误并已修复。
    • No changes needed.: 文件无需修复。

示例输出

Scanning directory: ...\google_md
Processing: ...\google_md\1.md
  Fixed.

5. 生成 EXE 可执行文件 (可选)

如果您希望生成一个不需要安装 Python 也能运行的 .exe 程序：

  1. 安装依赖: 
    pip install -r requirements.txt
  2. 执行打包: 
    pyinstaller google2md_mathfix.spec
  3. 获取程序: 打包完成后，可执行文件位于 dist 文件夹中：dist/google2md_mathfix.exe。 您可以将该 .exe 文件复制到任何包含 .md 文件的目录（或与 google_md 同级）直接运行。

6. 注意事项

  • 备份建议: 虽然脚本经过测试，但在处理重要文件前，建议先备份原始文件。
  • 目录结构: 默认脚本会在当前运行目录下的 google_md 文件夹中查找文件。请确保您在 项目根目录下 运行脚本。
  • 重置测试: 如果您想验证修复效果，可以使用 reset_test.py 脚本生成一个模拟的“损坏”文件进行测试。