Enriched MyST Documents

🛠 Throughout the tutorial, whenever you’re supposed to do something you will see a 🛠

Start MyST 🚀¶

From the MyST quickstart tutorial, you should already have created a myst.yml configuration file that is required to render your project. To confirm this, run a MyST server to serve the MyST quickstart content:

🛠 Run myst start to serve your quickstart content

cd mystmd-quickstart
myst start

📖 Built README.md in 33 ms.
📖 Built 01-paper.md in 30 ms.
📖 Built 02-notebook.ipynb in 6.94 ms.
📚 Built 3 pages for myst in 76 ms.

      ✨✨✨  Starting Book Theme  ✨✨✨

⚡️ Compiled in 510ms.

🔌 Server started on port 3000!  🥳 🎉

      👉  http://localhost:3000  👈

🛠 Open your web browser to http://localhost:3000^[1]

To fully explore myst start see Get Started.

Add MyST Markdown! 🎉¶

Next we will improve the contents of the 01-paper.md, including:

• Adding and editing frontmatter
• Creating a “part” for the abstract
• Adding citations
• Adding figures
• Creating cross-references

Improve the frontmatter¶

🛠 Open 01-paper.md in a text editor

The start of the file includes information about the title, subtitle, author, affiliations and license. Unfortunately, this way of including this information is not easily machine-readable^[2], and focuses more on style/typography than on metadata.

# How to MyST, without being mystified 🧙

A tutorial to evolve markdown documents and notebooks into structured data

**Authors:** Rowan Cockett <sup>1,2</sup> \
**Affiliations:** <sup>1</sup> Executable Books, <sup>2</sup> Curvenote \
**License:** CC-BY

This will produce a document that looks like:

🛠 In 01-paper.md: Change the page frontmatter into a yaml block of data:

---
title: How to MyST, without being mystified 🧙
subject: Tutorial
subtitle: Evolve your markdown documents into structured data
short_title: How to MyST
authors:
  - name: Rowan Cockett
    affiliations:
      - Executable Books
      - Curvenote
    orcid: 0000-0002-7859-8394
    email: rowan@curvenote.com
license: CC-BY-4.0
keywords: myst, markdown, open-science
---

In this case, we are also adding additional metadata like an ORCID, as well as ensuring the license is an SPDX compatible code. Once these are added, the myst theme (in this case the book-theme template) can make it look pretty, this can also be customized by other themes, including $\LaTeX$ and Microsoft Word templates!

Add an abstract part¶

We will also add metadata about the “parts” of our document, for example, the abstract. This will be important when we export to PDF and also visually changes the book-theme.

🛠 In 01-paper.md: move the abstract into the frontmatter using a multiline YAML syntax abstract: |

1
2
3
4
5
6
---
title: How to MyST, without being mystified 🧙
...
abstract: |
  We introduce, a set of open-source, community-driven ...
---

You can make other parts, like data_availability or acknowledgments or keypoints, templates will treat these differently and may require specific parts to fully render. See document parts for additional information.

Add a citation¶

🛠 In 01-paper.md: find the text citation for Bourne et al., 2012 (shown in red below), and change it to a doi based citation, as shown in green below:

- ... follow the FORCE11 recommendations (Bourne _et al._, 2012). Specifically:
+ ... follow the FORCE11 recommendations [](doi:10.4230/DAGMAN.1.1.41). Specifically:

1. rethink the unit and form of scholarly publication;
2. develop tools and technologies to better support the scholarly lifecycle; and
3. add data, software, and workflows as first-class research objects.

This will result in correct rendering of the citation (such as Bourne et al. (2012)), and automatic insertion into the references section.

🛠 In 01-paper.md: find the text citation for Head et al. (2021), and change it to:

[](doi:10.1145/3411764.3445648)

If you have replaced both of these citations, you can now safely remove the text-only, poorly formatted references section, as that is now auto generated for you!

🛠 In 01-paper.md: Remove the ## References section with the two references (leave the links!)

This will have created a References section at the bottom of the page automatically!

Add a figure directive¶

🛠 In 01-paper.md: replace the image and paragraph with a figure directive.

Replace:

![](./images/citations.png)
**Figure 1**: Citations are rendered with a popup directly inline.

with:

:::{figure} ./images/citations.png
:label: citations
Citations are rendered with a popup directly inline.
:::

🛠 If you are up for it, in 01-paper.md replace the rest of the images with figure directives!

Add a cross-reference¶

🛠 In 01-paper.md: replace the text “Figure 1” with a local link to the figure

- ... (see Figure 1).
+ ... (see [](#citations)).

The “Figure 1” text will be automatically filled in, for example, Figure 4.

Conclusion 🥳¶

That’s it for this quickstart tutorial! You’ve just learned how to enrich your document with advanced MyST features for interactivity and open scholarship!

Check out the following tutorials for more step-by-step guides: