如何使用 Asciidoctor PDF：从安装到生成专业文档的完整指南

【免费下载链接】asciidoctor-pdf :page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby. 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor-pdf

Asciidoctor PDF 是一个基于 Asciidoctor 和 Prawn 的原生 PDF 转换器，用 Ruby 编写，能将 AsciiDoc 文档转换为高质量的 PDF 文件。本文将为新手和普通用户提供一份全面的指南，帮助你快速上手并充分利用这个强大的工具。

核心功能概览 🚀

Asciidoctor PDF 提供了丰富的功能，让你轻松创建专业的 PDF 文档：

• 原生转换：直接将 AsciiDoc 文档转换为 PDF，无需中间格式
• 自定义主题：通过 data/themes/ 目录下的主题文件，定制文档的外观和风格
• 丰富的格式化选项：支持标题、列表、表格、代码块等多种元素的格式化
• 图片支持：轻松插入和管理各种格式的图片
• 多语言支持：支持多种语言的文档生成

安装步骤 📦

准备工作

在安装 Asciidoctor PDF 之前，确保你的系统已经安装了 Ruby 和 RubyGems。如果尚未安装，可以按照以下步骤操作：

# Ubuntu/Debian
sudo apt-get install ruby ruby-dev

# macOS (使用 Homebrew)
brew install ruby

安装 Asciidoctor PDF

使用以下命令安装 Asciidoctor PDF：

gem install asciidoctor-pdf --pre

如果你想从源代码构建，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/as/asciidoctor-pdf
cd asciidoctor-pdf
bundle install

快速上手：创建你的第一个 PDF 🚀

准备 AsciiDoc 文件

创建一个简单的 AsciiDoc 文件，例如 basic-example.adoc，内容如下：

= 我的第一个 Asciidoctor PDF 文档
作者名称
v1.0, 2023-01-01

== 介绍

这是一个使用 Asciidoctor PDF 创建的简单文档。

== 主要内容

Asciidoctor PDF 可以轻松将 AsciiDoc 文档转换为专业的 PDF 文件。

[source,ruby]
----
puts "Hello, Asciidoctor PDF!"
----

== 结论

希望这个简单的示例能帮助你开始使用 Asciidoctor PDF。

转换为 PDF

使用以下命令将 AsciiDoc 文件转换为 PDF：

asciidoctor-pdf basic-example.adoc

转换完成后，你将得到一个名为 basic-example.pdf 的文件。

自定义 PDF 外观 🎨

Asciidoctor PDF 允许你通过主题文件自定义 PDF 的外观。主题文件位于 data/themes/ 目录下，你可以根据需要修改现有主题或创建新主题。

使用内置主题

Asciidoctor PDF 提供了多个内置主题，例如：

• default-theme.yml：默认主题
• default-sans-theme.yml：无衬线字体主题
• default-for-print-theme.yml：适合打印的主题

要使用特定主题，可以在转换时指定：

asciidoctor-pdf -a pdf-theme=default-sans-theme.yml basic-example.adoc

创建自定义主题

你可以通过复制现有主题并修改来创建自己的主题。例如，创建一个名为 my-theme.yml 的文件：

extends: default-theme.yml

page:
  size: A4
  margin: [1in, 1in, 1in, 1in]

base:
  font-family: Noto Sans
  font-size: 12
  line-height: 1.5

然后使用自定义主题：

asciidoctor-pdf -a pdf-theme=my-theme.yml basic-example.adoc

高级功能探索 🔍

添加水印

Asciidoctor PDF 支持为 PDF 添加水印。你可以使用 spec/fixtures/watermark.png 作为水印图片，通过主题文件配置：

page:
  background-image: image:watermark.png
  background-image-opacity: 0.2
  background-image-position: center

双面打印支持

对于需要双面打印的文档，Asciidoctor PDF 提供了对左右页面（recto/verso）的支持。你可以在主题中为左右页面设置不同的背景：

page:
  recto-background-image: image:recto-bg-landscape.png
  verso-background-image: image:verso-bg-landscape.png

表格和图表

Asciidoctor PDF 支持创建复杂的表格和图表。你可以使用 AsciiDoc 的表格语法创建表格，并通过主题自定义表格样式：

[cols="2*,3*", options="header"]
|===
| 功能 | 描述
| 原生转换 | 直接将 AsciiDoc 转换为 PDF
| 自定义主题 | 通过 YAML 文件定制外观
| 多语言支持 | 支持多种语言的文档
|===

总结

Asciidoctor PDF 是一个功能强大的工具，能够帮助你轻松创建专业的 PDF 文档。通过本文的指南，你已经了解了如何安装、使用和自定义 Asciidoctor PDF。无论你是需要创建技术文档、报告还是电子书，Asciidoctor PDF 都能满足你的需求。

如果你想深入了解更多功能，可以查阅项目的官方文档，探索 docs/ 目录下的详细资料。开始使用 Asciidoctor PDF，体验高效、专业的文档生成过程吧！

【免费下载链接】asciidoctor-pdf :page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby. 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor-pdf