# 工作区使用指南

本文档说明如何在独立工作区（如 `my-docs`）中使用 **yakultpdf**。

确保你已完成安装（参考 [快速开始](00.快速开始.md)），终端中可以直接运行 `yakultpdf` 命令。

> 📖 **相关阅读**
> - 完整命令参数请查阅 [CLI 使用说明](./02.CLI使用说明.md)
> - 详细配置项请查阅 [配置指南](./03.配置指南.md)

---

## 1. 建立工作区

### 初始化

建议为每个项目创建一个独立的目录：

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

### 标准目录结构

初始化后，推荐的目录结构如下：

```text
my-docs/
├── mark2pdf.config.toml    # [核心] 配置文件
├── frontmatter.yaml        # [核心] 默认元数据
├── index.md                # [文档] 可以在根目录直接编写
├── chapter1.md             # [文档] 其他章节
├── images/                 # [资源] 图片建议统一存放于此
├── out/                    # [输出] PDF 默认输出位置
├── template/               # [可选] 自定义模板文件
└── fonts/                  # [可选] 自定义字体文件
```

---

## 2. 常用操作

### 转换文档

最常用的操作。在工作区根目录下：

```bash
# 默认转换 (通常是 index.md)
yakultpdf convert

# 转换指定文件
yakultpdf convert chapter1.md

# 转换当前目录所有 .md 文件并合并
yakultpdf convert --dir .
```

### 图片处理

如果你的 Markdown 包含网络图片（如微信公众号文章），先下载到本地：

```bash
yakultpdf mdimage download article.md
```

### 安装字体

安装常用的开源中文字体：

```bash
# 列出可用字体
yakultpdf fonts list

# 安装霞鹜文楷
yakultpdf fonts install lxgw-wenkai
```

---

## 3. 最佳实践

### 图片管理
- **存放位置**: 推荐在根目录建立 `images/` 文件夹。
- **引用格式**: 在 Markdown 中使用 `![](images/pic.jpg)`。

### 配置文件
- **mark2pdf.config.toml**: 定义项目的输入输出路径和默认模板。

```toml
[project]
name = "我的文档"

[paths]
input = "."     # 源文件在当前目录
output = "out"  # PDF 输出到 out 目录
```

### 为什么使用工作区？
相比直接使用 CLI，工作区模式通过配置文件 (`config.toml`) 和 `frontmatter.yaml` 固定了项目参数，让你无需每次输入繁琐的命令行选项，保证输出的一致性。
