Metadata-Version: 2.4
Name: yakultpdf
Version: 0.8.8
Summary: Markdown to PDF converter using Pandoc and Typst
Author: mark2pdf contributors
License-Expression: MIT
Keywords: converter,markdown,pandoc,pdf,typst
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: click>=8.0.0
Requires-Dist: markdown-it-py
Requires-Dist: mdit-py-plugins
Requires-Dist: opencc
Requires-Dist: pillow
Requires-Dist: pymupdf
Requires-Dist: pyyaml
Provides-Extra: web
Requires-Dist: fastapi>=0.128.0; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.40.0; extra == 'web'
Description-Content-Type: text/markdown

# yakultpdf (mark2pdf)

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

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

> ⚠️ **注意**: 本项目在 PyPI 上包名为 `yakultpdf`，导入模块时使用 `mark2pdf`，命令行工具名为 `yakultpdf`。

## 系统依赖

**在安装之前，请确保已安装以下系统依赖**：

- [Pandoc](https://pandoc.org/installing.html) - 通用文档转换工具
- [Typst](https://typst.app/docs/installation/) - 现代排版系统

### macOS 安装
```bash
brew install pandoc typst
```

### Linux 安装
```bash
# Ubuntu/Debian
sudo apt-get install pandoc typst

# 或使用 cargo 安装 typst
cargo install typst-cli
```

## 🚀 快速开始

### 1. 安装

```bash
pip install yakultpdf
```

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

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

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

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

### 3. 开始转换

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

```bash
yakultpdf convert
```

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

### 4. 封面开关

默认不生成封面。

可以用三种方式开启：

```bash
# CLI 显式开启
yakultpdf convert test.md --with-cover
```

```toml
# mark2pdf.config.toml
[options]
withcover = true
```

```yaml
# frontmatter.yaml 或文件头
theme:
  withcover: true
```

优先级是：**CLI > 单文件 YAML 头 > frontmatter.yaml > config > 默认关闭**。  
只要显式传了 `--with-cover` 或 `--no-cover`，CLI 就会覆盖文件头、`frontmatter.yaml`、`disables: [cover]` 和 config。  
只有没传 CLI 时，`disables: [cover]` 才会按禁用处理。

### 5. 目录模式 title/image 自动注入

当使用 `yakultpdf convert --dir <目录>` 时：

- 会读取 `index.md` 与各子文件 frontmatter 的 `title` / `image`。
- `image` 会自动注入为 `topimage` 块：

```markdown
::: {#topimage}
images/cover.jpg
:::
```

- `title` 会自动注入为 H1 标题（`# 标题`）。
- 该行为仅在目录模式生效，默认开启。
- 如需关闭，在 `index.md` frontmatter 配置：

```yaml
disables:
  - title_injection
```

- 若只想关闭 `index` 的题图注入（保留 index 标题和子文件注入）：

```yaml
disables:
  - index_image
```

---

## 📚 文档导航

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

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

---

## ✨ 核心特性

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

## 🐍 Python API

也可以在 Python 代码中直接使用（注意导入模块名为 `mark2pdf`）：

```python
from mark2pdf import convert_file, convert_directory

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

# 目录转换（合并目录下所有 Markdown）
convert_directory("docs", output_file="merged_report.pdf")
```
