# mark2pdf (yakultpdf)

**基于 Pandoc 和 Typst 的 Markdown 转 PDF 专业工具链**

Mark2pdf 是一个强大的文档转换工具，旨在将 Markdown 文件转换为排版精美的 PDF 文档。它支持类似 Hugo/Jekyll 的工作区管理、Frontmatter 配置以及高度可定制的 Typst 模板系统。

> ⚠️ **注意**: 本项目在 PyPI 上包名为 `markdown2pdf`，但命令行工具名为 `mark2pdf`。

## 🚀 快速开始

### 1. 安装

```bash
pip install markdown2pdf
```

### 2. 初始化工作区 (推荐)

我们强烈建议使用**工作区模式**来管理你的文档项目：

```bash
mkdir my-docs && cd my-docs
mark2pdf init .
```

这将创建标准目录结构 (`in/`, `out/`, `mark2pdf.config.toml` 等)。

### 3. 开始转换

将 Markdown 文件放入 `in/` 目录，然后运行：

```bash
mark2pdf convert
```

生成的 PDF 将出现在 `out/` 目录中。

---

## 📚 文档导航

所有详细文档均位于 [./docs](./docs) 目录：

- **入门必读**: [💪 工作区使用指南](docs/工作区使用指南.md) - 最佳实践、环境配置与工作流。
- **命令手册**: [🛠 CLI 使用说明](docs/CLI使用说明.md) - 所有命令参数详解。
- **配置参考**: [⚙️ 配置指南](docs/配置指南.md) - `config.toml` 与 Frontmatter 参数全解。
- **模板语法**: [🎨 模板语法指南](docs/模板语法指南.md) - 如何使用高级排版特性（NB模板）。
- **架构说明**: [🏗 项目说明文档](docs/项目说明文档.md) - 开发者视角的设计文档。
- **常见问题**: [❓ FAQ](docs/FAQ.md) - 疑难解答。

---

## ✨ 核心特性

- **工作区管理**: 自动管理输入输出路径、模板与资源。
- **智能图片处理**: 自动下载远程图片、微信公众号图片修复、本地路径重写。
- **混合排版**: 支持标准 Markdown 与 Typst 语法混合使用。
- **多模式转换**: 支持单文件转换、目录合并转换、批量转换。
- **中文优化**: 内置简繁转换、常用中文字体下载与管理。
- **稿纸模式**: 特有的 `gaozhi` 转换器，生成书写练习稿纸。

## 🐍 Python API

也可以在 Python 代码中直接使用：

```python
from markdown2pdf import convert_file

# 单文件转换
convert_file("input.md", output_file="output.pdf")
```
