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.