📢 5 - Sharing & Publishing Your Work

What is MyST?¶

MyST (Markedly Structured Text) is both a language and a software tool.

MyST, the language¶

MyST, as a language, extends Markdown.

It adds new syntax, including “roles” and “directives” that enable advanced functionality like executable code cells, callouts (also known as admonitions), and glossaries, and more. There is also dedicated syntax for citations, math, and more.

Directives are like functions that can receive Markdown content, for example an callout’s text. Roles are just like directives, except they are inline with other Markdown text.

Let’s jump right into a quick example of how this functionality works.

Example {glossary} directive and {term} role¶

MySTMD, the software¶

MySTMD is a software tool for executing and rendering technical documents from source in MyST or Notebook input formats to multiple output formats including websites, PDFs, $\LaTeX$, Typst, MS Word, JATS, and CITATION.cff.

MySTMD is the software that created this website from its source code (written in MyST and Jupyter Notebook format).

Building a website with MyST¶

As workshop participants, you have access to CryoCloud, which provides a JupyterLab instance with MyST pre-installed. CryoCloud also comes with a special configuration for building a MyST site without the use of the terminal.

To preview a MyST site in JupyterLab, view instructions at 📝 Using MyST.

myst build --html

myst start

💪 Exercise A: Build this MyST website in JupyterLab¶

TODO: Step to clone workshop repo as a drop-down or link to reference page (for participants who may come in late and miss these instructions from earlier modules)

Navigate to the correct directory in the file browser¶

On the left panel, ensure the JupyterLab file browser tab (📁 icon) is selected.

Double click the folder in the file browser named workshop-open-source-geospatial.

Build the MyST website¶

Location the MyST project configuration file, myst.yml, in the file browser.

Right click this file and select the top option from the menu: “Build MyST Project”.

🧠 What do we know now?¶

• A MyST project is configured by a myst.yml file

• In JupyterLab, we can right-click myst.yml to trigger a build (requires jupyter-myst-build-proxy)

💪 Exercise B: Build a MyST website from scratch in JupyterLab¶

Create a new empty GitHub repository¶

In the GitHub UI, click the + icon at the top-right. Select “New repository”.

Select your username as the owner, and enter myst-exercise as the repository name.

Leave everything else as default, and click “Create repository”.

Clone your repository¶

From your repository homepage’s “Quick start” menu, select “HTTPS”, then copy the URL.

On your JupyterHub server, open a new terminal.

Run these commands, replacing the placeholder with your actual repository URL:

# Change to your home directory
cd

# Clone the repository
git clone <YOUR_REPOSITORY_HTTPS_URL_HERE>

Initialize your MyST project¶

First, change directory into your empty repository:

cd myst-exercise

Next, initialize your MyST project with configuration needed to generate a website:

myst init --project --site

Create some content¶

Create a new file index.md using the JupyterLab interface:

• Right-click in the empty space in the file browser.

• Select “New file”.

• Input the name index.md.

Enter the following content in the file (click the copy button at the top-right of this code block):

Hello, world!

$$
1 + 1 = 2
$$

The $$ symbols delimit a math equation, and you can write any $\LaTeX$ within.

Build your site¶

Right-click the myst.yml file in the file browser, and select “Build MyST Project”.

Try some other MyST features and rebuild¶

MyST offers many useful features for technical publishing, including superscripts and subscripts, keyboard input notation, abbreviations, executable code cells, callouts (also known as admonitions), math, figures, diagrams, asides, dropdowns, grids, tabs, cards, buttons, glossaries, and more.

Try out some of these features in your MyST site.

Each time you make changes, rebuild the site by clicking “Rebuild” at the top-right of the site.

Make changes, rebuild, and view the result as many time as you need!

Give your site a title¶

Edit your myst.yml file by double-clicking it in JupyterLab.

Uncomment the title key and populate a title for your site, e.g. “My site”.

Your config file should now look like this:

# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  id: 60e9ac52-956d-4811-800a-68be74a85174
  title: "My site"
  # description:
  # keywords: []
  # authors: []
  github: https://github.com/mfisher87/myst-exercise
  # To autogenerate a Table of Contents, run "myst init --write-toc"
site:
  template: book-theme
  # options:
  #   favicon: favicon.ico
  #   logo: site_logo.png

Save and rebuild your site.

Replace “Made with MyST” text¶

“Made with MyST” is the default text that appears at the top of your site if you don’t provide a logo or logo_text.

We can update the text at the very top to replace “Made with MyST” by editing myst.yml again and setting site.options.logo_text. First, uncomment options:, then add a line underneath it to set logo_text. Indentation is important.

Your config file should now look like this:

# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  id: 60e9ac52-956d-4811-800a-68be74a85174
  title: "My site"
  # description:
  # keywords: []
  # authors: []
  github: https://github.com/mfisher87/myst-exercise
  # To autogenerate a Table of Contents, run "myst init --write-toc"
site:
  template: book-theme
  options:
    logo_text: "My logo text"
  #   favicon: favicon.ico
  #   logo: site_logo.png

Save and rebuild your site.

🧠 What do we know now?¶

• myst.yml controls what the site looks like, including the title, logo, logo text, and more.

• The index.md file is the “home page” for our site by default.

• The development loop for a MyST site in JupyterLab looks like:

  • Right-click myst.yml and “Build MyST Project”

  • In the newly opened browser tab, you can view a preview of your MyST site.

  • Change your site content by editing myst.yml, Markdown files, or Notebooks.

  • View the results of those changes by clicking “Rebuild” at the top of your site preview.

Building a PDF with MyST¶

TODO

💪 Exercise C: Render a PDF from the same source as your website¶

TODO

🧠 What do we know now?¶

TODO

Hosting your website for free¶

GitHub Pages¶

TODO

ReadTheDocs¶

TODO

💪 Exercise D: Publish your paper and website to GitHub¶

TODO

🧠 What do we know now?¶

TODO

Getting a DOI¶

TODO

💪 Exercise E: Get a DOI for your published content on GitHub¶

TODO

🧠 What do we know now?¶

TODO