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. For example, we could link to the main https://mystmd.org/guide website:

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

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

Hover over [this link to a cool figure](xref:guide#subfigure)!

Hover Previews and Embedded Content¶

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. It is also possible to embed another resource, removing the need for the user to hover over a link:

Result

Code

![A cool figure with two subfigures](xref:guide#subfigure)