Links and cross-references

Hyperlinks

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: \PATH[].
2. Add link text in square brackets after the path.

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].

*Adding accessibility in URIs*

To add accessibility 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]].
2. To reference an anchor, type the anchor name like this \<<anchor>>.
3. To set an alternative text other than the anchor text, append the text inside the brackets using a comma.

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.

Format-independent links

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 of links to other Metanorma documents

link:../parent[update-type=true]
link:../child[This is the child document,update-type=true]

Hyperlink validation

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}.)