Links and cross-references

tag::tutorial[] 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

Hyperlinks

Metanorma AsciiDoc lets you include links to external sources, and sources to files within the same project.

To reference an internal source:

Use the link: command to include a link to a file. The syntax looks like this: link:PATH[].
Add link text in square brackets after the path.
Example of an internal link
```
Download the latest link:downloads/report.pdf[Report]!
```
end::tutorial[]

tag::tutorial[]

To reference an external source:

Paste the URL into the document.
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].
```
end::tutorial[] 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]

tag::tutorial[] == 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:

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]
```
Figure 1. Rendered image caption
To reference an anchor, type the anchor name like this <<anchor>>.
```
<<figureC-1>> gives an example of a typical gelatinization curve.
```
Figure 2. Rendered reference
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.

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

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

end::tutorial[]