编目资源

由于 Asciidoctor 的主要重点是将文档高效地转换为其他格式，因此它不会尝试存储在处理文档时遇到的所有资产的信息。但是，此类信息对于分析文档或供扩展使用可能很有用。因此，Asciidoctor 提供了一个标志来目录特定的附加资产。本文档将介绍如何启用此目录以及如何访问它。

会编入目录的资产有哪些？

资产目录提供了一个按类型分组的精选资产表，这些资产在处理文档时被发现。此表存储在文档模型的 catalog 属性上。

启用此功能后，处理器会编入以下资产的目录

  • 链接（但不包括交叉引用） (键： :links)

  • 块级或内联图像 (键： :images)

无论此设置如何，处理器始终编入以下资产的目录

  • 块级或内联锚点 (键： :refs)

  • 脚注 (键： :footnotes)

总的来说，内联元素在转换之前不会被编入目录。因此，它们仅在文档被转换后可用，而在加载后不可用。但是，内联锚点是一个例外。

段落和列表项中的内联锚点在解析文档时会被编入目录。但是，对内联锚点的扫描发生在内联直通（passthrough）处理之前。因此，要转义内联锚点，您必须使用反斜杠而不是内联直通。

设置 :catalog_assets 选项

处理器是否对资产（特别是链接和图像）进行目录化是通过 API 使用 :catalog_assets 选项控制的。此选项的值是一个布尔值。如果值为 false（默认值），则不编入资产目录。如果值为 true，则编入资产目录。:catalog_assets 选项被所有 入口点方法（例如，Asciidoctor#load_file）接受。

以下是使用 API 时编入资产目录的示例

doc = Asciidoctor.convert_file 'doc.adoc', safe: :safe, catalog_assets: true

请注意，我们使用了 convert_file 方法而不是 load_file 方法。这确保内联资产也包含在目录中。

如果您在使用 CLI 时需要启用 :catalog_assets 选项，您需要引入以下扩展

示例 1. enable-catalog-assets-preprocessor.rb
Asciidoctor::Extensions.register do
  preprocessor do
    process do |doc, reader|
      doc.instance_variable_set :@options, ((doc.instance_variable_get :@options).merge catalog_assets: true)
      nil
    end
  end
end

既然您已经配置了处理器来编入资产目录，您就可以从文档对象中访问它们了。让我们来探索一下。

使用资产目录

已编入目录的资产可从文档模型（即解析后的文档）的 catalog 属性访问。目录是一个 Ruby 哈希。键是资产系列（例如，:links、:images 等）。每个键的值是一个资产数组。资产对象因系列而异。

让我们看一个如何从资产目录中访问链接、图像和引用的示例。

首先创建名为 doc.adoc 的以下 AsciiDoc 文件。

示例 2. doc.adoc
You can learn about Asciidoctor at https://docs.asciidoctor.org.cn.
The Asciidoctor source repo is hosted on https://github.com[GitHub].

image::screenshot.png[]

If you see image:green-check.png[], it means the job was successful.

现在，使用 Asciidoctor 并启用 :catalog_assets 选项来转换此文件

doc = Asciidoctor.convert_file 'doc.adoc', safe: :safe, catalog_assets: true

让我们看看处理器找到了哪些链接

links = doc.catalog[:links]
puts "Found #{links.size} links:"
puts links

您将看到以下输出

Found 2 links:
https://docs.asciidoctor.org.cn
https://github.com

:links 键的值是文档中找到的唯一 URL 的数组。条目不包含链接文本，仅包含 URL 本身。

:images

让我们在文档中添加一些图像。

示例 3. doc.adoc
//...

image::screenshot.png[]

If you see image:green-check.png[], it means the job was successful.

现在，使用 Asciidoctor 并启用 :catalog_assets 选项来转换此文件

doc = Asciidoctor.convert_file 'doc.adoc', safe: :safe, catalog_assets: true

让我们看看处理器找到了哪些图像

images = doc.catalog[:images]
puts "Found #{images.size} images:"
puts images

您将看到以下输出

Found 2 images:
screenshot.png
green-check.png

:images 键的值是文档中发现的图像（按出现顺序）的数组。虽然每个条目的值看起来像一个相对路径字符串，但实际上包含更多信息。

:images 集合中的每个条目都是一个 ImageReference 对象。打印时，此对象显示为相对路径字符串（这解释了观察到的行为）。ImageReference 包含以下属性

target

相对于 imagesdir 值而言的图像路径。

imagesdir

处理图像时 imagesdir 属性的值。

假设图像位于 images 文件夹中，并且我们相应地在文档中设置了 imagesdir 属性。

示例 4. doc.adoc
= Document Title
:imagesdir: images

//...

image::screenshot.png[]

If you see image:green-check.png[], it means the job was successful.

您可以通过以下方式打印图像的完整位置

images = doc.catalog[:images]
puts "Found #{images.size} images:"
docdir = doc.attr 'docdir'
puts images.map {|image| File.join docdir, image.imagesdir.to_s, image.target }

在输出中，图像引用将显示为绝对路径。

:refs

除了图像和链接，您还可以访问所有可定位的引用（即具有 ID 的元素）。首先，让我们在文档中添加一些可引用的元素。

= Document Title

== Quickstart

You can learn about Asciidoctor at https://docs.asciidoctor.org.cn.
The Asciidoctor source repo is hosted on https://github.com[GitHub].

.Screenshot
[#screenshot]
image::screenshot.png[]

== CI

If you see image:green-check.png[], it means the job was successful.

让我们看看处理器找到了哪些引用

refs = doc.catalog[:refs]
puts "Found #{refs.size} references:"
puts refs.keys

您将看到以下输出

Found 3 references:
_quickstart
screenshot
_ci

:refs 键的值是文档中找到的唯一引用的映射。键名是唯一 ID。值是这些 ID 所绑定的元素节点。节点的 API 取决于元素的类型。最常见的属性是节点的 reftext。

refs = doc.catalog[:refs]
puts "Found #{refs.size} references:"
puts refs.map {|id, node| %(#{node.context}: #{id} => #{node.xreftext || "[#{id}]"}) }

现在您将看到以下输出

Found 3 references:
section: _quickstart => Quickstart
image: screenshot => Screenshot
section: _ci => CI

您可以使用 refs 表来验证跨文档的深度交叉引用。