# Technical Documentation: jupyter-book/mystmd > ℹ️ **Provenance:** Multi-Tier Ingestion Β· [CodeWiki Reference](https://codewiki.google/github.com/jupyter-book/mystmd) ### Overview (`README.md`) # MyST Markdown Command Line Interface, `mystmd` [](https://github.com/jupyter-book/mystmd/blob/main/LICENSE) [](https://discord.mystmd.org) `mystmd` is a set of open-source, community-driven tools designed for scientific communication, including a powerful authoring framework that supports blogs, online books, scientific papers, reports and journals articles. ## Overview The `mystmd` project provides a command line tool (`mystmd`) for working with MyST Markdown projects. - Provides functionality for cross-referencing, external structured links, and scientific citations - Translate and render MyST Markdown into: - HTML for static websites, and modern React for interactive websites (like this website!) - PDFs and LaTeX documents, with specific templates for over 400 journals - Microsoft Word export - Parse MyST into a standardized AST, that follows the MyST Markdown Spec See the [documentation](https://mystmd.org/guide). ## Get Started Ensure that you have an updated version of Node installed (): ```bash node -v >> v20.4.0 ``` The MyST Markdown CLI is available through NPM, PyPI and Conda: ```bash # Using npm, yarn, or pnpm npm install mystmd # Or using PyPI pip install mystmd # Or using Conda / Mamba conda install mystmd -c conda-forge ``` Usage: ```bash myst init myst start myst build my-doc.md --tex ``` # Development See [the Contribution Guide](CONTRIBUTING.md) for information on setting up a development environment. --- As of v1.0.0 this package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). --- --- ### Overview (`.changeset/README.md`) # Changesets Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it [in our repository](https://github.com/changesets/changesets) We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md) --- ### Overview (`docs/README.md`) # Contribute to the documentation This folder contains the content for the [MyST Guide at mystmd.org/guide](https://mystmd.org/guide). See [the documentation contribution guide for more information](contribute-docs.md). --- ### Overview (`packages/jats-to-myst/README.md`) # jats-to-myst Convert a JATS XML document to MyST AST --- ### Overview (`packages/jtex/README.md`) # jtex `jtex` is a command line tool (CLI) for rendering LaTeX documents from jinja-style templates. This package uses Jinja2 as the template engine with a modified environment and syntax that plays well with LaTeX's markup. ## Installation Install the package into your virtual environment using pip: ```bash npm install jtex ``` and confirm correct installation by typing: ```bash jtex --version ``` --- ### Overview (`packages/myst-cli-utils/README.md`) # myst-cli-utils Simple utilities for myst CLI tools. --- ### Overview (`packages/myst-cli/README.md`) # myst-cli See the [docs](https://mystmd.org/cli). --- ### Overview (`packages/myst-common/README.md`) # myst-common Common utilities and types for MyST. --- ### Overview (`packages/myst-directives/README.md`) # myst-directives Default directive definitions for MyST parser. ## Directives These directives are ported from `markdown-it-docutils`: - `admonitions` - `code` / `code-block` - `math` - `image` - `list-table` - `figure` --- ### Overview (`packages/myst-execute/README.md`) # MyST Execute Kernel execution of code and inline expressions using Jupyter. This package provides a transform that takes a MyST tree, computes the executable content, and stores the results in the AST. It provides basic support for caching of outputs to avoid needless computation. --- ### Overview (`packages/myst-ext-button/README.md`) # myst-ext-button `mystmd` extension for `button` role --- ### Overview (`packages/myst-ext-card/README.md`) # myst-ext-card `mystmd` extension for `card` directive --- ### Overview (`packages/myst-ext-exercise/README.md`) # myst-ext-exercise `mystmd` extension for `exercise` directive --- ### Overview (`packages/myst-ext-grid/README.md`) # myst-ext-grid `mystmd` extension for `grid` directive --- ### Overview (`packages/myst-ext-icon/README.md`) # myst-ext-icon `mystmd` extension for `icon` role --- ### Overview (`packages/myst-ext-proof/README.md`) # myst-ext-proof `mystmd` extension for `proof` directive --- ### Overview (`packages/myst-ext-reactive/README.md`) # myst-ext-card `mystmd` extension for `card` directive --- ### Overview (`packages/myst-ext-tabs/README.md`) # myst-ext-tabs `mystmd` extension for `tab-set` and `tab-item` directives --- ### Overview (`packages/myst-migrate/README.md`) # myst-migrate Utilities for upgrading and downgrading MyST ASTs --- ### Overview (`packages/myst-parser/README.md`) # myst-parser MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. The main use case driving the development and design of MyST is [JupyterBook](https://jupyterbook.org/), which helps you create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. `myst-parser` is a javascript parser for MyST markdown that brings these capabilities into a web-native environment. ## Goals - Provide a Javascript implementation of MyST markdown - Parse MyST into a standardized AST, based on [mdast](https://github.com/syntax-tree/mdast). - Serialize `mdast` into a default HTML for all known roles and directives - Expose an opinionated set of `markdown-it` plugins, to be used in ecosystems that require `markdown-it` (e.g. vscode) - Expose extension points in MyST for new roles/directives - Provide functionality for cross-referencing that is usually completed by Sphinx (e.g. in the [Python implementation](https://github.com/executablebooks/MyST-Parser)) ## Usage ```bash npm install myst-parser ``` In a node environment: ```javascript import { mystParser } from 'myst-parser'; import { State, transform, mystToHast, formatHtml } from 'myst-to-html'; import rehypeStringify from 'rehype-stringify'; import { unified } from 'unified'; const pipe = unified() .use(mystParser) .use(transform, new State()) .use(mystToHast) .use(formatHtml) .use(rehypeStringify); const file = pipe.processSync(':::{important}\nHello to the world!\n:::'); console.log(file.value); >> ``` In a browser: ```html
``` ## `myst-parser` Features - CommonMark - Admonitions - Figures - Images - Math - role - directive (equations) - dollar math - amsmath - Tables - GFM - List Tables - References - ref - numref - eq - links - Including numbering (single document) - Code Directives - Code - Code blocks - Code cell - Blocks - Comments - Targets - HTML: - `sub` - `sup` - `abbr` - Definition List - Footnotes Not yet complete: - div - proof - margin - sidebar - colon fence - Citations - Bibliography - Epigraph - Glosary - Terms - Tabs - Panels - CSV Tables - Multi-document ## Developer Install For installing the package locally, you will need [node](https://nodejs.org/) and [npm](https://docs.npmjs.com/about-npm), both can use a global install on your system. Once you have `npm` installed globally, navigate into this project folder and install the dependencies: ```bash cd myst-parser npm install npm run start # Start a development server to play with the library! πŸš€ ``` The scripts for building, testing, and serving the project are in the [package.json](package.json), the main ones to use are `npm run test`, `npm run build`, and `npm run start`. ### `npm run build` Builds the library, including compiling the typescript and bundling/minification to create `myst.min.js` which can be used in the browser directly. This outputs to the `dist` folder, and also includes all type definitions (`*.d.ts`) in the types folder. ### `npm run test` Run the tests, these are mostly based on the [fixtures](fixtures) folder. You can also use `npm run test:watch` to run on any file changes. ### `npm run start` Starts a server for manually testing and playing with `myst-parser`, this uses a in-memory bundle of what would go in the `dist` folder. Note that this does not actually build the library! --- ### Overview (`packages/myst-roles/README.md`) # myst-roles Default role definitions for MyST parser. ## Roles These roles are ported from `markdown-it-docutils`: - `sup`/`superscript` - `sub`/`subscript` - `abbr`/`abbreviation` - `eq` - `ref` - `numref` - `math` --- ### Overview (`packages/myst-spec/README.md`) # MyST Spec > :warning: The MyST AST specification is still in dev; any structures or features present in the JSON schema may change at any time without notice. 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](https://jupyterbook.org/), which creates educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. MyST is a superset of [CommonMark](https://commonmark.org/) (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)](https://en.wikipedia.org/wiki/ReStructuredText) and [Sphinx](https://www.sphinx-doc.org/) -- 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. ````md ```{directive} Argument The *content* of a directive can have {role}`with content` ``` ```` ## Goals `myst-spec` is designed to standardize implementations and extensions to MyST, with the goal of making the MyST ecosystem as rich and interoperable as possible. The spec formalizes three formats: 1. the MyST markup syntax, to ensure MyST works as expected across languages and implementations; 2. the MyST abstract syntax tree (AST), to promote an ecosystem of transformations and exports to diverse formats (e.g. latex/word/html/docutils/etc.); and 3. suggested semantic HTML output and CSS class structure, to promote web-accessibility and interoperability of themes. The `myst-spec` will be improved overtime through enhancement proposals which can be submitted by our multi-stakeholder community. [IN PROGRESS] ## MyST Spec This repository introduces tests to cover the MyST Spec. These tests cover three target formats: `myst`, `mdast`, and `html`. An simple example test case (in yaml) for a header looks like: ```yaml cases: - title: CommonMark headers myst: |- # Heading! mdast: type: root children: - type: heading depth: 1 children: - type: text value: Heading! html: |-

Heading!

