Metanorma: Aequitate Verum

Links and cross-references

References are an integral part of standards. The main mechanism for references are anchors and destinations. There are four types of references:

  • Hyperlinks to an external source, for example a link to a website

  • Metadata references

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

  • Bibliographic entries

Metanorma AsciiDoc lets you include links to external sources, 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].

    Adding acessibility in URIs

To add acessibility URIs, use the ,title=…​ option in the square brackets. The option corresponds to HTML’s alt text a@title attribute.

http://www.iso.org[International Organization for Standardization,title=This is a tooltip for the link]

Metadata references

Every document contains a set of metadata to describe the document. You can insert a metadata reference by putting the attribute in curly braces {attribute}. The reference will be replaced with the value in the rendered output.

:technical-committee-number: 2
:technical-committee: Fasteners
:subcommittee-number: 11
:subcommittee: Fasteners with metric external thread

This document was prepared by Technical Committee ISO/TC {technical-committee-number}, _{technical-committee}_, Subcommittee SC {subcommittee-number}, _{subcommittee}_.

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 autonumbered, they will be renumbered automatically if you insert any new text of the same type.

Since the markup will be converted into XML, the anchor must follow the XML namespace conventions.

Therefore, 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.

Typical links created by the link command require the correct file path that includes the file suffix (e.g. .html for HTML documents).

When linking a Metanorma document to another Metanorma document, which can be rendered into multiple output formats with different suffixes (such as in HTML, PDF or DOC), the option update-type=true can be specified to achieve format-independent links [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.4].

When the option update-type=true is given, the rendered link will provide the correct file paths dependent on the output format.

The following conditions must be satisfied to use format-independent links:

  • The link shall be relative and not absolute

  • The link shall not have a file suffix

Example 1. Example of links to other Metanorma documents
link:../parent[update-type=true]
link:../child[This is the child document,update-type=true]

This will render the following links depending on the output format:

  • in HTML, ../parent.html and ../child.html

  • in PDF, ../parent.pdf and ../child.pdf

Hyperlinks are validated and normalized in Metanorma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.5.2].

Hyperlinks are treated as IRIs (internationalized resource identifiers, where non-ASCII Unicode characters are allowed.)

As with normal AsciiDoc, http(s) links are assumed by default to be intended as hyperlinks, and are marked up and rendered as such.

Example hyperlinks are often invalid (e.g. http://{domain}), and Metanorma execution will be aborted if they are found, since they cannot be rendered as meaningful hyperlinks.

Such links should be escaped by prefixing them with a backslash, which will result in them being treated as plain text (e.g. http://{domain}.)