:::{attention} This section serves as a quick guide to MyST. Quotes below are sourced from the MyST Documentation, where you can find more comprehensive information. :::

MyST (Markedly Structured Text) is designed to create publication-quality, computational documents written entirely in Markdown. The main use case driving the development and design of MyST is JupyterBook, which creates educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST.

MyST is a superset of CommonMark (a standard form of Markdown) and allows you to directly create “directives” and “roles” as extension points in the language. These extensions points are influenced by ReStructured Text (RST) and Sphinx -- pulling on the nomenclature and introducing additional standards where appropriate. directives are block-level extension points, like callout panels, tabs, figures or embedded charts; and roles are inline extension points, for components like references, citations, or inline math.

• See this for a quick start guide to MyST Markdown's syntax.
• See MyST Specification and MyST History for more details about what MyST is.

The MyST Document Engine can parse Jupyter Notebooks and render them as HTML. This means you can write content in both MyST Markdown and Jupyter Notebooks—afterpython will organize and render them together as part of your project website.

You can add tags to notebook cells to control their behavior. For example, you can add the hide-input tag to a cell to hide the input of the cell.

See Notebook Cell Tags for more details.

If the environment variable AP_MOLAB_BADGE is set to 1, afterpython automatically adds molab badges to Jupyter Notebooks during the build process.

:::{note} molab is a cloud service by Marimo that supports running Jupyter Notebooks in the cloud. The badge lets users open your notebooks and run them in the cloud for free. :::

myst.yml is a configuration file for MyST, and since afterpython uses MyST to build content, each directory (doc/, blog/, tutorial/, example/, and guide/) has its own myst.yml configuration file. This allows you to customize MyST's behavior per directory.

A myst.yml file contains two main sections:

project — Project-level settings such as description, keywords, and GitHub URL.

See Frontmatter for all available options.

site — Website-level settings such as template, site title, logo, and favicon.

See Site Options for all available options.

:::{caution} Bug Report Some settings in myst.yml may not work as expected, and you may need to report the bugs on mystmd GitHub Issues.

Please do NOT report mystmd bugs on afterpython repository. :::

The toc subsection under project in myst.yml defines how your content is organized.

You can run myst init --write-toc in your content directory (e.g., afterpython/doc/) to automatically generate a TOC based on your existing content.

See Table of Contents for more details.

When you run ap init, afterpython creates an authors.yml file in the afterpython/ directory and syncs authors from pyproject.toml. This allows you to easily manage the authors of your project.

See Authorship, you can add social media links to your authors in authors.yml (e.g. GitHub, X, etc.)

By default, authors defined in authors.yml will all be used in myst.yml at the project level (see project.authors in myst.yml). However, you can override this behavior at the page level by adding the authors frontmatter at the top of your content (e.g. doc/your_page.md):

---
authors:
- new_author_id_defined_in_authors_yml
---

:::{tip} This entire documentation is written in MyST Markdown. You can click the "Edit this page" button in the top right corner to see the source code as an example of how to write content in MyST Markdown. :::

ap sync copies corresponding values from pyproject.toml and afterpython.toml into authors.yml and myst.yml.

For example, after updating authors in pyproject.toml, run ap sync to update authors.yml and your myst.yml files automatically.

You can also change [company.name] in afterpython.toml and run ap sync to update venue.title (set to the company name) in your myst.yml files.