Links and cross references

uid: guides.cross-references description: Link pages and declarations by identity, check every link at build time, and exchange cross-reference maps with other sites.

Links between pages can be written in two ways: as relative links to Markdown files, or as cross references to an identity (a uid). Both are checked when the site is built.

Relative links

A relative link names the source file, not the published page:

See the [configuration reference](configuration.md#build-settings).

The build rewrites configuration.md to the published configuration.html and checks that:

• the target file is published (DG123 when it is not, DG125 for a missing image);
• the fragment names a heading or element on the target page (DG127);
• the path stays inside the site (DG122) and uses a safe scheme (DG121).

Identities

Every page and declaration can carry a uid:

Two pages that declare the same uid stop the build with DG301.

Cross-reference forms

The shorthand form starts at an @ that follows a space or an opening bracket, so addresses such as team@example.org are not read as references.

An identity that no page and no cross-reference map declares is reported as DG124 and rendered as plain text.

Cross-reference maps

Every build publishes xrefmap.yml at the root of the site. It lists each uid with its name, full name, address, and kind, sorted by uid. When sitemap.baseUrl or the _baseUrl metadata is set, the map records it as baseUrl so that its addresses resolve from anywhere.

### YamlMime:XRefMap
sorted: true
baseUrl: https://www.pudu-lang-docgen.com
references:
- uid: PuduLangDocgen.Docset.build
  name: build
  fullName: PuduLangDocgen.Docset.build
  href: api/PuduLangDocgen.Docset.html#build
  type: function

To link to another site's identities, list its map in build.xref. Entries may be project paths or web addresses, in YAML or JSON:

"xref": [
  "https://www.pudu-lang-docgen.com/xrefmap.yml",
  "maps/partner.json"
]

Identities declared by the site itself take precedence over identities from maps. A map that cannot be fetched or read is reported as DG904.

Reference services

A reference service answers questions about single identities. List its address in build.xrefService, with {uid} where the identity goes:

"xrefService": ["https://xref.example.com/query?uid={uid}"]

The build first renders the site without the services. For every identity still unresolved, it asks the services in order, replacing {uid} with the percent-encoded identity, and keeps the first reference whose uid matches. An answer is a JSON list of references with the same fields as a map entry, or a whole map. A service that fails is reported once as DG904 and not asked again during that build; its identities stay unresolved warnings.

The download and merge commands save a remote map locally and combine several maps into one, which keeps builds independent of the network.