笔记文件格式转换说明¶

本文档描述从 Obsidian 笔记到 Zensical 网站的所有 Markdown 格式转换规则，以及转换工具的使用方法。

一、转换规则¶

1. 一级标题¶

笔记	网站
多数文件无 `# 标题`	必须有 `# 标题`，标题等于文件名（不含 `.md`）

文件名和一级标题保持一致。例如 优化理论速成.md → # 优化理论速成。

2. 段落间距¶

笔记	网站
段落、列表、代码块之间可无空行	以下情况必须空一行，否则 Zensical 无法正常渲染

需要空行的场景：

两段普通文字之间
普通文字后接列表第一项
普通文字后接代码块
数学块 $$...$$ 前后

3. Admonition¶

笔记（Obsidian）	网站（Zensical）
`> [!NOTE] 标题`	`!!! note "标题"`
`> 正文行`	`正文行`（4 空格缩进）

示例：

# 笔记
> [!NOTE] 重参数化技巧
> 现在，我们知道 $z$ 是通过采样得到的...

# 网站
!!! note "重参数化技巧"

    现在，我们知道 $z$ 是通过采样得到的...

已支持的 admonition 类型：note tip info question warning example quote theorem

4. 图片引用¶

笔记（Obsidian）	网站（Zensical）
`![[图片.png]]`	`![](./<文件名>.assets/图片.png){.img-center width=50%}`
`![[图片.png\\|402]]`	`![](./<文件名>.assets/图片.png){.img-center width=X%}`

规则：

图片存放在 <md文件名>.assets/ 文件夹中（与 .md 同级）
图片名不需要 URL 编码，中文名直接使用
转换工具自动从 obsidian_imgs/ 复制图片到 .assets/ 目录
图片默认居中（.img-center）并缩放

5. Wiki-Link（内部链接）¶

笔记	网站
`[[页面名]]`	`[页面名](相对路径/页面名.md)`
`[[页面名\\|显示名]]`	`[显示名](相对路径/页面名.md)`
`[[页面名#章节]]`	`[页面名](相对路径/页面名.md#章节)`

链接中如有空格或中文，需 URL 编码。

6. 数学公式¶

$$...$$ 整体前后必须各空一行（开头 $$ 前、结尾 $$ 后）。

二、转换工具使用指南¶

工具位置：cloudmosquito_site/tools/obsidian_to_zensical.py

纯 Python 脚本，无第三方依赖，Python 3.10+ 即可运行。

首次配置¶

在新电脑上首次使用，需要指定笔记目录的位置：

cd cloudmosquito_site

# 创建配置文件（只需执行一次）
python tools/obsidian_to_zensical.py --init-config "E:/你的Obsidian笔记目录"

这会在 tools/convert_config.json 中记录笔记路径。之后使用无需再指定。

日常使用¶

# 预览转换结果（不写文件，打印到终端）
python tools/obsidian_to_zensical.py -i "控制理论/最优控制/优化理论速成.md" --dry-run

# 转换单个文件
python tools/obsidian_to_zensical.py -i "控制理论/最优控制/优化理论速成.md"

# 强制覆盖已有输出
python tools/obsidian_to_zensical.py -i "文件.md" --force

# 跳过图片复制（仅转换文本）
python tools/obsidian_to_zensical.py -i "文件.md" --skip-images

批量转换¶

# 转换笔记目录下所有 .md 文件
python tools/obsidian_to_zensical.py --batch

# 仅转换有修改的文件（推荐日常使用）
python tools/obsidian_to_zensical.py --batch --only-modified --force

# 预览批量转换结果
python tools/obsidian_to_zensical.py --batch --dry-run

覆盖默认路径¶

如果没创建配置文件，或临时使用不同路径：

python tools/obsidian_to_zensical.py \
    --notes-root "D:/另一个笔记目录" \
    --website-root "D:/另一个网站/docs" \
    -i "文件.md"

完整参数列表¶

参数	说明
`-i, --input`	源文件路径（相对笔记根目录）
`-o, --output`	输出路径（默认自动推导）
`--batch`	批量转换全部文件
`--dry-run, -n`	预览模式，不写入
`--force, -f`	强制覆盖已有输出
`--skip-images`	跳过图片文件复制
`--only-modified`	仅转换比输出更新的源文件
`--verbose, -v`	详细日志
`--notes-root`	笔记根目录（覆盖配置文件）
`--website-root`	网站 docs 目录（覆盖自动检测）
`--init-config`	创建配置文件并写入笔记路径

转换流程¶

工具按以下顺序进行处理，且不会修改代码块内的内容：

修复已有文件中重复的图片属性
规范化段落/列表/代码块间距
转换 Admonition（> [!TYPE] → !!! type）
转换 Wiki-Link（[[页面]] → [页面](路径.md)）
转换图片引用（![[图]] → ![](./.assets/图)）+ 复制图片文件
确保数学块前后有空行
添加一级标题（取文件名）
补全链接中缺失的 .md 扩展名

两次运行同一文件结果不变（幂等）。