Links and Cross References

DocFX offers two mechanisms, and choosing the right one for each case avoids most broken links:

The resolution order is shown below: a path link is checked against the files of the build; a cross reference is looked up first in the UIDs of the current project (conceptual headers and generated API pages) and then in the cross-reference maps listed in build.xref.

Figure: how DocFX resolves a path link and a cross reference.

The syntax is plain Markdown. A link to an absolute URL is left alone. A link that starts with / is domain independent and points to the root of the server that hosts the site. A relative path is relative to the file that contains the link. The prefix ~/ makes the path relative to the folder that holds docfx.json instead, which is easier to maintain in deep folder trees. ~/ is valid in images and in the HTML elements a, img, script and link as well; DocFX rewrites the href or src of those elements in the same way.

The Pocket Units project used for this page has this layout (the metadata output api/ is generated):

Source: DocFX docs: Links and cross references

The articles/links.md file below contains path links, among them one to a file that does not exist:

Source: DocFX docs: Links and cross references

The build log reports the missing file, and the rendered HTML shows that the valid links point at tour.html and at the copied image, while the broken one keeps the .md source path:

Three details come from the official page and from the build above:

A UID is declared in the YAML header of a conceptual file, and is generated automatically for every namespace, type and member that docfx metadata documents:

Source: DocFX docs: Links and cross references

For API pages the UID is the mangled signature: the namespace PocketUnits, the type PocketUnits.Converter, the enumeration PocketUnits.LengthUnit, and the method PocketUnits.Converter.Convert(System.Double,PocketUnits.LengthUnit,PocketUnits.LengthUnit). The easiest way to find a UID is to open the generated xrefmap.yml (see below) or the YAML file of the page under api/. A trailing asterisk, as in PocketUnits.Converter.Convert*, refers to all overloads of a method.

There are three equivalent ways to write a cross reference.

Options are appended to the UID as a query string. They apply to all three syntaxes; in the shorthand form the whole reference must be quoted when it contains ?.

The following references were built against the Pocket Units API and the .NET class library (see the next section for the System ones):

Source: DocFX docs: Links and cross references

An unresolved reference does not break the build. It is printed as text, and the log gets a UidNotFound warning with the line number:

The alt option is the one way to silence that warning on purpose: a reference that has alt and no target renders as the plain span shown above (the Not.Defined.Type reference produced no warning). In the same way, an xref element in HTML may carry data-throw-if-not-resolved="false", which the metadata stage adds to references taken from documentation comments.

References to System types need a map of the types published at learn.microsoft.com. The official page gives the location of the map that holds the class library types published from the dotnet-api-docs repository, and the xref key of the configuration file takes it as it is (it is already present in the docfx.json shown above):

Source: DocFX docs: Links and cross references

With that entry the build log reported 2 external references found in xref maps, the two external UIDs used by the articles (System.String and System.String.Length). The map is downloaded on every build, so a build needs network access to the Microsoft site; a build in a restricted network fails to resolve those references. The official page adds that, for the API reference pages generated from code (the ManagedReference documents), DocFX resolves the class library types and other types published on learn.microsoft.com without any map, which is why the double of Converter.Convert is already a link in the generated page while a System.String mention in an article needs the map.

Every build writes an xrefmap.yml into the output folder. It lists each UID of the site with the title of the page and its URL, so another project can link to yours by UID. The first entries of the Pocket Units file:

Source: DocFX docs: Links and cross references

Each entry has a uid, a name (the title or short name), an href (an absolute URL, or a path relative to the xrefmap.yml file) and, for API members, fullName and nameWithType, which displayProperty can select. commentId and the language variants such as name.vb come from the metadata stage. The articles PocketUnits.Tour and PocketUnits.Links appear in the same file with only uid, name and href.

To use the map, a second project lists it in build.xref. The value is a string or an array of strings, each a file path or a URL (the reference documents the schemes http, https and file):

Source: DocFX docs: docfx.json reference

Source: DocFX docs: Links and cross references

The example in the page was built with a map served over HTTP from the Pocket Units output folder (a local server stood in for example.org), and the references resolved to the other site:

The relative href values of the map were resolved against the URL of the map. A local file does not behave that way: with a relative file path such as ../lib/_site/xrefmap.yml in the xref list, the same references were rendered with href="api/PocketUnits.Converter.html", the relative path copied unchanged into the page, which points to a file that does not exist on the consumer site. In practice this means: publish the map next to the site and reference it by its HTTP address, or make the href values absolute (for example with a post-processing step on the file) before using it as a local file. Setting sitemap.baseUrl did not change the href values written to xrefmap.yml in the test.

A map is only read, never merged into the output of the consumer: its UIDs are not copied to the consumer’s own xrefmap.yml, and a consumer that republishes its map exports only its own UIDs.

Each UID should be defined once. When two files define the same UID, DocFX warns and keeps one of them:

In the build, the reference <xref:Dup.Page> resolved to the first file (dup1.html) and xrefmap.yml listed only that one. The official Markdown page describes the outcome as undetermined, so do not depend on which file wins; the order in which the files are processed is not a documented contract.

Conceptual files have no UID unless the header declares one, so a file that is only linked by path needs none. Giving every article a UID that reflects its subject (PocketUnits.Tour, not articles-tour) makes cross references readable and lets another site link to it.

A xrefService setting under build is not described in the docfx.json reference or in the cross-reference page (the text of the reference file contains no occurrence), and it was not tested for this page, so its behaviour is not documented here. Use a static xrefmap.yml or the maps published by other projects, which are the documented mechanisms.