Resources and Resource IDs

What’s a resource?

A resource is a source file that belongs to the pages, images, partials, examples, or attachments family. Antora assigns each resource a unique identifier called an Antora resource ID.

What’s a publishable resource?

A publishable resource is a source file that belongs to the pages, attachments, or images family. Antora automatically publishes page, attachment, and image files to your site, even if they aren’t referenced in another resource. This is in contrast to partial and example files. The content of a partial or example is only published if it’s referenced—either directly or by way of another partial or example that is eventually referenced—from a publishable resource.

What’s a resource ID?

An Antora resource ID, or resource ID for short, is a unique and reliable set of identifying coordinates, organized in a standard sequence, that Antora automatically constructs from the properties assigned to each resource’s source file. You’ll often use the resource ID of a resource to reference it from another resource. A resource is referenced by assigning its resource ID to an AsciiDoc xref macro, include directive, image macro, or the few keys, attributes, or options that accept a resource ID as a value. Antora then uses the assigned resource ID to look up the corresponding resource in its virtual file system. Resource ID Coordinates describes the coordinates in a resource ID, where you find a resource’s coordinates, and when you use each of the coordinates.

Why are resource IDs important?

They’re not coupled to a published URL because they’re a source-to-source reference. Notice the page coordinate ends with .adoc, the file extension of an AsciiDoc source file. Regardless of whether you’re deploying your site locally, to a staging or production environment, or you change URL strategies, the resource ID always remains the same. The xref locks on to the target page and produces a URL that points to it wherever it gets published.

They’re minimally coupled to the filesystem by using an identifier based on the Antora’s virtual component version classification system.

They’ve eliminated the relative path (../../) problem by specifying the resource as a family-relative directory path. The path always starts from a family directory, even when the referencing resource is located inside a subdirectory of the family directory.

This human-friendly referencing system saves you from having to do computations in your head while writing. You just specify the coordinates of the page you want to reference. There’s no need to worry about the source file’s physical location on disk or its published URL. All you need to know are the names of your components, versions, modules, and pages so you can fill in this information.

Duplicate resources

Antora does not permit two resources (i.e., source files) to share the same resource ID. This situation can occur under the following conditions:

the antora.yml file in more than one content source root declares the same name and version
both content source roots have at least one file located at the same relative path (beginning from the start path)
the conflicting files are both collected and classified by Antora

If this situation occurs, Antora will report the conflicting files by logging a fatal error and immediately stop building the site.

Which error you see depends on the order in which files are discovered. If both component versions declare navigation files, you’ll likely see a duplicate nav file error:

Duplicate nav in 1.0@name-of-component: modules/ROOT/nav.adoc
    1: modules/ROOT/nav.adoc in https://git-host/repo-name.git (branch: v1.0.x)\n' +
    2: modules/ROOT/nav.adoc in https://git-host/repo-name.git (tag: v1.0.0)'

Otherwise, you’ll see an error about a duplicate page or other resource:

Duplicate page: modules/ROOT/index.adoc in 1.0@name-of-component
    1: modules/ROOT/nav.adoc in https://git-host/repo-name.git (branch: v1.0.x)\n' +
    2: modules/ROOT/nav.adoc in https://git-host/repo-name.git (tag: v1.0.0)'

What this error is telling you is that two files are trying to claim the same resource ID. This could indicate you have a redundant content source root configured in your playbook or that you’ve forgetten to update the version key in one of the antora.yml files. Study the git references that Antora cites to discover the cause.

If you’re attempting to define a distributed component version, in which case the antora.yml will declare the same name and version, then you need to remove the conflicting file from one of the two roots so there’s no overlap.