Gimli 技术文档

Gimli 是一个将标记语言转换为 PDF 文件的实用工具，特别适用于生成报告等文档。它支持多种标记语言，并提供了语法高亮功能。本文将详细介绍如何安装、使用 Gimli，以及如何通过 API 进行文档转换。

1. 安装指南

通过 RubyGems 安装

推荐使用 RubyGems 安装 Gimli：

$ [sudo] gem install gimli

从源码安装

如果你想从源码安装 Gimli，可以按照以下步骤操作：

$ cd gimli/
$ bundle
$ rake install

在 Windows 上安装

在 Windows 系统上使用 Gimli 需要额外安装 wkhtmltopdf 和 which 工具：

1. 安装 wkhtmltopdf：

   • 从 wkhtmltopdf 官网 下载并安装。
   • 确保 wkhtmltopdf.exe 的路径已添加到系统的 $PATH 环境变量中，并且位于 Ruby 目录之前。

2. 安装 which 命令：

   • 从 GnuWin32 下载并安装 which 工具。
   • 确保 which.exe 的路径已添加到系统的 $PATH 环境变量中。

2. 使用说明

基本使用

在包含标记文件的目录中运行以下命令：

$ gimli

Gimli 会将当前目录下的所有标记文件转换为 PDF 文件。

自定义样式

你可以通过添加 gimli.css 文件来自定义 PDF 的样式，或者使用 -s 参数指定其他 CSS 文件：

$ gimli -s /path/to/custom.css

指定输出目录

默认情况下，Gimli 会在当前目录下生成 PDF 文件。你可以使用 -o 参数指定输出目录：

$ gimli -o /path/to/output

处理 Jekyll 文件

如果你的标记文件包含 Jekyll 的 YAML 前端内容，可以使用 -y 参数移除这些内容：

$ gimli -y

添加封面

你可以通过 -cover 参数为文档添加封面：

$ gimli -f doc-file.md -cover cover-file.md

传递 wkhtmltopdf 参数

使用 -w 参数可以直接传递参数给 wkhtmltopdf，例如添加目录和页脚：

$ gimli -f test.md -w '--toc --footer-right "[page]/[toPage]"'

使用 Docker 容器

Gimli 提供了 Docker 容器，可以在不安装 Gimli 的情况下进行文件转换：

$ docker run -v <host_dir>:<container_dir> walle/gimli -f <container_dir>/my-file.md -o <container_dir>

其中 <host_dir> 是包含待转换文件的目录，<container_dir> 是容器内的目录。

3. API 使用文档

Gimli 提供了命令行接口，可以通过命令行参数进行配置。以下是常用的参数：

• -f：指定要转换的标记文件。
• -o：指定输出目录。
• -s：指定自定义样式表。
• -y：移除 Jekyll 的 YAML 前端内容。
• -cover：指定封面文件。
• -w：传递参数给 wkhtmltopdf。

4. 项目安装方式

Gimli 可以通过 RubyGems 或源码安装，具体步骤见 安装指南。

依赖项

Gimli 依赖于以下工具：

• wkhtmltopdf：用于将 HTML 转换为 PDF。
• which：用于查找 wkhtmltopdf 的路径。

确保这些工具已正确安装并配置。

语法高亮

Gimli 支持语法高亮，使用以下语法：

def foo
  puts 'bar'
end

代码块必须以三个反引号开头，后跟语言名称。支持的语法高亮语言列表请参考 coderay。

---

通过本文档，你应该能够顺利安装、配置并使用 Gimli 进行文档转换。如有任何问题，请参考官方文档或社区支持。