Reference Exports

After the buildNavigation event is complete, the export files can be referenced. Since export files are stored in the content catalog under the export family, they can be addressed using a resource reference. They can also be referenced using the assembler property on any page that was included in an export, which is the preferred method.

assembler property

In order to create a link to an export from a page, it’s necessary to know which export is relevant for that page. That’s where the assembler property on the page comes in.

Assembler creates a direct reference between each page and the export in which it has been included. These references are available via the assembler property on the page file.

There are two ways to access the exports from this property. The first way is the exports property, which is an array of all exports. Each export entry is a map with the file and fragment properties. The second way is the <extname> property, which references the first entry in the exports array with the given extname (e.g., pdf).

Typically, the assembler property will be used in a UI template to create a link to the export from the page. For example:

{{#with (resolvePage page.relativeSrcPath model=false)}}
{{#each ./assembler.exports}}
<p><a href="{{{relativize ./file.pub.url}}}{{{./fragment}}}">{{{./file.assembler.backend}}}</a></p>
{{/each}}
{{/with}}

The assembler property is available on the raw file for the page, not the page UI model. Therefore, the resolvePage helper must be used to get a reference to the raw file. (In the future, you’ll be able to simplify this reference to page.file).

The ./fragment variable appends a URL fragment (# plus ID) that resolves to the current page within the export. This reference only works for certain formats, such as PDF.

If you know the export format you want to link to, and you’re only expecting a single export with that format, you can simplify this template by using the shorthand property.

{{#with (resolvePage page.relativeSrcPath model=false)}}
{{#with ./assembler.pdf}}
<p><a href="{{{relativize ./file.pub.url}}}{{{./fragment}}}">PDF</a></p>
{{/with}}
{{/with}}

If you do not have qualify_exports enabled in the Assembler configuration, and you want the browser to suggest a qualified filename, you can set the download attribute on the link to the value of the pub.download property.

{{#with (resolvePage page.relativeSrcPath model=false)}}
{{#with ./assembler.pdf}}
<p><a href="{{{relativize ./file.pub.url}}}" download="{{{./file.pub.download}}}">PDF</a></p>
{{/with}}
{{/with}}

When you use the download attribute, the deep link to the page within the export will no longer work (due to a browser limitation).

Resource reference

Assembler stores each export in the content catalog under the (non-standard) export family. Since these files are not added until after the pages have already been converted to HTML, they cannot be referenced using the AsciiDoc xref macro in a page. However, they can still be referenced using the content catalog in an extension or UI helper.

Here’s an example of how an export can be resolved using the ContentCatalog#resolveResource method.

const export = contentCatalog.resolveResource('version@name::export$index.pdf')

The reference must be fully qualified in this case since no context is provided. You can also access the exports from the collection of all files, or look up the export by ID.

Here’s an example of how an export can be retrieved using the ContentCatalog#getById method.

const export = contentCatalog.getById({
  component: 'name',
  version: 'version',
  module: 'ROOT',
  family: 'export',
  relative: 'index.pdf',
})