Follow us on TwitterFork us on GitHub
MyST Markdown

External references

MyST allows you to connect your documents to external linked content like Wikipedia, which allow for hover-references with external content. External references are references to structured content or documents that are outside of your project. MyST supports referencing rich content in a growing number of formats, including:

  1. other mystjs projects, with rich cross-linking of content
  2. integrating directly with Wikipedia articles to show tooltips,
  3. linking to other Sphinx documentation using intersphinx,
  4. link to files on GitHub and show inline previews,
  5. showing structured content from scholarly sources like DOIs or RRIDs.

#Referencing external MyST projects

When using the HTML renderer for MyST, an API is provided for the deployed site. This provides pre-parsed, structured content as an AST that can be included and rendered in a tooltip.

#Referencing external Sphinx documentation

MyST can integrate directly with other Sphinx documentation, which is used in many Python projects including the standard library.

In your project configuration, include the references object with named links out to the Sphinx or MyST documentation that you will reference in the project. For example, in the demonstration below we will load the Python 3.7 documentation and JupyterBook docs, both of which use sphinx and expose cross references through an objects.inv file.

references:
  python: https://docs.python.org/3.7/
  jupyterbook: https://jupyterbook.org/en/stable/

When you specify these in your project configuration, MyST will load and cache the remote objects.inv file, and provide access to all of the references in that project.

To reference a function, class or label in the linked documentation, use the myst: protocol in a link followed by the project key and the target. For example, <myst:python#library/abc> renders to:
"abc — Abstract Base Classes"
and is made of a protocol, project and target.

protocol
The protocol for this type of link is myst:, and is what selects for cross-project referening.
project
the project key above is "python" which is defined in your local above.
The project is optional, however, we recommend that you include it to both efficiently look up the reference as well as be explicit as to what project you are referring to.
If the project is not included, all projects will be searched for the reference in the order given in the intersphinx configuration.
target
The target is everything that follows the # and is a named reference in the project.
In the example above it is "library/abc".

As with any link, the text can be overridden using markdown link syntax [text](myst:...).

MyST can directly integrate with Wikipedia to create hover-card information directly integrated into your myst documents. The syntax follows standard markdown links, under the wiki: protocol followed by the page title. As with any other link, you can either follow a [text](wiki:Page_Title) or <wiki:Page_Title>, which if no text is provided for the links will be replaced with the page title.

Primordial <wiki:gravitational_waves> are hypothesized to arise from <wiki:cosmic_inflation>, a faster-than-light expansion just after the <wiki:big_bang>.

The links will take you to Wikipedia, as well as provide a tooltip and description directly on the page.

To show different text you can use a similar technique to references:
[my **bold** text](wiki:reference)

* [big bang](wiki:The_Big_Bang_Theory) * [](wiki:big_bang)

MyST can directly integrate with links to GitHub to create hover-card information directly integrated into your MyST documents. For example, a link to the linkTransforms plugin code shows a preview of the code. The code preview works for both mutliple line numbers and higlighting single lines, which shows the surrounding ten lines, with the referenced line highlighted. If you reference the full file then the first ten lines of the file are shown in the preview.

#Linking DOIs

It is possible to include DOIs as external content, and they are also added as citations to your project and show up in the references section at the bottom of a document. See Citations and bibliography for more details, specifically , which explains linking DOIs with the <doi:10.5281/zenodo.6476040> or [](doi:10.5281/zenodo.6476040) to create a citation, for example ().

#Research Resource Identifiers

RRIDs are persistent, unique identifiers for referencing a research resource, such as an antibody, plasmid, organism, or scientific tool. These are helpful for ensuring reproducibility and exact communication in scientific studies. See the RRID website for more information.

MyST allows you to directly integrate with the RRID database to pull information and validate the links are correct as you are writing documents. The metadata is passed to subsequent systems (e.g. PDF documents, compatible journals and preprint servers) and helps keep your science reproducible.

To create an RRID link, use the rrid: protocol followed by the resource identifier, for example:

  • [](rrid:SCR_008394) becomes
  • <rrid:SCR_008394> becomes
References
  1. Cockett, R. (2022). Future of Research Communication &amp; Collaboration. 10.5281/ZENODO.6476040
  2. Ridler, T., Witton, J., Phillips, K. G., Randall, A. D., & Brown, J. T. (2020). Impaired speed encoding and grid cell periodicity in a mouse model of tauopathy. eLife, 9. 10.7554/elife.59045
  3. Rossant, C., Kadir, S. N., Goodman, D. F. M., Schulman, J., Hunter, M. L. D., Saleem, A. B., Grosmark, A., Belluscio, M., Denfield, G. H., Ecker, A. S., Tolias, A. S., Solomon, S., Buzsáki, G., Carandini, M., & Harris, K. D. (2016). Spike sorting for large, dense electrode arrays. Nature Neuroscience, 19(4), 634–641. 10.1038/nn.4268