Skip to article content


When you create a MyST project, the references that you make can be automatically linked and exposed to be referenced by other projects using External References. This must be served at myst.xref.json at the project root, and provides a list of reference links in JSON.

  "version": "1",
  "myst": "1.2.0",
  "references": [
      "kind": "page",
      "data": "/index.json",
      "url": "/"
      "identifier": "xref-features",
      "kind": "heading",
      "data": "/index.json",
      "url": "/",
      "implicit": true

The myst.xref.json data structure has three entries:


The version of the myst.xref.json schema


The version of mystmd CLI that created the myst.xref.json data


A list of references that are exposed by the project, each object includes:

The identifier in the project for this reference, this will be unique in the project unless there is an implicit flag.
This is only optional for pages, which may not have identifiers. All other content must have an identifier.
The identifier used on the HTML page, which is stricter than the identifier.
This is only included if it differs from the identifier.
The kind of the reference, for example, page, heading, figure, table.
The location of where to find the content as data. Use this link to find information like the reference’s enumerator, title or children.
The URL is relative from the location of where the myst.xref.json is served from.
The location of the HTML page; the URL is relative from the location of where the myst.xref.json is served from.
For constructing specific links to HTML pages, use <url>#<html_id || identifier>.
A boolean indicating that the reference is implicit to a page. This is common for headings, where the page information must be included.
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication