# html_to_markdown

**Repository Path**: HappyEventKing/html_to_markdown

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-01-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HTML到Markdown批量转换工具

## 项目初始目的

本项目的初始目的是为了将印象笔记中导出的笔记（多个网页格式（html））转换为Markdown格式后，导入到思源笔记中。通过批量处理HTML文件及其资源，确保笔记内容和结构的完整保留，实现跨平台笔记迁移。

## 工具简介

这是一个用于将HTML文件批量转换为Markdown文件的Python工具，支持保持目录结构和处理资源文件，具有强大的错误处理和资源管理能力。

## 功能特点

1. **批量转换**：支持转换目录下所有HTML文件以及递归所有子目录中的HTML文件
2. **保持目录结构**：转换后的Markdown文件的目录结构与原始HTML文件保持一致，确保笔记的层次结构完整保留
3. **资源文件处理**：自动处理HTML中的图片和其他资源文件（PDF、ZIP、EXE等）
4. **资源文件复制**：将资源文件复制到转换后的Markdown文件同目录下的assets目录中
5. **文件名规范化**：处理特殊字符和中文标点符号，确保资源文件名在各种系统中都能正常使用
6. **智能去重**：基于文件哈希值对资源文件进行去重，避免重复复制相同的资源
7. **alt属性处理**：修复包含方括号等特殊字符的alt属性，确保Markdown转换正确
8. **准确的资源统计**：避免重复计数和错误统计，确保资源文件数量匹配
9. **详细的转换报告**：生成HTML格式的转换报告，包含资源完整性检查和错误分析

## 印象笔记迁移流程

### 1. 印象笔记导出

在印象笔记中，手动按单个笔记本导出到有层次结构的目录：

1. 打开印象笔记客户端
2. 选择要导出的笔记本
3. 右键点击笔记本，选择"导出笔记"
4. 选择"HTML格式"，点击"导出"
5. 重复上述步骤，为每个笔记本创建单独的导出目录
6. 按照印象笔记中的层次结构，组织这些导出目录

### 2. 使用工具批量转换

1. 运行本工具，指定包含所有导出目录的根目录作为输入
2. 工具会自动递归处理所有子目录中的HTML文件
3. 转换后的Markdown文件会保持与原始导出目录相同的层次结构
4. 资源文件会被自动复制到每个Markdown文件对应的assets目录

### 3. 导入到思源笔记

1. 将转换后的输出目录（包含完整层次结构）压缩为ZIP文件
2. 打开思源笔记客户端
3. 选择"导入"功能
4. 选择"Markdown文件"或"ZIP文件"
5. 选择刚才创建的ZIP文件
6. 导入完成后，思源笔记会自动保留原始的目录层次结构

通过这种方式，您可以完整保留印象笔记中的笔记层次结构，实现平滑迁移到思源笔记。

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 基本用法

```bash
python html_to_md.py <input_dir>
```

- `<input_dir>`：包含HTML文件的输入目录
- 转换后的文件将默认输出到`out`目录

### 指定输出目录

```bash
python html_to_md.py <input_dir> --output <output_dir>
```

或者使用短选项：

```bash
python html_to_md.py <input_dir> -o <output_dir>
```

### 剔除_index.html文件

```bash
python html_to_md.py <input_dir> --exclude-index
```

这个选项会剔除所有后缀为`_index.html`的文件，不进行转换。

## 示例

### 示例1：基本转换

```bash
python html_to_md.py ./html_files
```

这将转换`./html_files`目录下的所有HTML文件，并将结果输出到`out`目录。

### 示例2：指定输出目录

```bash
python html_to_md.py ./html_files --output ./markdown_files
```

这将转换`./html_files`目录下的所有HTML文件，并将结果输出到`./markdown_files`目录。

### 示例3：剔除_index.html文件

```bash
python html_to_md.py ./html_files --exclude-index
```

这将转换`./html_files`目录下的所有HTML文件，但剔除所有后缀为`_index.html`的文件。

### 示例4：组合使用

```bash
python html_to_md.py ./html_files --output ./markdown_files --exclude-index
```

这将转换`./html_files`目录下的所有HTML文件（剔除`_index.html`文件），并将结果输出到`./markdown_files`目录。

## 资源文件处理

对于HTML文件中引用的资源文件（如图片、PDF等），程序会：

1. 在Markdown文件同目录下创建`assets`目录
2. 将资源文件从原始的`{html文件名}_files`目录复制到`assets`目录
3. 更新Markdown文件中的资源路径，指向`assets`目录
4. 为同名资源文件生成唯一文件名，避免覆盖

## 转换报告

转换完成后，程序会在输出目录中生成`conversion_report.html`文件（HTML格式），包含：

1. 转换文件对照表
2. 已剔除文件列表（如果使用了--exclude-index选项）
3. 原始资源文件汇总
4. 转换后资源文件汇总
5. 统计结果
6. 资源文件完整性检查（基于哈希值）
7. Markdown资源引用检查
8. 缺失资源文件报告

HTML格式的报告提供了更友好的视觉效果和交互体验，便于快速识别转换问题。

例如，原始HTML中的：
```html
<a href="PDF - file.ncnynl.com_files/CMake Practice.pdf"><img src="PDF - file.ncnynl.com_files/95fdf9da35d698ad55c0364657155d63.png" alt="CMake Practice.pdf"></a>
```

转换后Markdown中的：
```markdown
![CMake Practice.pdf](assets/95fdf9da35d698ad55c0364657155d63.png)
[CMake Practice.pdf](assets/CMake Practice.pdf)
```

## 注意事项

1. 确保原始HTML文件及其对应的`{html文件名}_files`目录在同一目录下
2. 程序会自动忽略不存在的资源文件
3. 转换过程中会保持原始的目录结构
4. 使用`--exclude-index`选项时，所有后缀为`_index.html`的文件都会被剔除，不进行转换
5. **特殊字符处理**：程序会自动处理文件名中的特殊字符和中文标点符号，确保资源文件在各种系统中都能正常使用
6. **alt属性修复**：自动处理包含方括号等特殊字符的图片alt属性，确保Markdown转换正确
7. **资源文件去重**：基于文件哈希值对资源文件进行智能去重，避免重复复制相同的资源
8. **准确的资源统计**：改进了资源文件统计逻辑，避免重复计数和错误统计，确保资源文件数量匹配
9. **路径转义处理**：优化了资源文件路径中的转义字符处理，确保链接正确

## 系统要求

- Python 3.6或更高版本
- 安装了所需的依赖包（beautifulsoup4和html2text）

## 命令行参数

| 参数 | 说明 |
|------|------|
| `<input_dir>` | 包含HTML文件的输入目录（必填） |
| `--output, -o` | 输出目录路径，默认是out |
| `--exclude-index` | 剔除后缀为_index.html的文件 |