Catalog Assets

Since Asciidoctor’s primary focus is on converting documents efficiently, it does not attempt to store information about all assets it comes across while processing the document. However, such information can be useful for analyzing the document or for use in extensions. Therefore, Asciidoctor provides a flag to catalog certain additional assets. This page explains how to enable this catalog and how to access it.

What assets are cataloged?

The asset catalog provides a table of select assets grouped by type that are discovered while processing the document. This table is stored on the catalog property of the document model.

When this feature is enabled, the processor catalogs the following assets:

  • links (but not xrefs) (key: :links)

  • block or inline images (key: :images)

The processor always cataloged the following assets, regardless of this setting:

  • block or inline anchors (key: :refs)

  • footnotes (key: :footnotes)

Generally speaking, inline elements are not cataloged until conversion. Therefore, they’re only available after the document has been converted, not after it has been loaded. However, inline anchors are an exception.

Inline anchors in paragraphs and list items are cataloged when the document is parsed. However, the scan for inline anchors happens before inline passthroughs are processed. Therefore, to escape an inline anchor, you must use a backslash instead of an inline passthrough.

Set :catalog_assets option

Whether the processor catalogs assets (specifically links and images) is controlled from the API using the :catalog_assets option. The value of this option is a boolean. If the value is false (default), assets are not cataloged. If the value is true, assets are cataloged. The :catalog_assets option is accepted by all entrypoint methods (e.g., Asciidoctor#load_file).

Here’s an example of how to catalog assets when using the API:

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

Notice that we’ve used the convert_file method instead of the load_file method. This ensures that inline assets are included in the catalog as well.

If you need to enable the :catalog_assets option when using the CLI, you’ll need to require the following extension:

Example 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

Now that you’ve configured the processor to catalog assets, you can access them from the document object. Let’s explore it.

Use the asset catalog

Assets which have been cataloged are available from the catalog property on the document model (i.e., the parsed document). The catalog is a Ruby hash. The keys are the asset families (e.g., :links, :images, etc). The value of each key is an array of assets. The asset object varies by family.

Let’s look at an example of how to access links, images, and refs from the asset catalog.

Start by creating the following AsciiDoc file named doc.adoc.

Example 2. doc.adoc
You can learn about Asciidoctor at https://docs.asciidoctor.org.
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.

Now, convert this file using Asciidoctor with the :catalog_assets option enabled:

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

Let’s see what links the processor found:

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

You’ll see the following output:

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

The value of the :links key is an array of unique URLs found in the document. The entry does not include the link text, only the URL itself.

:images

Let’s add some images to the document.

Example 3. doc.adoc
//...

image::screenshot.png[]

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

Now, convert this file using Asciidoctor with the :catalog_assets option enabled:

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

Let’s see what images the processor found:

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

You’ll see the following output:

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

The value of the :images key is an array of images (by occurrence) found in the document. While it looks like the value of each entry is a relative path string, there’s actually more information there.

Each entry in the :images collection is an ImageReference object. This object appears as a relative path string when printed (which explains the observed behavior). An ImageReference contains the following properties:

target

The image path relative to the value of imagesdir.

imagesdir

The value of the imagesdir attribute at the time the image was processed.

Let’s assume the images are located in the images folder, and we have set the imagesdir attribute on the document accordingly.

Example 4. doc.adoc
= Document Title
:imagesdir: images

//...

image::screenshot.png[]

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

You can print the full location to the images as follows:

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 }

In the output, the image references will be shown as absolute paths.

:refs

In addition to images and links, you can also access all targetable references (i.e., elements that have an ID). First, let’s add some referenceable elements to our document.

= Document Title

== Quickstart

You can learn about Asciidoctor at https://docs.asciidoctor.org.
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.

Let’s see what references the processor found:

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

You’ll see the following output:

Found 3 references:
_quickstart
screenshot
_ci

The value of the :refs key is a map of unique references found in the document. The key names are the unique IDs. The values are the element nodes to which these IDs are bound. The API for the node depends on the type of element. The most common property is the reftext of the node.

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

Now you’ll see the following output:

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

An idea of something you can do with the refs table is validate deep xrefs across documents.