Cross References

To create a link between policy documents, use the cross reference macro, which is commonly called the xref macro or simply xref.

AsciiDoc xref macro

An xref macro consists of the macro’s prefix (xref:), the resource ID of the target document, and a set of square brackets ([]).

Xref that creates a link to SNAP Policy 3320 from SNAP Policy 3035
Refer to xref:3320.adoc[Section 3320, Citizenship/Alien Status], for policy on how to determine eligibility for citizens and aliens.

The target document is the file in the pages or attachments folder that’s being referenced by the current document. The target document is referenced by assigning its resource ID to an xref macro in the content of the current document. The current document is the document file containing the xref macro that references the target document. The number of resource ID coordinates you need to specify in the xref depends on the location of the current document in relation to the location of the target document (i.e., the page or attachment you want to link to). The closer the two files are, the shorter the resource ID. Ninety-nine out of 100 times, you’ll want to create a link to document that belongs to the same module as the current document.

In the example above is an xref to a SNAP document (Policy 3320) from another SNAP document (Policy 3035). Because both documents belonged to the snap module (i.e., stored in the snap module folder), and both documents belong to the pages family (i.e., are stored in the pages folder), all you need to enter in the xref as the target is the file coordinate of the target document’s resource ID. The file coordinate for Policy 3320 is its filename, 3320.adoc.

This is just an example of the most common links you’ll be making between policy documents. To really learn about the terminology used in the paragraph above, and how to create links to documents in other modules (and even other components when more are added to PAMMS), see the extensive documentation (with diagrams and many examples) on the following Antora pages:

To link to a specific element in another page, you need to know the element’s ID. Add a hash (#) directly after the file name, followed by the ID of the element. For example, to link from this page to the Description lists section on the Lists page, you write:

See xref:lists.adoc#description-lists[How to make a description and step list].

This is published to the PAMMS site as:

See How to make a description and step list.

Learn more