Metadata-Version: 2.5
Name: yakultpdf
Version: 0.10.1
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

YakultPDF 是一个基于 Pandoc 和 Typst 的 Markdown → PDF 工具库和命令行程序，面向中文报告、书籍、稿纸和 3:4 练习页。

- PyPI 包名：`yakultpdf`
- 命令行：`yakultpdf`
- Python 导入名：`mark2pdf`

```text
Markdown + 配置 → YakultPDF / Pandoc → Typst 模板 → PDF
```

## 系统要求

- Python 3.11+
- Pandoc
- Typst

完整安装方法见[安装指引](docs/07.安装指引.md)。

## 快速开始

安装 Python 包：

```bash
uv tool install yakultpdf
```

确认三个组件可用：

```bash
yakultpdf --version
pandoc --version
typst --version
```

准备 `demo.md`：

```markdown
# 我的第一份 PDF

这是由 YakultPDF 生成的文档。
```

转换并使用输入文件名作为输出名：

```bash
yakultpdf convert demo.md --force-filename
```

独立模式会在当前目录生成 `demo.pdf`。更多内容见[快速开始](docs/00.快速开始.md)。

## 工作区

长期项目建议初始化工作区：

```bash
yakultpdf init my-docs
cd my-docs
yakultpdf convert index.md
```

工作区使用 `mark2pdf.config.toml` 管理输入、输出、模板和字体，PDF 默认写入 `out/`。

```toml
[paths]
in = "."
out = "out"
tmp = "tmp"
template = "template"
fonts = "fonts"

[options]
default_template = "nb"
withcover = false
overwrite = false
```

配置、Frontmatter 和封面规则见[配置指南](docs/03.配置指南.md)。

## 主要能力

- 单文件、目录合并和批量转换
- 工作区本地模板、字体和资源管理
- NB 模板的封面、目录、背景页、整页图片和 Mermaid
- 远程图片下载与 Markdown 资源结构迁移
- 简繁转换和 PDF 压缩
- classic / small 中文稿纸
- 简洁版和精装版 Worksheet 练习页
- Python API

## 文档

完整入口：[YakultPDF 用户文档](docs/index.md)。

| 文档 | 内容 |
| --- | --- |
| [工作区使用指南](docs/01.工作区使用指南.md) | 目录、资源和常用工作流 |
| [CLI 命令参考](docs/02.CLI使用说明.md) | 当前命令与参数 |
| [配置指南](docs/03.配置指南.md) | TOML、Frontmatter、模板和封面 |
| [NB 模板语法](docs/04.模板语法指南.md) | 页面和组件扩展 |
| [稿纸模式](docs/09.稿纸模式.md) | classic、small 和着重号 |
| [Worksheet 模板](docs/08.Worksheet模板.md) | 五种练习页版式 |
| [Python API](docs/10.Python_API.md) | 程序化转换 |
| [Docker 与 Web 服务](docs/06.docker版使用说明.md) | 容器部署 |

## Python API

```python
from mark2pdf import convert_file
from mark2pdf.core import ConversionOptions

result = convert_file(
    "input.md",
    output_file="output.pdf",
    options=ConversionOptions(overwrite=True, force_filename=True),
)
```

完整签名和目录转换示例见[Python API 文档](docs/10.Python_API.md)。

## 开发与测试

```bash
uv sync
uv run pytest
```

项目架构见 [DEVELOPMENT.md](DEVELOPMENT.md)，发布流程见 [RELEASING.md](RELEASING.md)。Agent 规则见 [AGENTS.md](AGENTS.md)。

## License

MIT
