math-card-import

name	math-card-import
description	数学 Anki 卡片导入。将 Markdown 格式的数学知识卡批量导入 Anki（通过 AnkiConnect）， 自动处理 MathJax 公式渲染兼容性（$...$ → \(...\) 转换）、配图复制、HTML 格式化。 触发条件：用户提到"导入anki"、"anki卡片"、"数学anki"、"牌组导入"、公式在 Anki 中显示不正确、$...$ 公式不渲染、MathJax 兼容性问题、创建/修改/完善 Anki 数学卡片、调整卡片格式。 也用于：已有 Anki 卡片公式显示异常的诊断和批量修复。

数学 Anki 卡片导入

将 Markdown 格式的数学知识卡批量导入 Anki，自动处理公式渲染兼容性。

前置条件

• Anki 已启动，AnkiConnect 插件可用（默认 localhost:8765）
• 卡片以 Markdown 文件编写，放在 G:/初中/数学/ 目录下

卡片 Markdown 格式

每张卡片用 ### 卡N 分隔，包含以下字段：

### 卡1

**配图：** ![](子文件夹/01.webp)

**提问：** 同底数幂相乘的公式是什么？

**答案：** $a^m \cdot a^n = a^{m+n}$。

**易错分析：** 底数不变，指数相加。

**记忆钩子：** 底同指加，乘对加。（可选字段）

字段说明

字段	必须	说明
**配图：**	否	图片路径，相对于 md 文件的子文件夹。支持 webp/png/jpg
**提问：**	是	卡片正面内容，支持行内公式
**答案：**	是	卡片背面内容，支持行内和显示公式
**易错分析：**	否	红色文字显示的易错提醒
**记忆钩子：**	否	绿色文字显示的助记口诀

公式语法

在 Markdown 源文件中使用标准 LaTeX 语法：

• 行内公式：$a^2 + b^2 = c^2$ — 导入时自动转为 \(...\) 格式
• 显示公式（块级）：\[ ... \] 或 $$ ... $$ — 保留原始格式

导入脚本位于 G:/初中/数学/import_math_to_anki.py。

MathJax 公式兼容性（关键知识点）

这是最容易出错的部分，务必理解。

问题

Anki（2.1.50+）内置 MathJax，但仅默认支持：

• \(...\) 行内公式 ✅
• \[...\] 显示公式 ✅
• $...$ 行内公式 ❌ 不支持

如果直接将包含 $...$ 的文本导入 Anki，公式会显示为原始 $a^2$ 而不是渲染后的数学符号。

解决方案

导入脚本中的 convert_inline_math() 函数自动处理转换：

def convert_inline_math(text):
    """将 $...$ 行内公式转换为 Anki 支持的 \(...\) 格式。
    跳过 $$...$$ 和 \[...\] 显示公式块。"""
    return re.sub(
        r'(?<!\$)\$(?!\$)(.*?)(?<!\$)\$(?!\$)',
        r'\(\1\)',
        text
    )

转换规则：

• $x^2$ → \(x^2\)（行内公式，转换为 \(...\)）
• $$x^2$$ → $$x^2$$（显示公式，不转换）
• \[x^2\] → \[x^2\]（显示公式，不转换）

显示公式的换行保护

preserve_display_math() 函数处理 \[...\] 和 $$...$$ 块：

• 块内的换行符替换为空格（防止被 html_field() 转成 <br>）
• 块外的换行符正常转为 <br>

两个字段的不同处理

字段	处理方式	原因
Front	convert_inline_math() 仅转换公式	正面通常为单行文本，不需要 <br>
Back	html_field() 转换公式 + 换行转 <br> + 保护显示公式	背面可能有多行答案、易错分析、记忆钩子

导入流程

标准导入

cd G:\初中
python 数学/import_math_to_anki.py

这会：

1. 清空现有"数学"牌组
2. 扫描 数学/ 下所有 .md 文件
3. 解析卡片、转换公式、复制配图
4. 批量导入 Anki（每批 30 张）

仅导入特定文件

修改 import_math_to_anki.py 中的 md_files 路径过滤，或编写针对性的导入脚本。

修复已有卡片公式

当发现已导入的卡片公式不显示时：

批量修复（推荐）

# 对现有多有卡片执行 convert_inline_math
for note in all_notes:
    new_front = convert_inline_math(front)
    new_back = convert_inline_math(back)
    invoke_anki("updateNoteFields", {
        "note": {"id": note_id, "fields": {
            "Front": new_front, "Back": new_back
        }}
    })

然后重新导入整个牌组。

单张卡片修复

1. 在 Anki 浏览器中找到卡片
2. 修改字段中的 $...$ 为 \(...\)
3. 保存

验证

检查卡片是否使用正确的格式：

# 好的格式（能渲染）
"已知 \(a^2 + a - 1 = 0\)，怎样处理含 \(a^3\) 的式子？"

# 坏的格式（不能渲染）
"已知 $a^2 + a - 1 = 0$，怎样处理含 $a^3$ 的式子？"

AnkiConnect API 参考

导入脚本使用的关键 API：

操作	action	说明
检查连接	version	返回 AnkiConnect 版本号
获取牌组	deckNames	列出所有牌组
创建牌组	createDeck	{"deck": "数学"}
查询卡片	findNotes	{"query": 'deck:"数学"'}
批量导入	addNotes	{"notes": [...]}
删除卡片	deleteNotes	{"notes": [id1, id2]}
更新字段	updateNoteFields	{"note": {"id": ..., "fields": {...}}}
获取媒体路径	getMediaDirPath	返回 collection.media 目录
卡片详情	notesInfo	{"notes": [id1, id2]}

常见问题

Q: 卡片导入后公式显示为原始 $...$ 文本

原因：公式使用了 $...$ 格式，Anki 默认不支持。

解决：运行修复脚本转换所有 $...$ → \(...\)，或重新导入（导入脚本已自动转换）。

Q: 显示公式 \[...\] 内部出现多余的 <br>

原因：html_field() 将显示公式块内的换行符错误地转成了 <br>。

解决：确保 preserve_display_math() 在 html_field() 中被优先调用。导入脚本 v2 已修复此问题。

Q: AnkiConnect 连接失败 "Connection refused"

原因：Anki 未启动或 AnkiConnect 插件未安装。

解决：

1. 确保 Anki 正在运行
2. 检查 AnkiConnect 插件是否已安装（工具 → 附加组件 → 搜索 AnkiConnect）
3. 确认端口 8765 未被占用

Q: 配图不显示

原因：图片路径错误或未复制到 Anki 媒体文件夹。

解决：

1. 检查 md 文件旁是否有同名子文件夹存放 webp 图片
2. 路径格式：**配图：** ![](子文件夹/01.webp)
3. 导入脚本会自动复制图片到 Anki 的 collection.media 目录

项目文件结构

G:/初中/数学/
├── import_math_to_anki.py          # 主导入脚本
├── 七年级下册/
│   ├── 错题补充-代数易错记忆.md    # 卡片源文件
│   ├── 错题补充-代数易错记忆/      # 配图文件夹（webp）
│   │   ├── 01.webp
│   │   └── ...
│   ├── 重要知识点补充-实数坐标系不等式统计.md
│   └── 重要知识点补充-实数坐标系不等式统计/
│       └── ...

添加新卡片

1. 在对应的 .md 文件中按格式添加新的 ### 卡N 块
2. 如果需要配图，将图片放入同名的子文件夹
3. 公式统一使用 $...$ 写法（导入时自动转换）
4. 运行 python 数学/import_math_to_anki.py 重新导入