``` [TBD: Do we include latex here, maybe?] ### Markdown Abstract Syntax Tree, `mdast` Markdown AST, or `mdast`, is an intermediate format that builds upon the existing [mdast spec](https://github.com/syntax-tree/mdast), which is used throughout the [unifiedjs](https://unifiedjs.com/) Javascript community with hundreds of [existing transformations](https://unifiedjs.com/explore/), [utilities](https://unifiedjs.com/explore/keyword/unist-util/) and [serializers](https://unifiedjs.com/explore/keyword/rehype/). `mdast` is simple, with a `type` defining the node optional properties on the node and optional `children` (a leaf node has a `value`). Beyond CommonMark and GitHub Flavoured Markdown, MyST introduces new directives and roles (like admonitions, citations, equations) following existing standards where they are defined. `mdast` is serializable to JSON or YAML, and can be effectively shared between projects, languages and implementations. The output of this repository is a versioned JSON file that can be used in implementations of MyST. --- ### Overview (`packages/myst-to-docx/README.md`) # `myst-to-docx` Export a MyST document to a Microsoft Word file, using [docx](https://docx.js.org/). ## Overview `myst-to-docx` has a `DocxSerializer` object that you write to as you walk the MyST document. It is a light wrapper around , which actually does the export. `myst-to-docx` is write only (i.e. can export to, but can’t read from `*.docx`), and has all standard MyST nodes covered (see below). `myst-to-docx` can be used in the browser or in node. This library currently only has dependence on `docx`, `myst-frontmatter` and `buffer-image-size` - and the serialization handlers can be edited externally (see `Extended Usage` below). The AST should be transformed through `myst-transforms` to ensure that all nodes are enumerated. ## Basic usage in browser The utility `fetchImagesAsBuffers` walks the AST and downloads images into buffers to be used by docx, it also figures out the size and returns an object with `getImageBuffer` and `getImageDimensions`, which need to be passed to the options. If your images are more complex (e.g. they are mermaid diagrams, or Jupyter Outputs), you will need to do more complex preprocessing to create these two functions. A `Blob` is returned, which can be downloaded client side. ```typescript import { unified } from 'unified'; import { mystToDocx, fetchImagesAsBuffers, DocxResult } from 'myst-to-docx'; const opts = await fetchImagesAsBuffers(tree); const file = unified().use(mystToDocx, opts).stringify(tree); const blob = await (file.result as DocxResult); ``` ## Basic usage in node In node, the image dimensions are discovered using a node-only package, and don't need to be provided. The result of the conversion in node is a `Buffer` as the `file.result`, which can be saved to disk. ```typescript import { unified } from 'unified'; import { mystToDocx, DocxResult } from 'myst-to-docx'; const file = unified() .use(mystToDocx, { getImageBuffer(url) { return fs.readFileSync(url).buffer; }; }) .stringify(tree); const buffer = await (file.result as DocxResult); ``` ## Extended usage Instead of using the `defaultDocxSerializer` you can override or provide cusome serializers. ```ts import { DocxSerializer, defaultNodes, defaultMarks } from 'myst-to-docx'; const nodeSerializer = { ...defaultNodes, my_paragraph(state, node) { state.renderInline(node); state.closeBlock(node); }, }; export const myDocxSerializer = new DocxSerializer(nodeSerializer, defaultMarks); ``` The `state` is the `DocxSerializerState` and has helper methods to interact with `docx`. ## Supported Block Nodes - text - link - paragraph - heading (levels) - Including numbering of headings - blockquote - code - TODO: No styles supported - thematicBreak - break - list - listItem - image - math - Including numbering - inlineMath - crossReference - abbreviation - block - definitionList - definitionTerm - definitionDescription - container - caption - captionNumber - tables ## Supported Style Nodes - emphasis - strong - inlineCode - subscript - superscript - delete (strikethrough) - underline - smallcaps ## Resources - [docx](https://docx.js.org/) - [myst-spec](https://github.com/jupyter-book/myst-spec) --- ### Overview (`packages/myst-to-html/README.md`) # myst-to-html Convert a MyST AST to HTML. ```typescript import { u } from 'unist-builder'; import { mystToHtml } from 'myst-to-html'; const html = mystToHtml(u('root', [u('paragraph', [u('text', 'hello world')])])); // '

hello world

