PDF Composer

使用Yaml Front Matter文档生成PDF的Rust库

概述

此库可以从YAML Front Matter源文档创建PDF文档。YAML值可以用于PDF字典条目或用于替换YAML Front Matter文档Markdown部分的占位符引用。

特性

PDF输出目标

生成的PDF保存到项目根目录相对路径的输出目标目录。

例如，my_pdf_instance.set_output_directory("output_pdfs")。如果没有设置输出目标，则PDF将保存在名为pdf_composer_pdfs的目录中。这样可以避免在项目根目录中产生过多的生成PDF文件。整洁有序。

PDF版本

目前仅支持最新的两个PDF规范版本（并推荐使用），即版本1.7和2.0。

例如，my_pdf_instance.set_pdf_version(PDFVersion::V2_0)。如果没有设置PDF版本，则默认使用版本1.7。

注意： 这不是指PDF本身的版本/版本号。这是由你决定的（也许可以将其设置为YAML值，作为PDF字典条目的一部分，详见下文更多信息）。

要设置版本，请查看显示相应枚举和版本号的表格。

纸张大小

支持纸张大小的列表。例如，my_pdf_instance.set_paper_size(PaperSize::A5)。如果没有设置纸张大小，纸张大小默认为A4。

ISO 216 A系列纸张大小

ISO 216 B系列纸张大小

美国纸张大小

JIS纸张大小

纸张方向

这允许将PDF文档页面保存为横向或纵向方向。例如，my_pdf_instance.set_orientation(PaperOrientation::Landscape)。如果没有设置方向，默认为Portrait。

页面边距

边距的单位是毫米（mm）。如果没有设置边距，默认边距大小为10。

使用CSS缩写符号设置页面边距（上 右 下 左）。这意味着

设置一个值，则四个边距都将获取该值。例如，my_pdf_instance.set_margins("20") 将产生以下结果

• margin-top: 20,
• margin-right: 20,
• margin-bottom: 20,
• margin-left: 20

设置两个值，则顶部和底部边距将获取第一个值，右侧和左侧边距将获取第二个值。例如，my_pdf_instance.set_margins("20 15") 将产生以下结果

• margin-top: 20,
• margin-right: 15,
• margin-bottom: 20,
• margin-left: 15

设置三个值，则顶部边距将获取第一个值，右侧和左侧边距将获取第二个值，底部边距将获取第三个值。例如，my_pdf_instance.set_margins("20 15 30") 将产生以下结果

• margin-top: 20,
• margin-right: 15,
• margin-bottom: 30,
• margin-left: 15

设置四个值，则顶部边距将获取第一个值，右侧边距将获取第二个值，底部边距将获取第三个值，左侧边距将获取第四个值。例如，my_pdf_instance.set_margins("20 15 30 5") 将产生以下结果

• margin-top: 20,
• margin-right: 15,
• margin-bottom: 30,
• margin-left: 5

如果设置了其他值（或非整数数字、字母、字符等），则每个边距将使用默认值 10。

页面字体

PDF文档可以使用14种标准字体之一。这些是

例如，my_pdf_instance.set_font(FontsStandard::TimesRoman)。如果没有设置字体，默认字体为 Helvetica。

PDF字典条目

PDF字典条目是您在PDF阅读器中选择“文档属性”时可以看到的名称和值对。字典条目区分大小写，有一些保留名称。

保留字典条目

• 标题
• 作者
• 主题
• 关键词

这些 必须 大写。 PDF Composer 只会自动将保留名称大写。其他名称将保持原样。

在 PDF Composer 中，标题输入是一个特殊情况。在 PDF 生成过程中，YAML 文档中的 title 值会自动插入到 HTML 模板中用于的 <title> 标签中。因此，字典条目将被填充。如果没有找到 YAML 值，则将使用源文件的文件名代替。

不允许有空条目。如果找不到相应的 YAML 条目，则不会将空条目添加到 PDF 文档中。

例如，如果您想设置一个名为 Language 的字典条目，并将其设置为一个在 YAML 文档中不存在的 YAML 条目，则 PDF Composer 不会创建空条目。

设置字典条目的示例

PDFDocInfoEntry {
    doc_info_entry: "Subject",
    yaml_entry: "description",
}

doc_info_entry 是 PDF 字典条目。

yaml_entry 是将被分配给字典条目的 YAML 值。

YAML Markdown 占位符替换

在 YAML 文档的 markdown 部分中可以进行简单的替换。这是通过在 markdown 部分中使用 {{my_yaml_value}} 实现的。

示例

---

# Front Matter (YAML)

author: "Richard"

---

The author of this document is {{author}}.

结果将是： The author of this document is Richard.

如果找不到 YAML 值，则替换占位符将保留在生成的输出中。

示例

---

# Front Matter (YAML)

author: "Richard"

---

The author of this document is {{name}}.

结果将是： The author of this document is {{name}}.

use pdf_composer::{FontsStandard, PaperOrientation, PaperSize, PDFComposer, PDFDocInfoEntry, PDFVersion};

// Create a new PDFComposer instance
let mut my_pdf_instance = PDFComposer::new();

// Add some paths. Relative paths
let paths = vec![
    PathBuf::from("source_mds/file_01.md"),
    PathBuf::from("source_mds/file_02.md")
];
my_pdf_instance.add_source_files(paths);

// PDF version (not the version of the document, but the Adobe (formerly) PDF format version)
my_pdf_instance.set_pdf_version(PDFVersion::V2_0);

// Output directory for the generated PDFs
my_pdf_instance.set_output_directory("example_pdfs");

// Set the paper size
my_pdf_instance.set_paper_size(PaperSize::A5);

// Set the paper orientation
my_pdf_instance.set_orientation(PaperOrientation::Landscape);

// Set the page margins
my_pdf_instance.set_margins("20");

// Set font
my_pdf_instance.set_font(FontsStandard::TimesRoman);

// Metadata for the PDFs
let author_entry = PDFDocInfoEntry {
    doc_info_entry: "Author",
    yaml_entry: "author",
};
let keywords_entry = PDFDocInfoEntry {
    doc_info_entry: "Keywords",
    yaml_entry: "keywords",
};
let subject_entry = PDFDocInfoEntry {
    doc_info_entry: "Subject",
    yaml_entry: "description",
};
let language_entry = PDFDocInfoEntry {
    doc_info_entry: "Language",
    yaml_entry: "language",
};
my_pdf_instance.set_doc_info_entry(author_entry);
my_pdf_instance.set_doc_info_entry(keywords_entry);
my_pdf_instance.set_doc_info_entry(subject_entry);
my_pdf_instance.set_doc_info_entry(language_entry);

// Generate the PDF(s)
my_pdf_instance.generate_pdfs();