Asciidoctor Web PDF 使用教程

Asciidoctor Web PDF 使用教程

asciidoctor-web-pdf Convert AsciiDoc documents to PDF using web technologies 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor-web-pdf

1. 项目介绍

Asciidoctor Web PDF 是一个基于 Web 技术的 AsciiDoc 文档转换为 PDF 的工具。它允许用户使用 CSS 和 JavaScript 定义复杂的布局，同时使用 AsciiDoc 编写内容。该项目支持 LaTeX 风格的数学公式（通过 MathJax）和语法高亮（通过 highlight.js），并且可以通过导入现有的 JavaScript 或 CSS 框架来添加更多功能。

主要特点

• 使用 CSS 和 JavaScript 实现复杂布局
• 支持 SVG 图标（如 Font Awesome 5）
• 生成 PDF 文档大纲（书签）
• 支持文档元数据（标题、作者、主题、关键词等）
• 完全可定制的模板
• 语法高亮支持（通过 Highlight.js）
• 页面编号
• 预览模式
• STEM 支持（通过 MathJax 3）

2. 项目快速启动

安装

使用预编译二进制文件

1. 访问 Releases 页面 下载适用于您平台的二进制文件（在“Assets”下）。
2. 解压到您选择的文件夹。
3. 在命令行中运行 asciidoctor-web-pdf 命令。

使用 npm 安装

1. 安装 Node.js（推荐使用 nvm 安装）。

   $ nvm install --lts
   

2. 在项目目录中安装 Asciidoctor Web PDF。

   $ npm init -y
   $ npm i @asciidoctor/core asciidoctor-pdf --save-dev
   

3. 验证安装是否成功。

   $ npx asciidoctor-web-pdf --version
   

使用 Docker

1. 运行以下命令验证安装。

   $ docker run --rm ggrossetie/asciidoctor-web-pdf --version
   

2. 渲染示例文档。

   $ docker run -i --rm \
     --volume=$PWD/examples/cheat-sheet:"/usr/app" \
     -u $(id -u $USER):$(id -g $USER) \
     ggrossetie/asciidoctor-web-pdf:latest \
     --template-require /snyk/template.js maven-security-cheat-sheet.adoc
   

3. 应用案例和最佳实践

应用案例

• 技术文档生成：使用 Asciidoctor Web PDF 生成技术文档，支持复杂的布局和样式。
• 简历生成：通过自定义 CSS 生成专业的简历 PDF。
• 幻灯片生成：将 AsciiDoc 文档转换为 PDF 幻灯片。

最佳实践

• 使用自定义样式表：通过 stylesheet 属性提供自定义 CSS 文件，完全替换默认样式。

  $ asciidoctor-web-pdf document.adoc -a stylesheet="custom.css"
  

• 启用 STEM 支持：在文档头部设置 stem 属性以启用数学公式支持。

  $ asciidoctor-web-pdf document.adoc -a stem
  

4. 典型生态项目

• Asciidoctor：Asciidoctor 是一个快速文本处理器和发布工具链，用于将 AsciiDoc 文档转换为 HTML5、PDF 和其他格式。
• Paged.js：Paged.js 是一个用于分页媒体的开源库，Asciidoctor Web PDF 使用它来准备文档以进行 PDF 渲染。
• MathJax：MathJax 是一个用于在 Web 上显示数学公式的开源 JavaScript 库，Asciidoctor Web PDF 使用它来支持 LaTeX 风格的数学公式。

通过这些工具和项目的结合，Asciidoctor Web PDF 提供了一个强大且灵活的解决方案，用于将 AsciiDoc 文档转换为高质量的 PDF 文件。

asciidoctor-web-pdf Convert AsciiDoc documents to PDF using web technologies 项目地址: https://gitcode.com/gh_mirrors/as/asciidoctor-web-pdf