intro.md

(intro/get-started)=

🚀 Get Started

This page gives a quick overview of how to get started with MyST Markdown, and how to use it within Docutils and Sphinx.

Installation

To install myst-parser use pip:

pip install myst-parser

or Conda:

conda install -c conda-forge myst-parser

(intro/writing)=

Write a Markdown document

To start off, create an empty file called example.md and give it a Markdown title and text. We can now use the myst-docutils-demo CLI tool, from the installed package, to parse this file to HTML:

:::{myst-to-html}

My nifty title

Some text! :::

Extend Markdown with MyST syntax

MyST is an extension of CommonMark Markdown, that includes a rich additional syntax for technical authoring, and can integrate with Docutils and Sphinx.

For example, MyST includes {{role}} and {{directive}} extensions points, to allow for richer features, such as admonitions and figures.

Lets add an admonition directive and sup role to your Markdown page, like so:

::::{myst-to-html} :extensions: colon_fence

My nifty title

Some text!

:::{admonition} Here's my title :class: tip

Here's my admonition content.{sup}1 :::

::::

:::{tip} MyST works with just about all Docutils and Sphinx roles and directives.

Note, Sphinx provides a superset of the Docutils roles and directives, so some may not work in the Docutils CLI. :::

(intro/reference)=

Cross-referencing

MyST-Parser offers powerful cross-referencing features, to link to documents, headers, figures and more.

For example, to add a section reference target, and reference it:

::::{myst-to-html} (header-label)=

A header

My reference ::::

(intro/sphinx)=

Enable MyST in Sphinx

To get started with Sphinx, see their quick-start guide.

To use the MyST parser in Sphinx, simply add the following to your conf.py configuration file:

extensions = ["myst_parser"]

This will activate the MyST Parser extension, causing all documents with the .md extension to be parsed as MyST.

Our example.md file can now be added as the index page, or see the organising content section about creating toctree directives, to add example.md to.

:::{tip} There are a range of great HTML themes that work well with MyST, such as sphinx-book-theme (used here), pydata-sphinx-theme and furo :::

Configuring MyST-Parser

The project:configuration.md section contains a complete list of configuration options for the MyST-Parser.

These can be applied globally, e.g. in the sphinx conf.py:

myst_enable_extensions = ["colon_fence"]

Or they can be applied to specific documents, at the top of the document, in frontmatter:

---
myst:
  enable_extensions: ["colon_fence"]
---

Extending Sphinx

The other way to extend MyST in Sphinx is to install Sphinx extensions that define new roles, directives, etc.

For example, let's install the sphinx-design extension, which will allow us to create beautiful, screen-size responsive web-components.

First, install sphinx-design:

pip install sphinx-design

Next, add it to your list of extensions in conf.py:

extensions = [
  "myst_parser",
  "sphinx_design",
]

Now, we can use the design directive to add a web-component to our Markdown file!

::::{myst-example} :::{card} Card Title Header ^^^ Card content +++ Footer ::: ::::

::::::{myst-example}

::::{tab-set}

:::{tab-item} Label1 Content 1 :::

:::{tab-item} Label2 Content 2 :::

::::

::::::

% TODO this can uncommented once mgaitan/sphinxcontrib-mermaid#109 is fixed % For example, let's install the sphinxcontrib.mermaid extension, % which will allow us to generate Mermaid diagrams with MyST.

% First, install sphinxcontrib.mermaid:

% shell % pip install sphinxcontrib-mermaid %

% Next, add it to your list of extensions in conf.py:

% python % extensions = [ % "myst_parser", % "sphinxcontrib.mermaid", % ] %

% Now, add a mermaid directive to your Markdown file. % For example:

% :::{myst-example} % Here's a cool mermaid diagram! % % {mermaid} % sequenceDiagram % participant Alice % participant Bob % Alice->John: Hello John, how are you? % loop Healthcheck % John->John: Fight against hypochondria % end % Note right of John: Rational thoughts <br/>prevail... % John-->Alice: Great! % John->Bob: How about you? % Bob-->John: Jolly good! % % :::

There are many other great Sphinx extensions that work with MyST, such as the ones used in this documentation:

:sphinx-design: Add beautiful, responsive web-components to your documentation :sphinx-copybutton: Add a copy button to your code blocks :sphinxext-rediraffe: Add redirects to your documentation :sphinxext-opengraph: Add OpenGraph metadata to your documentation :sphinx-pyscript: Execute Python code in your documentation, see here :sphinx-tippy: Add tooltips to your documentation, see here :sphinx-autodoc2: Generate documentation from docstrings, see here :sphinx-togglebutton: Add collapsible content to your documentation :sphinxcontrib.mermaid: Generate Mermaid diagrams

:::{seealso} sphinx-extensions, for a curated and opinionated list of Sphinx extensions. :::