Metanorma: Aequitate Verum

Cross-references

General

Cross-references are an integral part of standards. The main mechanism for references are anchors and destinations.

There are four types of cross-references:

  • Internal references to a section, image, table, etc.

  • Bibliographic entries

  • Hyperlinks to an external source (e.g., a link to a website)

It is easy to include links to external sources in Metanorma, and sources to files within the same project.

To reference an internal source:

  1. Use the link command to include a link to a file. The syntax looks like this: link:PATH[].

  2. Add link text in square brackets after the path.

    Example of an internal link
    Download the latest link:downloads/report.pdf[Report]!

To reference an external source:

  1. Paste the URL into the document.

  2. Add link text in square brackets after the URL (optional) URL[Link text].

    Example of an external link
    http://www.iso.org/[International Organization for Standardization].

Internal references

To link to an important section, table, figure, formula, or list item in your document:

  1. Set an anchor using double square brackets before the content you want to reference: [[anchor]].

    Example for an anchor preceding an image
    [[figureC-1]]
    .Typical gelatinization curve
    image::images/rice_image2.png[Image of the gelatinization curve]
    references img anchor
    Figure 1. Rendered image caption
  2. To reference an anchor, type the anchor name like this <<anchor>>.

    <<figureC-1>> gives an example of a typical gelatinization curve.
    references img target
    Figure 2. Rendered reference
  3. To set an alternative text other than the anchor text, append the text inside the brackets using a comma.

    <<figureC-1, The diagram>> gives an example of a typical gelatinization curve.

Auto-numbering of references

Metanorma automatically numbers and names references; because they are auto-numbered, they will be renumbered automatically if you insert any new text of the same type.

Metanorma markup is serialized into XML, hence the anchor should follow the XML namespace conventions.

i.e., an anchor name name must not contain:

  • colons

  • whitespaces

  • words starting with numbers

If you want to learn more about the technical aspects of cross-references, read Deep-dive into cross-references.