Cross-references

General

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

There are the following types of cross-references:

Internal references
Bibliographic references
Hyperlinks to external sources (e.g., a link to a website)

The following clauses will provide the basics on how cross-referencing works in Metanorma.

Internal references

General

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 imageadoc
```
[[figureC-1]]
.Typical gelatinization curve
image::images/rice_image2.png[Image of the gelatinization curve]
```
image::/assets/author/learn/referencesimganchor.jpg[]
To reference an anchor, type the anchor name like this \<<anchor>>.
```
<<figureC-1>> gives an example of a typical gelatinization curve.
```
image::/assets/author/learn/referencesimgtarget.jpg[]
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.

Hyperlinks

It is easy to include links to external sources in Metanorma, 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: \PATH[].
Add link text in square brackets after the path.
Example of an internal linkadoc
```
Download the latest link:downloads/report.pdf[Report]!
```

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 linkadoc
```
http://www.iso.org/[International Organization for Standardization].
```

Edit this page on GitHub →