' ``` --- ### Overview (`packages/myst-toc/README.md`) # myst-toc Utilities to parse a MyST table of contents. ## Overview The MyST ToC format is defined in `types.ts`, from which a JSON schema definition is compiled. The high-level description is as follows: 1. A TOC comprises of an array of TOC items 2. Each TOC item can be - A file (document) - A URL (document) - A collection of child items 3. TOC items containing children _must_ have either a `title` or a document ## Example Example `myst.yml` under the `toc:` key: ```yaml toc: - title: Main file: main.md - title: Overview children: - file: overview-1.md - file: overview-2.md - url: https://google.com - file: getting-started.md children: - file: getting-started-part-1.md - file: getting-started-part-2.md ``` --- ### Overview (`packages/myst-transforms/README.md`) # myst-transforms `unifiedjs` transforms for working with MyST Markdown documents. ## Overview These transforms take AST from `mystmd` and turn it into usable forms, enforce document structure, or provide other utilities. These utilities are available on npm: ```bash npm install myst-transforms ``` You can use the plugins as follows: ```typescript import { unified } from 'unified'; import { mathPlugin } from 'myst-transforms'; unified() .use(mathPlugin, { macros: {} }) // Add the plugin with any options .run(tree); // Run the AST through the set of plugins // The AST has now been modified in place. ``` --- ### Overview (`packages/mystmd-py/README.md`) # MyST Markdown Command Line Interface, `mystmd` [](https://github.com/jupyter-book/mystmd/blob/main/LICENSE) `mystmd` is a set of open-source, community-driven tools designed for scientific communication, including a powerful authoring framework that supports blogs, online books, scientific papers, reports and journals articles. > **Note** > The `mystmd` project is in **beta**. It is being used to explore a full MyST implementation and will change significantly and rapidly. > The project is being developed by a small team of people on the Executable Books Project, and may make rapid decisions without fully public/inclusive discussion. > We will continue to update this documentation as the project stabilizes. ## Overview The `mystmd` project provides a command line tool (`mystmd`) for working with MyST Markdown projects. - Provides functionality for cross-referencing, external structured links, and scientific citations - Translate and render MyST Markdown into: - HTML for static websites, and modern React for interactive websites (like this website!) - PDFs and LaTeX documents, with specific templates for over 400 journals - Microsoft Word export - Parse MyST into a standardized AST, that follows the MyST Markdown Spec See the [documentation](https://mystmd.org/guide). ## Get Started The MyST Markdown CLI is available through PyPI: ```bash pip install mystmd myst init myst build my-doc.md --tex ``` and Conda: ```bash conda config --add channels conda-forge conda config --set channel_priority strict conda install mystmd myst init myst build my-doc.md --tex ``` --- ### Overview (`packages/mystmd/README.md`) # mystmd The MyST Markdown Command Line interface. See --- ### Overview (`packages/simple-validators/README.md`) # simple-validators Schema validation functions and error reporting framework ## Scope This package provides basic validation functions for building more complex schema validation. It is explicit and verbose with no magic to infer anything from existing types. Rather than throwing validation errors, these functions pass error/warning messages out as options and return `undefined`; the consumer may then choose how to handle error reporting. ## Usage ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Overview (`packages/tsconfig/README.md`) # `tsconfig` These are base shared `tsconfig.json`s from which all other `tsconfig.json`'s inherit from. --- ### Overview (`packages/myst-common/scripts/README.md`) # MyST Scripts This directory contains utility scripts for maintaining the MyST codebase. ## generate-rule-severities.mjs Automatically generates `packages/myst-common/src/rule-severities.ts` by analyzing the codebase for rule usage patterns. ### What it does The script: 1. Scans all TypeScript files in the `packages` directory 2. Searches for patterns like: - `fileError(..., { ruleId: RuleId.* })` β†’ **error** severity - `fileWarn(..., { ruleId: RuleId.* })` β†’ **warn** severity - `addWarningForFile(..., 'error', { ruleId: RuleId.* })` β†’ **error** severity - `addWarningForFile(..., 'warn', { ruleId: RuleId.* })` β†’ **warn** severity - `*ValidationOpts(..., RuleId.*)` β†’ **error** severity (uses both, but errors are critical) 3. Aggregates the severities for each rule 4. Generates the `rule-severities.ts` file with: - Default severity for each rule - Comments explaining where each rule is used - Proper categorization matching the RuleId enum ### Usage ```bash # From the repository root node scripts/generate-rule-severities.mjs ``` --- ### Overview (`packages/mystmd/tests/url-folders/readme.md`) # Readme [xref to subfolder](#my-thing) [explicit xref to subfolder](two/page.md#my-thing) --- ### Index (`docs/index.md`) --- title: MyST Markdown Tools description: MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. --- {abbr}`MyST (Markedly Structured Text)` is an [ecosystem of open-source, community-driven tools](./overview.md) designed to revolutionize scientific communication. Our powerful authoring framework supports blogs, online books, scientific papers, reports and journals articles. :::{card} Get Started With MyST πŸ‘©β€πŸ’» :link: ./quickstart.md Start here to get up and running with the `myst` command-line tools. ::: ## Cool MyST Features πŸͺ„ We think {abbr}`MyST (Markedly Structured Text)` is really cool, some of the features that we think stand out are highlighted below with links to places in the documentation where you can reproduce them! --- πŸͺ„πŸ° **Rabbit-hole links** allow you to get information to your reader as fast as possible, and they can deep-dive all the way to computations, code and interactive figures. You can play with this demo yourself in [](./quickstart-myst-markdown.md). :::{figure} ./videos/links.mp4 :class: framed ::: πŸͺ„πŸ“Š **Live graphs** can be embedded directly in your documentation or articles with computation backed by Jupyter or JupyterLite – running locally, on Binder, or directly in your browser. Get up and running with Thebe in [](./in-page-execution.md) :::{figure} ./videos/thebe.mp4 :class: framed ::: πŸͺ„πŸͺ **JupyterLab support** for MyST comes with inline computations, support for `ipywidgets`, matplotlib sparklines, editable task-lists, rich frontmatter, and beautiful typography and other elements like dropdowns, grids and cards. Install [`jupyterlab-myst`](./quickstart-jupyter-lab-myst.md) today! :::{figure} ./videos/jupyterlab-myst.mp4 :class: framed ::: πŸͺ„πŸ“œ **Export to PDF** is easy with MyST, and we support hundreds of different journals out of the box, see [myst-templates](https://github.com/myst-templates)! You can also export to Microsoft Word or even JATS, which is used in scientific publishing. See the [](./quickstart-myst-documents.md)! :::{figure} ./images/myst-build.png :class: framed ::: --- ## Quickstart Tutorials :::{seealso} :class: dropdown # Coming from Jupyter Book V1 or Sphinx? πŸ‘‹ We are glad you are here! πŸ’š There are many ways that `mystmd` can be used with Jupyter Book and Sphinx. We recommend that you read [a high-level overview of MyST](./overview.md) as well as [the project background](./background.md), which goes over how these projects overlap and work together! TL;DR : **Yes**, you can use `mystmd` with your Jupyter Book! `mystmd` can create [scientific PDFs](./creating-pdf-documents.md) and can natively read the [`_toc.yml`](./table-of-contents.md) as well as all of your existing MyST Markdown content and [Jupyter Notebooks](./interactive-notebooks.ipynb). : **Yes**, `mystmd` is compatible with [intersphinx](#intersphinx) even though it is written in JavaScript not Python! : Jupyter Book and `mystmd` have **overlap** in the ability to create online books like this one. `mystmd` has some extra capabilities for [cross-references](./cross-references.md), interactivity and [performance](./accessibility-and-performance.md). : For more information see this [upgrade guide from Jupyter Book v1 to v2](https://next.jupyterbook.org/upgrade/). ::: ## Cite `mystmd` To cite or read more references about the `mystmd` project and related tools, see [](./cite.md). ## Project Goals MyST is part of the [Project Jupyter](https://jupyter.org/) organization, and is an open-source, community-driven project to improve scientific communication, including integrations into Jupyter Notebooks and computational results. ::::{grid} 1 1 2 3 :::{card} :link: ./citations.md **Built for Science** πŸ‘©β€πŸ”¬ ^^^ Extend Markdown with equations, cross-references, citations, and export to a preprint or rich, interactive website or book. +++ MyST for Science Β» ::: :::{card} :link: ./interactive-notebooks.ipynb **Dynamic Documents** πŸ“ˆ ^^^ Make your pages interactive by connecting to custom JupyterHubs, public Binders or even Python running directly in your browser. +++ Bring your pages to life Β» ::: :::{card} :link: ./accessibility-and-performance.md **Fast & Accessible** ⚑️ ^^^ Publish next-generation articles and books that are beautifully designed, without compromising on accessibility or performance. +++ Read about performance Β» ::: :::: **Technical Goals** - `mystmd` is a JavaScript parser and command line tool for working with MyST Markdown - Parse MyST into a standardized [AST](wiki:Abstract_Syntax_Tree), that follows [the MyST Spec](https://mystmd.org/spec) - Translate and render MyST into: - Modern [interactive websites](./quickstart-myst-documents.md), using React (like this website!) - PDFs and $\LaTeX$ documents, with [specific templates for over 400 journals](./creating-pdf-documents.md) - Microsoft Word [export](./creating-word-documents.md) - Provide functionality for [cross-referencing](./cross-references.md), [external structured links](./external-references.md), and [scientific citations](./citations.md) **Architecture** The `mystmd` command line tool can be used to parse MyST Markdown and Jupyter Notebooks into an AST. This data can be saved as JSON, or rendered to a website (like this one!) or any number of formats including [PDF & $\LaTeX$](./creating-pdf-documents.md), [Word](./creating-word-documents.md), [React](./quickstart-myst-documents.md), or [JATS](./creating-jats-xml.md). ```{mermaid} flowchart LR A[Jupyter Notebook] --> C B[MyST Markdown] --> C C(mystmd) --> D{AST} D <--> E[LaTeX] E --> F[PDF] D --> G[Word] D --> H[React] D --> I[HTML] D <--> J[JATS] ``` ```{important .dropdown} Using Sphinx or Python? For integration with **Sphinx**, use the Python implementation for MyST or Jupyter Book V1, which can be found at: - [MyST Python Parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/) - [Jupyter Book](https://jupyterbook.org/) Although many tools in the [MyST Ecosystem](https://mystmd.org) follow the same conventions and [specification](https://mystmd.org/spec), the following documentation refers only to the `mystmd` CLI. ``` --- ### Overview (`docs/overview.md`) # Overview of the MyST stack This section provides a high-level overview of the main concepts and tools in the MyST ecosystem. See the [guiding principles of the MyST ecosystem](./guiding-principles.md) for some more high-level context. (overview-build-process)= ## Overview of the MyST build process The MyST Build process takes input documents from authors and converts them into outputs that are meant for consumption by readers. The [MyST CLI](https://mystmd.org) contains logic to use the MyST Document Engine, renderers, and themes to carry out this entire process. Here's a high-level breakdown of the major steps of that process: ```{list-table} :header-rows: 1 - - Phase - Input - Output - - (1) **Writing**: An author writes content with {term}`MyST Markdown` in a file. - Ideas - Content (`.md`, `.ipynb`, `.tex`, etc) - - (2) **Parsing**: A {term}`MyST Document Engine` parses content into structured data called the {term}`MyST AST`. See [](#overview-parsing). - Raw content (`.md`, `.ipynb`, etc) - Raw MyST AST - - (3) **Resolving**: Transform raw MyST AST into AST that can be rendered. See [](#overview-transformers). - Raw MyST AST - Resolved / Processed MyST AST - - (4) **Rendering**: A {term}`MyST Renderer` transforms the {term}`MyST AST` into components that can be used by a {term}`MyST Theme`. - Resolved MyST AST - Components that can be rendered into a final output with a _template_ and/or _theme_ (e.g., LaTeX, React, etc). - - (5) **Theming / templating**: Rendered components are used by a {term}`MyST Theme` to generate final artifacts. See [](#overview-themes). - Template components that have been rendered by a MyST renderer. - Output formats that are ready for final consumption (e.g., a website or PDF). ``` Here is a brief overview of these steps: % NOTE: This is an excalidraw SVG. You can edit it directly in Excalidraw. % See the contributing docs for a short guide. :::{figure} images/overview-diagram-build.svg An overview of the "Parsing and Resolving" phase using the MyST Document Engine. In this stage, a text file written in MyST Markdown is parsed by the {term}`MyST Document Engine` which outputs {term}`MyST AST` that follows the {term}`MyST Specification`. This file undergoes a number of transformations to add metadata, resolve links, and enrich the document. The final output is MyST AST (usually a `.json` file) that can be rendered into many different kinds of outputs. ::: :::{figure} images/overview-diagram-render.svg An overview of the "Rendering and Theming" phase using one or more MyST renderers / themes. In this stage, a resolved MyST AST is rendered into multiple components by a MyST renderer. These are building blocks that a theme knows how to convert into a final output. For example, the [MyST React Renderer](https://github.com/jupyter-book/myst-theme/tree/main/packages/myst-to-react) and the [MyST React Themes](https://github.com/jupyter-book/myst-theme/tree/main/themes) know how to use these React components to create a final website. ::: (overview-parsing)= ## How does parsing work? The MyST Document engine knows how to parse many kinds of documents into {term}`MyST AST`. This is most-commonly done with Markdown files (`.md`) or Jupyter Notebooks (`.ipynb`) written in {term}`MyST Markdown`, a flavor of Markdown that was designed for the MyST Document Engine. However, the MyST Engine knows how to parse other kinds of syntax into MyST AST as well. For example, [for admonition compatibility with GitHub Markdown](#admonition-github-compatibility). This is because we see the {term}`MyST AST` as the primary point of _standardization_ for the MyST ecosystem, not the Markdown flavor. Input documents may have many different forms, but once it is parsed into {term}`MyST AST`, the document should have a standardized structure defined by the {term}`MyST Specification`. ## What is the MyST AST and Specification? The {term}`MyST AST` is a version of parsed MyST content that follows a specific structure so that Renderers can convert into different outputs. MyST AST conforms to the {term}`MyST Specification`. The {term}`MyST Specification` is a superset of [the `mdast` specification](https://github.com/syntax-tree/mdast) (meaning that MyST includes all of the syntax that `mdast` supports, plus some extra ones like Directives). Here's an example of MyST content, and the same content parsed as MyST AST: ````{list-table} :header-rows: 1 - - Content - AST - - `**Hello there!**` - ```yaml - type: block children: - type: paragraph children: - type: strong children: - type: text value: Hello there! ``` ```` The easiest way to understand how {term}`MyST Markdown` gets converted to {term}`MyST AST` is to [explore the MyST Sandbox](https://mystmd.org/sandbox). Click the {kbd}`AST` tab to see the underlying AST structure for anything that you type. The {kbd}`PRE` tab represents the initial parsing phase, and the {kbd}`POST` tab represents the AST after the resolving phase. If you're building your own renderer or parser, start with the [AST primer](xref:spec/ast-primer). It walks through the node structure, the PRE/POST distinction, and what the spec formalizes vs. what's implementation-specific. (overview-transformers)= ## How do MyST Transformers work? MyST Transformers are a way to convert a {term}`MyST AST` node into another type of node. Transformers operate on AST rather than on raw Markdown because AST has more standardized structure to work with. For example, consider a Markdown link like `[some text](#a-label)`. In MyST Markdown, this defines a **cross-reference** to `#a-label`, but it uses Markdown link syntax. We use a **MyST Transformer** to convert that Markdown to a cross-reference AST node like so: - First parse the Markdown `[some text](#a-label)`. - The result is a MyST AST node for a **Markdown link**. - Next, search the document AST for any Markdown link nodes with a target that starts with `#`. Check if there's [a target](./cross-references.md) for the link. If so, it is meant to be a cross reference. - If so, converts the Markdown Link node into a Cross Reference node. Some other uses for Transformers include: - Lifting metadata from `code-cells` to their parent structures - Check that figures have alt-texts - Convert non-standard AST nodes (e.g., ones generated from a custom user directive) into ones that MyST knows how to render[^ex-transform-node]. [^ex-transform-node]: For example, see [this Executable Transform example from Project Pythia](https://github.com/projectpythia-mystmd/cookbook-gallery/blob/main/pythia-gallery.py). It is an example of an [`executable transform`](#executable-plugins), which takes custom `pythia-cookbooks` nodes and converts them (via some HTTP fetches) to a grid of cards by outputting the relevant grid and card AST nodes. See [](#develop:transforms) for more details about how transforms operate on an AST and what intermediate steps look like. (overview-themes)= ## How do MyST themes and templates work? MyST {term}`themes` and MyST {term}`templates` are both related to _exporting_ a resolved MyST AST into one or more final output formats. They differ in the amount of _customizability_ that a user has in altering their behavior, but the end-result is the same (generating an export artifact). ```{glossary} Templates : Templates are usually used for [static exports](./documents-exports.md) (like LaTeX or Typst). The are structured like a final document (e.g., a LaTeX template for a specific journal), but with fields that MyST uses to insert document metadata at export time (e.g., a `doc.author` field if you want to insert the author name). See [the `myst-templates` GitHub repository](https://github.com/myst-templates) for a list of templates that you can use and contribute to. Themes : Themes expose more customizability than a template (which simply generates static outputs via a Jinja-like filter), but they function similar to a template because they take rendered components as inputs and export a final output. Themes are usually meant for _websites_, because there is a lot more control a website exposes compared to a static document like LaTeX. Themes have more complex logic, and thus their source-code is often in a dedicated repository. For examples, see the [build outputs of the `book` and `article` web themes are `myst-templates`](https://github.com/myst-templates#templates), but their [source code is in `myst-theme`](https://github.com/jupyter-book/myst-theme/tree/main/themes). ``` For a more technical explanation see [the developer guide on themes, templates, and renderers](#develop-renderers-themes). ## Are there other MyST engines? The [MyST Specification](https://mystmd.org/spec) and [MyST Markdown Syntax](https://mystmd.org/guide) was designed so that others could implement their own parsers, document engines, and renderers using MyST. Although there are presently no independent examples of a true {term}`MyST Document Engine`, the MyST Parser for Sphinx project fulfills a similar role in the Sphinx ecosystem. The [MyST Parser for Sphinx](https://myst-parser.readthedocs.io) is an extension for [Sphinx](https://sphinx-doc.org) that can parse MyST Markdown into Sphinx's internal document structure. It was created to allow users to parse MyST Markdown syntax into Sphinx for [V1 of Jupyter Book](https://jupyterbook.org). It now exists as an independent extension for the Sphinx community, as Jupyter Book V2 now uses the MyST Document Engine. :::{note} MyST Parser for Sphinx Compatibility As the MyST Parser for Sphinx does not support all of the syntax defined in the MyST Guide, or output {term}`MyST AST`, it's not a true {term}`MyST Document Engine` as defined by this project. That's OK! Its goal is to be a useful tool for the Sphinx community that only leverages parts of the MyST ecosystem (the Markdown flavor), which for many people is "good enough." ::: ## How does Jupyter Book relate to MyST? The MyST Markdown Syntax was originally created to allow [Jupyter Book V1](https://jupyterbook.org) to use the [Sphinx Document engine](https://sphinx-doc.org) with Markdown content[^md], rather than the less well-known language. [^md]: Specifically, the [MyST Parser for Sphinx](https://myst-parser.readthedocs.io) was created to move beyond the functionality of the [`recommonmark` project](https://github.com/readthedocs/recommonmark) in order to natively support docutils `roles` and `directives` in Markdown. Over time, the Jupyter Book team decided that the most sustainable path forward was to maintain its own document engine, the [MyST Document Engine](https://mystmd.org/guide). An early version of the MyST Document Engine was created by [Curvenote](https://curvenote.com). To promote its long-term sustainability, the project was open sourced and further developed in collaboration with the Jupyter Book team. It serves as the engine behind Jupyter Book V2. You can think of Jupyter Book as a _distribution of the MyST Document Engine_. In other words, Jupyter Book wraps the MyST Document Engine application, with out-of-the-box configuration that supports a multi-page community knowledge base or documentation site. MyST is created and maintained by the [Jupyter Book team](https://compass.jupyterbook.org). Currently, Jupyter Book and the MyST Document Engine share much of the same functionality. Over time, we imagine that the MyST Document Engine will be a more flexible tool that makes fewer assumptions about the end use-case that it's being used for. Jupyter Book will then have "more opinions" above the base configuration of the MyST Document Engine. That said β€” we are still figuring this out! We aren't sure the exact relationship the two will have, and will revisit this as we learn more. See [next.jupyterbook.org](https://next.jupyterbook.org) for Jupyter Book V2 documentation, and [see this section of the Contributing Guide](#jb-vs-md) for our approach to documenting the two projects. ## How do MyST and Sphinx compare? [Sphinx] is an open-source documentation system used in many software projects, especially in the Python ecosystem. It builds an internal representation of technical documents as a tree (see [docutils]) similar to the {term}`MyST AST`. Whilst Sphinx partially defines a specification of sorts[^docutils], a {term}`MyST Document Engine` explicitly publishes its {term}`MyST AST` for other tools to consume. The Sphinx ecosystem has excellent support for Python documentation, referencing content, as well as externally providing an inventory of references known as [intersphinx]. You can link to Sphinx documentation with a {term}`MyST Document Engine` by using [intersphinx references](#intersphinx), and the official {term}`MyST Document Engine` automatically exposes the information required to allow Sphinx documentation to reference your MyST project. At this time, the official {term}`MyST Document Engine` does not support the authoring of software API documentation[^api-docs]. As such, if your project is documenting Python software we suggest that you use Sphinx. If your project is primarily tutorials, educational textbooks (including with Jupyter Notebooks), a presentation, or scientific paper, we hope that you find a better fit with the MyST stack! Sphinx and MyST take very different approaches to publishing to the web. In Sphinx, themes are used to customize the generation of HTML and JavaScript. Sites built using these themes can be deployed to static web servers like [ReadTheDocs](https://readthedocs.com/). In the MyST world, the equivalent to a Sphinx theme is a {term}`MyST Renderer` that consumes the {term}`MyST AST` and outputs HTML and JavaScript for your browser. Formally separating the {term}`MyST Document Engine` that generates {term}`MyST AST` and the {term}`MyST Renderer` that consumes it makes it possible to create rich new experiences with MyST, such as the [SciPy Conference Proceedings](https://proceedings.scipy.org/) website that renders {term}`MyST AST` on the fly. Although the official engine also supports static HTML outputs, implementing themes as applications makes it easier to build more powerful MyST viewing experiences. [^api-docs]: In the future, `mystmd` may offer support for Python and JavaScript documentation, and if you want to contribute please discuss on [#1259](https://github.com/jupyter-book/mystmd/issues/1259) and this [video](https://www.loom.com/share/589a947389fb49829c9b712b796d8a7d). [^docutils]: The Docutils source-code _is_ the specification. [docutils]: https://docutils.sourceforge.io/ [sphinx]: https://www.sphinx-doc.org/ [intersphinx]: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html --- ### Quickstart (`docs/quickstart.md`) --- title: Get Started subtitle: Your first steps with MyST subject: MyST Quickstart Tutorial description: Get up and running with the MyST (Markedly Structured Text) command line interface. MyST is designed to create publication-quality documents written entirely in Markdown. --- These quickstart tutorials are here to get you up and running on your local computer πŸ‘©β€πŸ’». See [this overview of the MyST ecosystem](./overview.md) for a more conceptual introduction. In this tutorial, you will get up and running from scratch. You will learn how to: - **write** MyST Markdown πŸ–Š - **export** PDF, Word and $\LaTeX$ documents πŸ“‘ - **create** a website like this one 🌎 :::{note} Goals and Prerequisites **Goal**: The goal of this tutorial is to help you **install MyST** on your local computer πŸ‘©β€πŸ’», create a local website 🌎, and edit elements of the theme to improve the website style 🎨. **Skills**: It is helpful if you have some familiarity with using the command line, as well as using a text editor and/or JupyterLab. **Tools**: You'll need a code and notebook editor ([VSCode](https://code.visualstudio.com/) is great, and we recommend [Jupyter Lab](https://jupyter.org/install) for notebooks) as well as access to a CLI. ::: (lookout-for-tutorial-actions)= > πŸ›  Throughout the tutorial, whenever you're supposed to _do_ something you will see a πŸ›  ## Install the MyST Markdown CLI πŸ›  Install MyST using your preferred packaging ecosystem. (See [](./installing.md) for more details). :::{tip} Not sure which to pick? :class: dropdown The easiest way to install MyST is with the `mamba` package manager. `mamba` is a cross-platform language-agnostic package manager that is useful for users across many data science languages like Python, R, Julia, and JavaScript. ::: :::{embed} #installing-myst-tabs ::: πŸ›  Then, check that MyST has successfully been installed: ```shell $ myst -v v1.3.4 ``` ## Build your first MyST site Next we'll download some sample content and use MyST to render it as a local web server! ### Download example content We provide an example project that includes a few simple Markdown files and some Jupyter Notebooks. Through the course of the tutorials we will add content to these documents that show off some of the features of MyST. πŸ›  Download the example content[^no-git], and navigate into the folder: ```bash git clone https://github.com/jupyter-book/mystmd-quickstart.git cd mystmd-quickstart ``` [^no-git]: If you aren't familiar with git, it isn't required for this tutorial, you can download the zip file with the contents from the [quickstart repository](https://github.com/jupyter-book/mystmd-quickstart). ### Initialize MyST in the content folder πŸš€ Next we will create a `myst.yml` configuration file that is required to render your project. πŸ›  Run `myst` The `myst` command is a shortcut for `myst init`, which has a few more options for writing specific parts of the configuration file and a table of contents for your site. ```shell $ myst Welcome to the MyST Markdown CLI!! πŸŽ‰ πŸš€ myst init walks you through creating a myst.yml file. You can use myst to: - create interactive websites from Markdown and Jupyter Notebooks πŸ“ˆ - build & export professional PDFs and Word documents πŸ“„ Learn more about this CLI and MyST Markdown at: https://mystmd.org πŸ’Ύ Writing new project and site config file: myst.yml ``` ### Preview your MyST site locally Preview a rendered version of the quickstart content to make sure that MyST is working properly. πŸ›  When prompted, type `Yes` to install and serve your MyST content locally: ```bash ? Would you like to run "myst start" now? Yes ``` or manually serve the quickstart content with the following command: ```bash myst start ``` Starting the server requires a theme, this will download the default `book-theme` from [the MyST themes](./website-templates.md). This can take **up to a minute** the first time, and then will be cached in the `_build/templates` directory. ```text πŸ• Fetching template metadata from https://api.mystmd.org/templates/site/myst/book-theme πŸ’Ύ Saved template to path _build/templates/site/myst/book-theme ‡️ Installing web libraries (can take up to 60 s) πŸ“¦ Installed web libraries in 13 s πŸ“– Built interactive-graphs.ipynb in 21 ms. πŸ“– Built paper.md in 32 ms. πŸ“– Built README.md in 35 ms. πŸ“š Built 3 pages for myst in 82 ms. ✨✨✨ Starting Book Theme ✨✨✨ ⚑️ Compiled in 524ms. πŸ”Œ Server started on port 3000! πŸ₯³ πŸŽ‰ πŸ‘‰ http://localhost:3000 πŸ‘ˆ ``` πŸ›  Open your web browser to `http://localhost:3000`[^open-port] [^open-port]: If port `3000` is in use on your machine, an open port will be used instead, follow the link provided in the terminal. The example site in this tutorial only has three pages and by default the `01-paper.md` page is seen in [](#frontmatter-before), which has minimal styles applied to the content. :::{figure} ./images/frontmatter-before.png :width: 50% :label: frontmatter-before :class: framed The myst theme for the `01-paper.md` page without any changes made. ::: πŸŽ‰ **Congratulations**, you just built your first MyST site! ## Configuration and structure The final section of this tutorial takes a closer look at the files that we just created, and aspects of your MyST project that can be customized. ### Folder Structure If you are using a text editor, for example [VSCode](https://code.visualstudio.com/), open up the folder to explore the files: ```text quickstart/ β”œβ”€β”€ πŸ†• _build β”‚ β”œβ”€β”€ exports β”‚ β”œβ”€β”€ site β”‚ β”‚ β”œβ”€β”€ content β”‚ β”‚ β”œβ”€β”€ public β”‚ β”‚ └── config.json β”‚ β”œβ”€β”€ temp β”‚ └── templates β”‚ β”œβ”€β”€ site/myst/book-theme β”‚ └── tex/myst/arxiv_two_column β”œβ”€β”€ images β”‚ β”œβ”€β”€ image.png β”‚ └── image.gif β”œβ”€β”€ 01-paper.md β”œβ”€β”€ 02-notebook.ipynb β”œβ”€β”€ README.md └── πŸ†• myst.yml ``` Running `myst init` added: - `myst.yml` - the configuration file for your myst project and site - `_build` - the folder containing the processed content and other `site` assets, which are used by the local web server. The `_build` folder also contains your templates (including the site template you installed) and any exports you make (when we build a PDF the exported document will show up in the `_build/exports` folder). You can clean up the built files at any time using `myst clean`[^clean-all]. [^clean-all]: By default the `myst clean` command doesn't remove installed templates or cached web responses; however, the function can with a:\ `myst clean --all`, or\ `myst clean --templates --cache`. Before deleting any folders `myst` will confirm what is going to happen, or you can bypass this confirmation with the `-y` option. For example: ```text Deleting all the following paths: - _build/site - _build/templates ? Would you like to continue? Yes πŸ—‘ Deleting: _build/site πŸ—‘ Deleting: _build/templates ``` ### Configure site and page options If we open and look inside our `myst.yml` we will see a basic configuration like this: ```yaml # See docs at: https://mystmd.org/guide/frontmatter version: 1 project: # title: # description: keywords: [] authors: [] # github: # bibliography: [] site: template: book-theme # title: # options: # logo: my_logo.png nav: [] actions: - title: Learn More url: https://mystmd.org/guide domains: [] ``` :::{note} As this is a rapidly-evolving project, the actual generated `myst.yml` file that you will see may look a bit different. ::: There are two important parts to the `myst.yml`: `project:` : The project holds metadata about the collection of files, such as authors, affiliations and licenses for all of the files, any of these values can optionally be overridden in a file. To see all of the options see [](./frontmatter.md), which includes which fields can be overridden by files in the project. `site:` : The site holds template information about the website, such as the logo, navigation, site actions and which template to use. πŸ›  In `myst.yml`: Change the "`# title:`" comment in **site** to "`title: Fancy Title 🎩`" and save Saving the `myst.yml` will have triggered a "full site rebuild"[^myst-start]. Take a look at the browser tab and you'll see that it has updated: :::{figure} ./images/frontmatter-site-title.png :width: 50% :label: frontmatter-site-title The site title will control site meta tags, and the browser-tab title, which is appended to each page title in the `book-theme`. ::: [^myst-start]: If the server stopped, you can restart the server using `myst start`. :::{seealso} See all Frontmatter options To see all of the options see [](./frontmatter.md), which includes which fields can be overridden by files in the project. ::: --- ## Next steps ➑️ That's it for this quickstart tutorial! You've now got MyST installed locally, and the basic structure of a MyST project ready to improve. You are well on your way to getting started with `myst`. Here are some things to try for next steps: - Organize a [Table of contents](./table-of-contents.md) - Configure [website downloads](./website-downloads.md) - [Choose a website template](./website-templates.md) - [Customize logos and favicons](#site-options) (quickstart-cards)= +++ Check out the following tutorials for more step-by-step guides: ::::{grid} 1 1 2 2 :::{card} Author enriched MyST articles ✨ :link: ./quickstart-myst-documents.md Write scientific articles using MyST Markdown with easy-to-use citations, metadata, and cross-references. ::: :::{card} Executable Documents with MyST 🐍 :link: ./quickstart-executable-documents.md Learn how to use computation and execution with Jupyter in MyST. ::: :::{card} Export to static documents πŸ“‘ :link: ./quickstart-static-exports.md Export MyST documents to a Word document, PDF, and $\LaTeX$! ::: :::{card} MyST Markdown Guide πŸ“– :link: ./quickstart-myst-markdown.md See an overview of MyST Markdown syntax with inline demos and examples. ::: :::{card} Use MyST in Jupyter Interfaces πŸŒ• :link: ./quickstart-jupyter-lab-myst.md Learn how to use MyST in Jupyter Interfaces. ::: :::: --- ### Syntax Overview (`docs/syntax-overview.md`) --- title: MyST Syntax Overview description: MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. --- MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. The extensions and design of MyST is inspired by the [Sphinx](https://www.sphinx-doc.org/) and [reStructuredText](https://docutils.sourceforge.io/rst.html) (RST) ecosystems. MyST is a superset of [CommonMark](./commonmark.md), the standard form of Markdown, and allows you to directly create β€œdirectives” and β€œroles” that extend Markdown to support technical and scientific documents. `directives` are block-level extension points, like [callout panels](./admonitions.md), [tabs](./dropdowns-cards-and-tabs.md), [figures](./figures.md) or [embedded charts](./interactive-notebooks.ipynb); and roles are inline extension points, for components like [cross-references](./cross-references.md), [external references](./external-references.md), [citations](./citations.md), or [inline math](./math.md). ## Directives & Roles Roles and directives are two of the most powerful parts of MyST. They are kind of like functions, but written in a markup language. They both serve a similar purpose, but roles are written in one line whereas directives span many lines. They both accept different kinds of inputs, and what they do with those inputs depends on the specific role or directive being used. (syntax:directives)= ### Directives Directives are multi-line containers that include an identifier, arguments, options, and content. Examples include [admonitions](./admonitions.md), [figures](./figures.md), and [equations](./math.md) (visit this page for the [full list of directives](#directives_list)). At its simplest, you can use directives using a "fence" (either back-ticks or colons[^colon-or-fence]) and the name of the directive enclosed in braces (`{name}`): [^colon-or-fence]: Which fence type, colon or backtick, is up to you, and either will work. The colon-fence has better fallback when the contents of the directive includes Markdown in non-MyST renderers (like GitHub). The backtick-fence should be used when the contents of the directive is code-like (e.g. a diagram or math!). (example-fence)= ``````{tab-set} ````{tab-item} Colon Fence Use a colon fence (`:::`) when the contents of the directive is Markdown, such as [callouts](./admonitions.md) or [theorems](./proofs-and-theorems.md) this will improve the processing in renderers that do not support MyST: ```{myst} :::{note} Here is a note! ::: ``` ```` `````{tab-item} Backtick Fence Use a backtick fence (`` ``` ``) when the contents of the directive is code-like, such as [math](./math.md) or a [diagrams](./diagrams.md), this will ensure any sort of auto-formatting will not attempt to reformat these sections: ````{myst} ```{math} \mathbf{u} \times \mathbf{v}=\left|\begin{array}{ll}u_{2} & u_{3} \\ v_{2} & v_{3}\end{array}\right| \mathbf{i}+\left|\begin{array}{ll}u_{3} & u_{1} \\ v_{3} & v_{1}\end{array}\right| \mathbf{j}+\left|\begin{array}{ll}u_{1} & u_{2} \\ v_{1} & v_{2}\end{array}\right| \mathbf{k} ``` ```` ````` `````` The {myst:directive}`note` directive above doesn't take any arguments, and we didn't add any options. In addition to the directive name and the directive content, directives allow two other configuration points: 1\) **directive arguments** - a list of words that come just after the `{directivename}`. ``````{tab-set} ````{tab-item} Colon Fence ```markdown :::{directivename} arg1 arg2 My directive content. ::: ``` ```` `````{tab-item} Backtick Fence ````markdown ```{directivename} arg1 arg2 My directive content. ``` ```` ````` `````` 2\) **directive options** - a collection of flags or key/value pairs that come just underneath `{directivename}`. There are three ways to write directive options: as `:key: value`, as a YAML block, or directly inline. ``````{tab-set} `````{tab-item} Key value pairs Options can be included as `:key: val` pairs, which is the default way to include options. ````markdown ```{directivename} :key1: metadata1 :key2: metadata2 My directive content. ``` ```` ````` `````{tab-item} YAML Options can also be included as `key: val` pairs enclosed by `---` lines, similar to document frontmatter. This is parsed as YAML, and may be easier for listing many options. ````markdown ```{directivename} --- key1: metadata1 key2: metadata2 --- My directive content. ``` ```` ````` `````{tab-item} Inline Options Options can be included inline. See [](./inline-options.md) for more information. ````markdown ```{directivename .class-name #label key="value"} My directive content. ``` ```` ````` `````` ```{tip} Specifying directive keywords with `:key:` or `---` will make no difference. Use the `:key: val` syntax as a shorthand for just one or two keywords. Use the `---` syntax if you have many keywords you wish to specify, or if some values will span multiple lines. ``` ### Roles Roles are very similar to directives, but they are written entirely in one line. The syntax of a role is: ```markdown Some content {rolename}`and here is my role's content!` ``` Of course, roles will only work if `rolename` is a valid role name! The `abbr` role creates inline abbreviations, for example, `` {abbr}`MyST (Markedly Structured Text)` `` will become {abbr}`MyST (Markedly Structured Text)`! When you hover over[^1] the abbreviation you will see the `title` appear! [^1]: Abbreviations are also great structured data for screen-readers! Roles are defined inline, with an identifier and input. There are a number of roles included in MyST, including abbreviations, subscript, and superscript, as well as inline [](./math.md). Unknown roles will still be parsed as well: ```{myst} Here is an {abc}`unknown role`. ``` Options for roles can be included inline. See [](./inline-options.md) for more information. ```markdown Here is my {span #label .class-name key="value"}`custom span`. ``` (nesting-content)= ## Nesting content blocks in Markdown If you’d like to nest content blocks inside one another in Markdown (for example, to put a `{note}` inside of a `{margin}`), you may do so by adding extra backticks (`` ` ``)[^colon] to the outer-most block. For example, two [admonitions](./admonitions.md) nested in side of each other: `````{myst} ````{important} ```{note} Here's my `important`, highly nested note! πŸͺ† ``` ```` ````` [^colon]: You can also use this same technique and add colons to the initial directive or fence. See an [example](#example-fence) of when to use each syntax. This works for literal code blocks as well. For example, to show triple-backticks on this page we are using following syntax: `````{myst} ```` ``` ``` ```` ````` --- ### Packages Jtex Docs Index (`packages/jtex/docs/index.md`) --- title: jtex description: jtex is a command line tool and library for rendering LaTeX documents from Jinja-style templates. --- `jtex` is a command line tool (CLI) for rendering $\LaTeX$ documents from Jinja-style templates. This package uses [nunjucks](https://mozilla.github.io/nunjucks/) (a port of Jinja) as the template engine with a modified environment and syntax that plays well with $\LaTeX$'s markup. ::::{grid} 1 1 2 3 :::{card} :link: ./create-a-latex-template.md **Create a Template** πŸ†• ^^^ Learn how to create a $\LaTeX$ template for a scientific journal article or Beamer presentation using `jtex` and MyST Markdown. ::: :::{card} :link: https://github.com/myst-templates **Browse Templates** πŸš€ ^^^ Our $\LaTeX$ templates are curated by the MyST community and include templates to render over 400 journals! ::: :::{card} :link: ./command-line.md **Command Line Interface** ✨ ^^^ Use `jtex` to list templates, quickly render content, or fix your `template.yml`, or parse your $\LaTeX$ files for used packages. ::: :::: ```{important} :class: dropdown # Looking for Templates? MyST Templates are available in the [myst-templates organization](https://github.com/myst-templates) on GitHub. You can also see all listed community templates using `myst templates list`, or browse the [api](https://api.mystmd.org/templates/tex) if you are into JSON. To create your own template see [](./create-a-latex-template.md). ``` ## Project Goals - Provide a data-driven templating markup for $\LaTeX$ - Provide validation of templates and supplied options when rendering a template - Work with standardized frontmatter to make authors, affiliations, etc. easy to template - Work with the MyST ecosystem of tools - Support many user supplied templates, local templates, etc. **Not Goals** - Translation of MyST to $\LaTeX$, instead see `myst-to-tex` or [using pandoc with `jtex`](pandoc-comparison.md) ## Installation Install the package globally using npm: ```bash npm install jtex ``` and confirm correct installation by typing: ```bash jtex --version ``` ## Usage with MyST The main usage for `jtex` is with `myst` and `curvenote` command line tools, both of which can compile markdown into $\LaTeX$ for templating with `jtex`. ## Simple Example A document can be used very simply with the document as `doc`, the contents of which are documented in [](document.md). Be sure to include the `[-IMPORTS-]` and the `[-CONTENT-]`. ```latex % template.tex \documentclass{article} [-IMPORTS-] \title{[-doc.title-]} \author{[-doc.authors[0].name-] ([-doc.authors[0].email-])} \begin{document} \maketitle [-CONTENT-] The End! \end{document} ``` --- ### Packages Myst Cli Docs Index (`packages/myst-cli/docs/index.md`) --- title: myst-cli description: myst-cli is a command line tool for processing MyST markdown files --- [](https://www.npmjs.com/package/myst-cli) `myst-cli` is a command line tool for processing MyST markdown files --- ### Packages Myst Parser Docs Index (`packages/myst-parser/docs/index.md`) # myst-parser [](https://www.npmjs.com/package/myst-parser) [](https://github.com/jupyter-book/mystmd/blob/master/LICENSE) [](https://github.com/jupyter-book/mystmd/actions) [](https://executablebooks.github.io/myst-parser) {abbr}`MyST (Markedly Structured Text)` is a flavor of markdown inspired from the Sphinx ecosystem and {abbr}`RST (reStructuredText)`. Any [CommonMark](https://commonmark.org/) markdown (such as [Jupyter Notebook](https://jupyter.org) markdown) is natively supported by the MyST parser. The goal of MyST _javascript_ parser ([myst-parser](https://github.com/jupyter-book/mystmd)) is to have overlap with Sphinx ecosystem and {abbr}`RST (reStructuredText)` and provide a flexible parser and renderer that can be used with other content workflows. ```{important} For integration with **Sphinx**, use the Python reference implementation for MyST parser, which can be found at: The following documentation refers only to the Javascript MyST parser. ``` The focus of `mystmd` is on components that are useful in rendering books, papers & reports. This project is associated with [JupyterBook](https://jupyterbook.org/) and maintained by the [Executable Books Community](https://executablebooks.org/). ## Package Responsibilities The `myst-parser` package provides a Javascript implementation of the [MyST](https://myst-parser.readthedocs.io) parser, with the many of the standard directives and roles included. - Parse MyST flavored markdown, which includes directives, roles, and block elements - Export a Markdown Abstract Syntax Tree (`mdast`) that is tested against the MyST specification - Provide extension point for additional directives and roles to be added - Provide a serializer into standard html for all known roles and directives - CSS styling will not be enforced or provided by this repository - Provide extension point for cross-referencing between multiple documents ## Supported Syntax - CommonMark Markdown - Admonitions (callouts) - References and citations - Figures, with cross-references - Math & equations, with cross-references - Common roles and directives that constitute "Core MyST" ## Design Choices and Related Packages The `myst-parser` package currently uses `markdown-it` for parsing markdown. This includes packages that are elsewhere in the executablebooks community including: - [markdown-it-dollarmath](https://github.com/executablebooks/markdown-it-dollarmath) - Math extensions to support inline $\LaTeX$ math surrounded by `$` - [markdown-it-amsmath](https://github.com/executablebooks/markdown-it-amsmath) - Support math that starts with `\begin{equation}`, etc. directly in the content The package also includes community supported markdown-it plugins (e.g. `markdown-it-footnote`, and others as necessary). ```{note} `myst-parser` may adopt portions of the [unified](https://unifiedjs.com/) ecosystem in the future, but will continue to support basic `markdown-it` parsing as this is required in extending markdown parsers in, for example, [VSCode](https://github.com/executablebooks/myst-vs-code). ``` --- ### Packages Myst Spec Docs Index (`packages/myst-spec/docs/index.md`) # MyST Specification 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](https://jupyterbook.org/), which creates educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. ## Overview There are three components that this documentation and repository aims to formalize: 1. the MyST markup language, which is a superset of [CommonMark](https://commonmark.org/) (a standard form of Markdown); 2. the MyST abstract syntax tree (AST), which is the datastructure of a document after it has been parsed, and can be used in transforming and rendering content; and 3. a set of unit-tests that can be used to test implementations of MyST (e.g. in Python and Javascript). ## MyST Markup Language MyST is a superset of [CommonMark](https://commonmark.org/) (a standard form of Markdown) and allows you to directly create β€œdirectives” and β€œroles” as extension points in the language. These extension points are influenced by [ReStructured Text (RST)](https://en.wikipedia.org/wiki/ReStructuredText) and [Sphinx](https://www.sphinx-doc.org/) -- 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. ## MyST Abstract Syntax Tree Fundamentally, the specification for MyST documents can be broken down into abstract syntax tree (AST) node types and their document-level counterparts. The `myst-spec` AST builds on [Markdown AST, or `mdast`](https://github.com/syntax-tree/mdast), an intermediate format that in turn builds upon the existing [Universal Syntax Tree, or `unist` spec](https://github.com/syntax-tree/unist). `unist` is used throughout the [unifiedjs](https://unifiedjs.com/) Javascript community with hundreds of [existing transformations](https://unifiedjs.com/explore/), [utilities](https://unifiedjs.com/explore/keyword/unist-util/) and [serializers](https://unifiedjs.com/explore/keyword/rehype/). `unist` has a simple format, with a `type` defining the node optional properties on the node and optional `children` (a leaf node has a `value`). The MyST AST introduces nodes for directives and roles, as well as numerous new features, like admonitions, citiations, and equations, all of which build upon `mdast` and other existing standards and nomenclature. The MyST AST, like `mdast`, is serializable to JSON or YAML, and can be effectively shared between projects, languages, and implementations. ## MyST Test Cases To validate implementations of the MyST spec, a suite of test cases is provided [here in `myst.tests.json`](https://unpkg.com/browse/myst-spec/dist/). This file is a JSON list of test cases with MyST markup, MyST AST, and example HTML in some cases. The cases are similar to [CommonMark test cases](https://spec.commonmark.org/) with the addition of the AST representation. The MyST test cases include all the CommonMark examples as well as many MyST specific examples. ```{note} These test cases are still being expanded as the spec is developed. They do not yet include all edge cases and are also subject to change as the spec is developed. ``` ```{attention} **Test Cases** Test cases are available for download here: https://unpkg.com/browse/myst-spec/dist/ ``` ## Working with the MyST AST ```{warning} The `myst-spec` AST is in development; any structures or features present in the JSON schema may change at any time without notice. ``` This documentation contains all the node types used to construct a MyST document. Conventionally, the AST representation of a MyST document represents the state immediately after parsing. This means, for example, references are not resolved, directive/role structures are still present, etc. You may work with AST nodes by either modifying or adding to them to modify and update the corresponding MyST document, or you may transform and reduce them into a simpler structure to consume in other contexts. --- ### Packages Myst To Jats Docs Index (`packages/myst-to-jats/docs/index.md`) --- title: myst-to-jats description: myst-to-jats is library for converting MyST documents to JATS XML. --- [](https://www.npmjs.com/package/myst-to-jats) `myst-to-jats` is a library for converting MyST documents into JATS. **Goals** - Convert from `myst-spec` AST documents into JATS XML **Not Goals** - Read JATS, this package is for serialization only - see `jats-to-myst` ## Installation Install the package into your virtual environment using npm: ```bash npm install myst-to-jats ``` ## Simple example Below we construct a AST tree using `unist-builder`, use the `mystToJats` plugin in a `unified` pipeline and `stringify` the document into a $\LaTeX$ file. ```typescript import { unified } from 'unified'; import { u } from 'unist-builder'; import mystToJats from 'myst-to-jats'; // Create a AST document, or parse using mystmd const tree = u( 'root', u('paragraph', [ u('text', { value: 'This is a unicode β€œfraction”: ' }), u('inlineMath', { value: 'Β½' }), ]), ); // Use the plugin, and stringify the tree const file = unified().use(mystToJats).stringify(tree); // Log the results console.log(file.result.value); ``` The document that we fed in was quite simple, and the `Β½` unicode characters as well as the quotes are nicely transformed into the appropriate $\LaTeX$: ```latex This is a unicode ``fraction'': $\frac{1}{2}$ ``` ## Overview The `myst-to-jats` library aims to translate all standard MyST syntax to sensible $\LaTeX$ syntax, as well as be extensible to other plugins. --- ### Packages Myst To Md Docs Index (`packages/myst-to-md/docs/index.md`) --- title: myst-to-md description: myst-to-md is library for converting MyST abstract syntax trees to markdown. --- [](https://www.npmjs.com/package/myst-to-md) `myst-to-md` is a library for converting MyST abstract syntax trees to markdown. **Goals** - Convert from `myst-spec` AST documents into markdown - Work as a `unifiedjs` plugin and in the `mystmd` ecosystem **Not Goals** - Read Markdown, this package is for serialization only ## Installation Install the package into your virtual environment using npm: ```bash npm install myst-to-md ``` ## Simple example Below we construct a AST tree using `unist-builder`, use the `mystToMd` plugin in a `unified` pipeline and `stringify` the document into a Markdown file. ```typescript import { unified } from 'unified'; import { u } from 'unist-builder'; import mystToMd from 'myst-to-md'; // Create a AST document, or parse using mystmd const tree = u( 'root', u('paragraph', [ u('text', { value: 'This is a unicode β€œfraction”: ' }), u('inlineMath', { value: 'Β½' }), ]), ); // Use the plugin, and stringify the tree const file = unified().use(mystToMd).stringify(tree); // Log the results console.log(file.result.value); ``` ## Overview The `myst-to-md` library aims to translate all standard MyST syntax to markdown, as well as be extensible to other plugins. --- ### Packages Myst To Tex Docs Index (`packages/myst-to-tex/docs/index.md`) --- title: myst-to-tex description: myst-to-tex is library for converting MyST documents to LaTeX. --- [](https://www.npmjs.com/package/myst-to-tex) `myst-to-tex` is a library for converting MyST documents into LaTeX. **Goals** - Convert from `myst-spec` AST documents into $\LaTeX$ markup - Work with [jtex](xref:jtex) to template documents - Work as a `unifiedjs` plugin and in the `mystmd` ecosystem **Not Goals** - Read LaTeX, this package is for serialization only ## Installation Install the package into your virtual environment using npm: ```bash npm install myst-to-tex ``` ## Simple example Below we construct a AST tree using `unist-builder`, use the `mystToTex` plugin in a `unified` pipeline and `stringify` the document into a $\LaTeX$ file. ```typescript import { unified } from 'unified'; import { u } from 'unist-builder'; import mystToTex from 'myst-to-tex'; // Create a AST document, or parse using mystmd const tree = u( 'root', u('paragraph', [ u('text', { value: 'This is a unicode β€œfraction”: ' }), u('inlineMath', { value: 'Β½' }), ]), ); // Use the plugin, and stringify the tree const file = unified().use(mystToTex).stringify(tree); // Log the results console.log(file.result.value); ``` The document that we fed in was quite simple, and the `Β½` unicode characters as well as the quotes are nicely transformed into the appropriate $\LaTeX$: ```latex This is a unicode ``fraction'': $\frac{1}{2}$ ``` ## Overview The `myst-to-tex` library aims to translate all standard MyST syntax to sensible $\LaTeX$ syntax, as well as be extensible to other plugins. --- ### Packages Myst Transforms Docs Index (`packages/myst-transforms/docs/index.md`) --- title: myst-transforms description: myst-transforms contains a number of transformations for MyST ASTs --- [](https://www.npmjs.com/package/myst-transforms) `myst-transforms` is a library for transforming `myst` markdown documents. ## Overview These transforms take AST from `mystmd` and turn it into usable forms, enforce document structure, or provide other utilities. These utilities are available on npm: ```bash npm install myst-transforms ``` You can use the plugins as follows: ```typescript import { unified } from 'unified'; import { mathPlugin } from 'myst-transforms'; unified() .use(mathPlugin, { macros: {} }) // Add the plugin with any options .run(tree); // Run the AST through the set of plugins // The AST has now been modified in place. ``` --- ### Packages Myst Transforms Docs Overview (`packages/myst-transforms/docs/overview.md`) --- title: What's in store description: List of transforms included in the myst-transforms package. --- ## List of Transforms Admonitions : Add headers to each admonition (callout), such as `Note` or `Important`. : Optionally replace the header with the first paragraph of text if it is all bold. Blocks : Ensure that all blocks in a document are not nested. Blockquotes : Change attributed blockquotes, those that include a single list item to a figure of `kind` quote, and add the attribution as a figure caption. Caption : Ensure that figure captions are in paragraphs Code : Audit code to ensure that languages are specified, or provide a default language : Ensure that `python` as a language is replaced from `IPython3` or other kernal-like language specifiers. CodeBlock : Codeblocks can live inside of figures, have captions and be references. Transformation ensures that this information isn't lost from the original parsing of AST. : Note: this should move into the parser in the future. Footnotes : Pull the footnote definitions into a reference object. HTML : Parse HTML nodes and replace their contents. HTML Ids : Ensure that referenceable nodes have proper HTML Ids (start with a letter, no spaces or fancy characters) : HTML Ids are more strict than the internal labels used for cross-references, and this is up to the transform to provide, not the renderer. Images : Add alt text to images if it is not defined, from the captions. Keys : Add unique identifiers to each node, helpful for rendering as well as referring to a document in the wild. These are not aiming to be persisted across multiple builds of the document, for that you should use a label (and associated HTML Id). Math : Use KaTeX to create and provide errors/warnings about math rendering. Math Label : Parse latex to strip \label and simple equation environments from math, and put this in AST directly. MyST Cleanup : A few utilities for lifting children and getting rid of some information about the parsed document from MyST. For example, the `mystDirective` and `mystRole` wrapper nodes are removed. Targets : Propagate targets (i.e. `(my-id)=`) to the following node : Add HTML friendly identifiers to headings. ## Plugin Collections A few of the plugins are exposed in a `basicTransformationsPlugin` that does a number of the expected transformations without any user supplied options. See the code (look for function `basicTransformations` in file `packages/myst-transforms/src/basic.ts`) for exactly which plugins are included. If you are depending on this, ideally use the individual plugins directly, which will always provide options. --- ### Packages Myst Spec Docs Features Overview (`packages/myst-spec/docs/features/overview.md`) # Overview MyST (Markedly Structured Text) is designed to create publication-quality documents written entirely in Markdown. The main use case driving the development and design of MyST is [JupyterBook](https://jupyterbook.org/), which helps you create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. The extensions and design of MyST is inspired by the [Sphinx](https://www.sphinx-doc.org/) and [ReStructured Text](https://docutils.sourceforge.io/rst.html) (RST) ecosystems. > MyST is designed to harness the extensibility and community of RST and bring these super-powers into Markdown. MyST is a superset of [CommonMark](./commonmark.md) (the standard form of Markdown) and allows you to directly create β€œdirectives” and β€œroles” as extension points in the language. `directives` are block-level extension points, like [callout panels](./admonitions.md), tabs, [figures](./figures.md) or embedded charts; and roles are inline extension points, for components like [references](./references.md) or [inline math](./math.md). ## Directives & Roles Roles and directives are two of the most powerful parts of MyST. They are kind of like functions, but written in a markup language. They both serve a similar purpose, but roles are written in one line whereas directives span many lines. They both accept different kinds of inputs, and what they do with those inputs depends on the specific role or directive being used. ### Directives Directives are multi-line containers that include an identifier, arguments, options, and content. Examples include [admonitions](./admonitions.md), [figures](./figures.md), and [equations](./math.md). #### Specification ```{include} ../nodes/directive.md ``` #### Example ```{include} ../examples/directive.md ``` In addition to the directive name and the directive content, directives allow two other configuration points: 1\) **directive arguments** - a list of words that come just after the `{directivename}`. ```` ```{directivename} arg1 arg2 My directive content. ``` ```` 2\) **directive options** - a collection of flags or key/value pairs that come just underneath `{directivename}`. There are two ways to write directive options `````{list-table} * - 2a) Options as `:key: val` pairs.\ Great for a few options. - 2b) Options as `key: val` pairs enclosed by `---` lines.\ This is parsed as YAML, and easier for listing many options. * - ```` ```{directivename} :key1: metadata1 :key2: metadata2 My directive content. ``` ```` - ```` ```{directivename} --- key1: metadata1 key2: metadata2 --- My directive content. ``` ```` ````` ```{tip} Remember, specifying directive keywords with `:key:` or `---` will make no difference. We recommend using `---` if you have many keywords you wish to specify, or if some values will span multiple lines. Use the `:key: val` syntax as a shorthand for just one or two keywords. ``` ### Roles Roles are very similar to directives, but they are written entirely in one line. #### Specification ```{include} ../nodes/role.md ``` #### Example ```{include} ../examples/role.md ``` Of course, roles will only allow custom behavior work if `name` is a valid role name! The `abbr` role creates inline abbreviations, for example, `` {abbr}`MyST (Markedly Structured Text)` `` will become {abbr}`MyST (Markedly Structured Text)`! When you hover over[^1] the abbreviation you will see the `title` appear! [^1]: Abbreviations are also great structured data for screen-readers! Roles are defined inline, with an identifier and input. There are a number of roles included in MyST, including abbreviations, subscript, and superscript, as well as inline [](./math.md). ## Nesting content blocks in Markdown If you’d like to nest content blocks inside one another in Markdown (for example, to put a {note} inside of a {margin}), you may do so by adding extra backticks (`) to the outer-most block. This works for literal code blocks as well. For example, the following syntax: ````` ```` ``` ``` ```` ````` yields ```` ``` ``` ```` Thus, if you’d like to nest directives inside one another, you can take the same approach. For example, the following syntax: ````` ````{important} ```{note} Here's my `important`, highly nested note! πŸͺ† ``` ```` ````` produces a nested, `important` > `note`: ````{important} ```{note} Here's my `important`, highly nested note! πŸͺ† ``` ```` --- ### Abbreviations.Yml (`docs/abbreviations.yml`) version: 1 project: abbreviations: # Alphabetical order AMS: American Mathematical Society API: Application Programming Interface AST: Abstract Syntax Tree CLI: Command Line Interface CRediT: Contributor Roles Taxonomy CSS: Cascading Style Sheet CSV: comma-separated values DOI: Digital Object Identifier ESM: ECMAScript Modules GPU: Graphics Processing Unit HTML: Hypertext Markup Language ID: Identifier ISNI: International Standard Name Identifier JATS: Journal Article Tag Suite JSON: JavaScript Object Notation LTS: Long Term Support MyST: Markedly Structured Text NISO: National Information Standards Organization OA: Open Access PDF: Portable Document Format PID: Persistent Identifier POSIX: Portable Operating System Interface REES: Reproducible Execution Environment Specification ROR: Research Organization Registry RRID: Research Resource Identifier RST: reStructuredText SPDX: Software Package Data Exchange TLA: Three Letter Acronym TOC: table of contents TPU: Tensor Processing Unit URL: Uniform Resource Locator VoR: Version of Record WASM: WebAssembly YAML: Yet Another Markup Language XML: Extensible Markup Language --- ### Accessibility And Performance (`docs/accessibility-and-performance.md`) --- title: Accessibility and Performance short_title: Accessibility & Performance description: MyST builds documents and websites that are accessible to everyone and quick to load on any device. --- ## Accessibility Most of the user-facing interface lives in [`myst-theme`](https://github.com/jupyter-book/myst-theme). These default themes build on top of [Remix](https://remix.run/), which provides sensible accessibility defaults. This section describes the broader goals and considerations around accessibility for the MyST themes.[^scope] [^scope]: **This page is scoped to the default MyST themes** This page describes the **default MyST website themes** (the Remix-based [`book` and `article` themes](https://github.com/jupyter-book/myst-theme) that ship with `mystmd`). Sites built with a custom theme or a different renderer may behave differently. For more information about accessibility across all of Jupyter, see the [Jupyter Accessibility Working Group](https://jupyter-accessibility.readthedocs.io). :::{card} Open an a11y issue Β» :link: https://github.com/jupyter-book/myst-theme/issues/new?labels=a11y If you find a barrier on a MyST site, open an issue in `myst-theme`. A clear way to reproduce helps even if you can't propose a fix. ::: ### Our accessibility goals The [default MyST web themes](https://github.com/jupyter-book/myst-theme) aim to meet [WCAG 2.1 AA](https://www.w3.org/TR/WCAG21/), the level required of US public-sector and many private websites under [ADA Title II](https://www.ada.gov/resources/2024-03-08-web-rule/). Accessibility bugs there are treated like any other bug. See the [`a11y` issues label](https://github.com/jupyter-book/myst-theme/labels/a11y) for open accessibility issues. Accessibility contributions follow the [normal contribution process](./contributing.md). ### How accessible is MyST today? The MyST themes ship with these accessibility behaviors: - Semantic HTML for articles, asides, figures, navigation, and captions. - A skip-to-content shortcut and full keyboard navigation for menus, search, and the table of contents. - Focusable, scrollable cell outputs so keyboard and screen-reader users can reach long stdout, stderr, and equation output. - Color-contrast-aware defaults in the book and article themes, including code cells and error states. - Pre-rendered math that ships as accessible HTML rather than images. - Alt-text for images sourced from figure captions when present. - `aria` labels and roles on interactive controls (theme toggle, document outline, search dialog, footnote return links). In April 2026 we completed a focused round of work to [align with WCAG 2.1 AA](https://github.com/jupyter-book/mystmd/issues/2802). We know there is always ongoing work to be done to improve accessibility and welcome both guidance and contributions, see [](#a11y:contribute). (a11y:monitor)= ### How we monitor accessibility On every push to `main`, `myst-theme` runs an automated accessibility audit in CI. It builds the current themes and runs [`berkeley-cdss/myst-a11y`](https://github.com/berkeley-cdss/myst-a11y) (which wraps [axe-core](https://github.com/dequelabs/axe-core)) against the [reference pages](https://myst-theme.netlify.app), checking WCAG 2.0 and 2.1 (A & AA). Results are surfaced in a tracking issue with the [`a11y-audit` label](https://github.com/jupyter-book/myst-theme/labels/a11y-audit). It summarizes the current issue counts broken down by rule (such as color-contrast, label, and image-alt) and by page. If an issue with that label is already open, it will be updated on each new workflow run. If there is no open issue, then a new one is created. ### Cell outputs are not under MyST's control Many libraries emit interactive JavaScript or images as part of executing code (e.g., Plotly, ipywidgets, etc). In these cases, MyST does not have control over the structure of what is created, and cannot guarantee their accessibility. If you find a cell output that is not accessible, please report it in the repository for the tool that produced it. The fix will most likely need to happen in that upstream tool rather than in the MyST theme. (a11y:contribute)= ### Where can I follow along or contribute? Open accessibility work is tracked under the [`a11y` label in `myst-theme`](https://github.com/jupyter-book/myst-theme/labels/a11y). There's a thread for broader discussion and tracking in the [Accessibility Improvements tracking issue](https://github.com/jupyter-book/myst-theme/issues/238). (a11y:check-your-site)= ### How can I check the accessibility of my own site? A few tools that others in the community have found useful: - The [Jupyter Accessibility Working Group](https://jupyter-accessibility.readthedocs.io) has a collection of accessibility resources for the broader Jupyter community. - [berkeley-cdss/myst-a11y](https://github.com/berkeley-cdss/myst-a11y) is a GitHub Action built for MyST sites. It runs [axe-core](https://github.com/dequelabs/axe-core) checks against WCAG 2.0 and 2.1 (A and AA) on every push and reports results as a tracking issue. This is the same action MyST runs on its own themes, see [](#a11y:monitor). For a working example, see [data-8/textbook](https://github.com/data-8/textbook/blob/main/.github/workflows/a11y.yml). - [Lighthouse](https://github.com/GoogleChrome/lighthouse) is built into Chrome DevTools and is useful for a quick audit of a single page. - [JupyCheck](https://jupycheck.vercel.app/) checks accessibility of source notebooks in Jupyter interfaces. This is useful if you also want readers to launch Jupyter sessions from your MyST site. ## Performance The [default MyST themes](https://github.com/jupyter-book/myst-theme) are built on [Remix](https://remix.run/) and [React](https://reactjs.org/). These provide link prefetching, smaller download sizes through modern bundlers, image optimization, and faster page transitions that update only the part of the page that changed. We follow the [PRPL pattern](https://web.dev/apply-instant-loading-with-prpl/) where possible: - **P**reload the most important resources. - **R**ender the initial route as soon as possible. - **P**re-cache remaining assets. - **L**azy load other routes and non-critical assets. Hover over a link in the navigation with your browser's developer tools open: the next page is fetched as soon as you hover, before you click. Only that page's content and metadata are downloaded, not a full HTML document, and shared assets like fonts and styles are reused across pages. Pages you've already visited are served from your browser's cache. Locally, MyST rebuilds and rerenders in under 150ms and restores your scroll position, so you can preview changes without losing your place. Performance of a deployed site depends on the infrastructure that serves it. See [deployment](./deployment.md) for options. ### Lighthouse [Lighthouse](https://github.com/GoogleChrome/lighthouse) is a Chrome tool that measures performance, accessibility, and search-engine readiness. It flags asset, image, and crawler issues that affect both real-world load times and search rankings. ```{figure} ./images/lighthouse-2022_09_15.png :label: lighthouse A 2022 Lighthouse run on a deployed MyST site using Curvenote's global CDN. ``` ```{warning} Lighthouse scores depend on your network, machine, and the specific page measured; the figure above is a 2022 snapshot. If you find a place where MyST performance can be improved, please [open an issue](https://github.com/jupyter-book/mystmd/issues). ``` --- ### Admonitions (`docs/admonitions.md`) --- title: Callouts & Admonitions description: Callout blocks or admonitions, like "notes" or "hints" are outlined or shaded areas of a document to bring attention to particular information. thumbnail: ./thumbnails/admonitions.png --- Callouts, or "admonitions", highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning. In MyST we call these kinds of directives {myst:directive}`admonitions `, however, they are almost always used through their _named_ directives, like {myst:directive}`note` or {myst:directive}`danger`. There are ten kinds[^docutils-admonitions] of admonitions available by default, and others may be introduced by [plugins](./plugins.md): ```{list-table} Named admonitions that can be used as directives :label: admonitions-list * - πŸ”΅ {myst:directive}`note` - 🟠 {myst:directive}`attention` * - πŸ”΅ {myst:directive}`important` - 🟠 {myst:directive}`caution` * - 🟒 {myst:directive}`hint` - 🟠 {myst:directive}`warning` * - 🟒 {myst:directive}`seealso` - πŸ”΄ {myst:directive}`danger` * - 🟒 {myst:directive}`tip` - πŸ”΄ {myst:directive}`error` ``` [^docutils-admonitions]: These admonitions are the same as those used in [docutils](https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions) and Sphinx. For example, try changing the following example of a `{tip}` admonition to a `{warning}`: ```{myst} :::{tip} Try changing `tip` to `warning`! ::: ``` See below for a demo of each admonition in the default theme. `````{tab-set} ````{tab-item} Note ```{note} This is an note admonition ``` ```` ````{tab-item} Important ```{important} This is an important admonition ``` ```` ````{tab-item} Hint ```{hint} This is an hint admonition ``` ```` ````{tab-item} See Also ```{seealso} This is an seealso admonition ``` ```` ````{tab-item} Tip ```{tip} This is an tip admonition ``` ```` ````{tab-item} Attention ```{attention} This is an attention admonition ``` ```` ````{tab-item} Caution ```{caution} This is an caution admonition ``` ```` ````{tab-item} Warning ```{warning} This is an warning admonition ``` ```` ````{tab-item} Danger ```{danger} This is an danger admonition ``` ```` ````{tab-item} Error ```{error} This is an error admonition ``` ```` ````` ## Admonition Titles All admonitions have a single argument ({myst:directive}`docs `), which is the admonition title and can use Markdown. If a title argument is not supplied the first node of the {myst:directive}`admonition.body` is used if it is a `heading` or a paragraph with fully bold text; otherwise the name of the directive is used (e.g. `seealso` becomes `See Also`; `note` becomes `Note`). ```{myst} :::{tip} Admonition _title_ Here is an admonition! ::: ``` (admonition-github-compatibility)= :::::::{tip} Compatibility with GitHub :class: dropdown GitHub Markdown transforms blockquotes that start with a bold `Note` or text with `[!NOTE]` into a simple admonition (see [GitHub](https://github.com/community/community/discussions/16925)). This syntax only works for `note`, `important` or `warning`. MyST transforms these blockquotes into the appropriate admonitions with a `simple` {myst:directive}`admonition.class`. ```{myst} > [!NOTE] > Highlights information that users should take into account, even when skimming. > [!IMPORTANT] > Crucial information necessary for users to succeed. > [!WARNING] > Critical content demanding immediate user attention due to potential risks. > **Note** > This is a note > **Warning** > This is a warning ``` ::::::: ::::{tip} Compatibility with Pandoc & Quarto :class: dropdown In Quarto/Pandoc Markdown admonitions are styled with special classes (like `{.callout-note}` or `{.callout-tip}`). If you are using Jupyter Book V1 or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example: ```{myst} ::: {.callout-tip} ## Tip with Caption This is an example of a callout with a caption. ::: ``` :::: ::::{warning} Compatibility with Sphinx :class: dropdown In Sphinx, all named admonitions (like `{note}` or `{tip}`), have **no arguments**. If you place content on the first line it will instead be prepended to the admonition body. If you are using Jupyter Book V1 or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example: ```{myst} :::{admonition} The Title :class: hint This is the body. ::: ``` :::: (admonition-dropdown)= ## Admonition Dropdown To turn an admonition into a dropdown, add the `dropdown` {myst:directive}`admonition.class` to them. Dropdown admonitions use the `
` HTML element (meaning they also will work without JavaScript!), and they can be helpful when including text that shouldn't immediately visible to your readers. To have a dropdown-style admonition start open, add the {myst:directive}`admonition.open` option. ```{myst} :::{note} Click Me! πŸ‘ˆ :class: dropdown πŸ‘‹ This could be a solution to a problem or contain other detailed explanations. ::: :::{note} Hide Me! πŸ‘ˆ :class: dropdown :open: true πŸ‘‹ This is an admonition with a lot of text. The user can hide it if they want. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. ::: ``` :::{seealso} You can also use a `{dropdown}` :class: dropdown You can also use a {myst:directive}`dropdown` directive, which provides a more compact writing experience and is simpler in the displayed style. See [](#dropdowns) for more information. ::: ## Simpler Admonitions Admonitions can additionally be styled as `simple`, and can optionally hide the icon using the {myst:directive}`admonition.icon` option. ```{myst} :::{important} Magic :class: simple This is a magic cat. It casts a luck spell on you that lasts an hour. \ **぀( ο½₯Ο‰ο½₯ｑ)γ€β”β˜†γƒ»*。** ::: ``` Removing the icon from an admonition allows using a custom emoji for style. ```{myst} :::{danger} 🎀 Transcript. **Speaker:** John Smith :icon: false β€” To begin this lecture, I would like to ask the audience some questions. ... β€” The next assignment has to be handed in by 01.05. Thanks everyone for attending. ::: ``` Multiple classes can be combined using, for example, [inline options](./inline-options.md): ```{myst} :::{warning .simple .dropdown icon=false open=true} ✍️ NB The proof of the lemma for $x \leqslant 0$ is left to the reader. ::: ``` --- ### Analytics (`docs/analytics.md`) --- title: Adding Analytics to your MyST Website short_title: Analytics description: Add Google Analytics or Plausible to your MyST website with a site configuration key. thumbnail: ./thumbnails/analytics.png --- By default, MyST sites contain no tracking cookies or analytics. However, we offer support for two analytics tracking systems: 1. [Google Analytics](https://marketingplatform.google.com/about/analytics/); and 2. [Plausible](https://plausible.io/), which is privacy-friendly alternative to Google. These are set using template specific options in your site configuration using either an `analytics_google` or an `analytics_plausible` key. See [](#site-options) for more on site options and how to set them. ## Google Analytics Use the `site.options.analytics_google` configuration, with the contents being your **Measurement ID** (G-XXXXXX) or **Tracking ID** (UA-XXXXXX). ```yaml version: 1 site: options: analytics_google: UA-XXXXX # Measurement ID or Tracking ID ``` See [Google Analytics docs](https://developers.google.com/analytics/devguides/collection/gtagjs) for more information on how to find this Measurement ID. ## Plausible Use the `site.options.analytics_plausible` configuration, with the contents being the **domain** you are tracking. ```yaml version: 1 site: options: analytics_plausible: mystmd.org # Domain(s) to track ``` See [Plausible docs](https://plausible.io/docs/plausible-script) for more information on how to find the domain. Note, you only copy in the contents of: `data-domain="COPY_THIS"`, which can be a comma-separated list for multiple domains. ## Testing your integration Run `myst start` and view the page source. The analytics section should be in the `` section of the HTML, you should also start to see real-time tracking in your dashboard. --- ### Asides (`docs/asides.md`) --- title: Asides, Margin Content, and Sidebars short_title: Asides & Margins description: Asides provide an easy way to represent content that is only indirectly related to the article's main content, such as in the sidebar or margin. --- Asides provide an easy way to represent content that is only indirectly related to the article's main content. Where supported, MyST will attempt to display an {myst:directive}`aside` _as close as possible to_β€”but separate fromβ€”the main article, such as in the side-margin. ```{aside} Margin Content Here’s some margin content! It was created by using the {myst:directive}`margin` directive in a Markdown, we can include images: or any other sort of content! ``` ```markdown :::{aside} Margin Content Here’s some margin content! It was created by using the {myst:directive}`margin` directive in a Markdown, we can include images: or any other sort of content! ::: ``` You can also refer to this directive using {myst:directive}`margin` or {myst:directive}`sidebar`, which will have slightly different classes applied in the future. :::{warning} Experimental Many of the features on this page are experimental and may change at any time. These elements can conflict with the document outline when they are both competing for the margin space (see [#170](https://github.com/jupyter-book/myst-theme/issues/170)). There is, as yet, no plugin available for transforming this directive into Typst. ::: % Using bold here, until we fix #170 **Topics** A topic is like a block quote with a title, or a self-contained section. Use the "topic" directive to indicate a self-contained idea that is separate from the flow of the document. Semantically, this is an `