Referencing other books

At the heart of Jupyter Book, and the MyST engine that powers it, is the concept of Structured Data. Every Jupyter Book (MyST) website publishes its structured data publically, making it possible for entire communities to publish and share knowledge and resources in a highly connected fashion. For example, here is a rich cross-reference to the https://mystmd.org guide: External MyST projects. By hovering over the previous link with your mouse cursor, you can see a rich-preview of the link’s contents, powered by structured data.

Declaring external websites¶

In order to create a rich cross-reference to an external resource, you must first inform Jupyter Book of where to find it by adding entries to the project.references mapping. The entries in project.references can be Jupyter Book 2 (MyST-MD) websites, or Jupyter Book 1 (Sphinx) websites. Only MyST-MD references support the rich features like hover-previews.

For example, we could link to the main https://mystmd.org/guide website:

myst.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  # title:
  # description:
  # keywords: []
  # authors: []
  # github:
  authors:
    - The Jupyter Book Team
  toc:
    - file: intro.md
  exports:
    - format: pdf
      template: lapreprint-typst
      articles: intro.md
  references:
    guide: https://mystmd.org/guide

site:
  template: book-theme
  # options:
  #   favicon: favicon.ico
  #   logo: site_logo.png

During your build, the Jupyter Book CLI will report that it has read these remote references, e.g.

$ myst start
🏫 Read 767 myst references for "guide" in 1.38 ms (cached).
...

Hover previews of cross-references¶

Now that Jupyter Book is aware of the name guide, we can link to its content using a special xref link:

Result

Code

Hover over this link to a cool figure!

Cross-references provide richer reading experiences than simple Markdown links. They take advantage of the structured data that MyST-powered websites publish, e.g. the cross-reference data for mystmd.org. The xref link syntax shown above is one-way to build a connection to another resource.

The xref link format is comprised of several important parts. E.g. for the xref xref:guide/figures#subfigure, each part has the following meaning:

xref:: xref scheme
guide: name of entry in project.references
/figures: path to the resource
#subfigure: fragment containing the identifier

Any content that has been explicitly labeled can found by omitting the /path, e.g. xref:guide#subfigure.

Embedding cross-referenced content¶

It is also possible to embed another resource, removing the need for the user to hover over a link. This can be done using the embed directive, or the markup for a Markdown image:

Result

Code

Golden Gate Bridge, San Francisco — (a)Banff, Canada