Table of Contents

Links and Cross References

Docfx provides several mechanisms to help you create links in markdown files.

To create hyperlinks, you can use the Markdown link syntax:

[docfx](https://dotnet.github.io/docfx)

This will render as

<a href="https://dotnet.github.io/docfx">docfx</a>

The link can be either an absolute URL pointing to another website or a relative URL pointing to a local resource on the same server. You can create a domain independent link starting with / to point to resources on the same server:

[my-file](/my-file.html)

To create a link to a local file, use the same markdown link syntax but change the URL to the relative path to the target file. For example, given the following directory structure:

|- docfx.json
|- file1.md
|- subfolder
   |- file2.md

You can reference file2.md in file1.md using relative path:

[file2](subfolder/file2.md)

This will render as:

<a href="subfolder/file2.html">file2</a>

You can also reference a local file using absolute path relative to docfx.json with the ~/ syntax. For example:

[file1](~/subfolder/file2.md)

This makes it easier to create links without the dealing with relative path.

Links to local files produces a build warning if the target file does not exist, so it is the recommended approach to avoid 404 links.

Note

You should include the target file in docfx.json, otherwise a broken link warning would appear.

Note

Automatic link doesn't support relative path. If you write something like <file.md>, it will be treated as an HTML tag rather than a link.

Docfx also supports referencing local files directly for HTML links created using the <a>, <img>, <script> and <link> tag. For example:

<a href="subfolder/file2.md">

This will render as:

<a href="subfolder/file2.html">

Cross references

Besides creating links using file path, docfx supports links to another resource identified by ID. This is useful for cases where you want to create path-independent references or share resources between projects using IDs.

Use the uid metadata to give a resource a unique identifier:

---
uid: file1
---

# This is file1
...

Then use one of the following syntax to reference resources by ID:

This is markdown autolink using the xref schema. For example,

<xref:file1>

This will render as:

<a href="file1.html">This is file1</a>

Notice how the link text is automatically generated from the title of the referenced article.

This is markdown link using the xref schema. For example,

[link text](xref:file1)

This will render as:

<a href="file1.html">link text</a>

Shorthand form

This is a shorthand form using @{uid} to quickly reference another file. For example,

see @file1

This will render as:

See <a href="file1.html">This is file1</a>

Not all strings after @ are treated as cross references. These are the rules to treat strings following @ as cross references:

  1. The string after @ must start with [A-Za-z], and end with:
    • Whitespace or line end
    • Punctuation ([.,;:!?`~]) followed by whitespace or line end
    • Two or more punctuations ([.,;:!?`~])
  2. A string enclosed by a pair of quotes (' or ")

Since @ is a common character in a document, a warning would appear if the UID isn't found for a shorthand form xref link.

Cross reference to .NET basic class library

To cross reference .NET basic class library types from markdown using the xref syntax, add https://learn.microsoft.com/en-us/dotnet/.xrefmap.json to the xref property in docfx.json, which contains all the BCL types published from https://github.com/dotnet/dotnet-api-docs.

{
  "build": {
    "xref": [
      "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
    ]
  }
}

For .NET API reference files, UID is generated by mangling the API's signature. For example, the System.String class's UID is System.String. You can open the xrefmap file to lookup the UID value of symbol to reference.

Note

For API reference documentations, docfx automatically resolves .NET base class library types and other types published to https://learn.microsoft.com by default, without cross reference map.

More options for cross referencing .NET API docs

You can create a cross link with following options:

  • text: the display text when the cross reference has been resolved correctly.

    e.g.: @"System.String?text=string" will be resolved as string.

  • alt: the display text when the cross reference does not have a href property.

    e.g.: <xref href="System.Collections.Immutable.ImmutableArray`1?alt=ImmutableArray"/> will be resolved as ImmutableArray<T>.

  • displayProperty: the property of display text when the cross reference is has resolved correctly.

    e.g.: <a href="xref:System.String?displayProperty=fullName"/> will be resolved as System.String.

    e.g.: <a href="xref:System.String.Length?displayProperty=nameWithType"/> will be resolved as String.Length.

  • altProperty: the property of display text when the cross reference does not have a href property.

    e.g.: <xref href="System.Collections.Immutable.ImmutableArray`1" altProperty="name"/> will be resolved as ImmutableArray<T>.

  • title: the title of link.

    e.g.: [](xref:System.String?title=String+Class) will be resolved as String.

Cross reference using xrefmap

The same mechanism to cross reference .NET base class library types can be used to cross reference resources in your own projects. You can define UID in one project and reference it using the cross reference syntax in another project using the xrefmap file as an intermediate exchange.

Generate xrefmap

Docfx generates an xrefmap.yml file in the output directory. This file contains information for all topics that have UID defined and their corresponding urls. The format of xrefmap.yml looks like this:

references:
- uid: uid_of_topic
  name: title_of_topic
  href: url_of_topic.html
  fullName: full_title_of_topic
- ...

It's a YAML object that contains following properties:

  1. references: a list of topic information, each item contains following properties:
    • uid: UID to a conceptual topic or API reference
    • name: title of the topic
    • href: url to the topic, which is an absolute url or relative path to current file (xrefmap.yml)
    • fullName: doesn't apply to conceptual, means the fully qualified name of API. For example, for String class, its name is String and fully qualified name is System.String. This property is not used in link title resolve for now but reserved for future use.

You can publish the xrefmap.yml file to a shared location for consumption by another project.

Using xrefmap

To use an xrefmap, add a xref config to the build section of docfx.json:

{
  "build": {
    "xref": [
      "<path_to_xrefmap>"
    ],
    ...
  }
}

The value of xref could be a string or a list of strings that contain the file path or URL to cross reference maps.

Once you import a cross reference map file in your DocFX project, all UIDs defined in that file can be cross referenced.

Edit this page