MyST - Markedly Structured Text

Words: rtpg - lobste.rs - 10:52 16-10-2020

A fully-functional markdown flavor and parser for Sphinx.

MyST allows you to write Sphinx documentation entirely in markdown.

MyST markdown provides a markdown equivalent of the reStructuredText syntax,

meaning that you can do anything in MyST that you can do with reStructuredText.

It is an attempt to have the best of both worlds: the flexibility

and extensibility of Sphinx with the simplicity and readability of Markdown.

MyST has the following main features:

You may use MyST markdown strong using reStructuredText in Sphinx.

See p to get started.

Site contents

Getting Started

Installation

Enable MyST in Sphinx

How does MyST parser relate to Sphinx?

Writing MyST in Sphinx

MyST configuration options

The MyST Syntax Guide

Block Tokens Summary

Span (Inline) Tokens Summary

Directives - a block-level extension point

Roles - an in-line extension point

Extra markdown syntax

Math shortcuts

Front Matter

Comments

Block Breaks

Targets and Cross-Referencing

Images

Footnotes

Optional MyST Syntaxes

Admonition directives

Auto-generated header anchors

Definition Lists

Images

Markdown Figures

Direct LaTeX Math

How-To Guides

Include rST files into a Markdown file

Include a file from outside the docs folder (like README.md)

Use sphinx.ext.autodoc in Markdown files

Show backticks inside raw markdown blocks

Automatically create targets for section headers

Frequently Asked Questions

What is the relationship between MyST, reStructuredText, and Sphinx?

What markup language should I use inside directives?

Why doesn’t my role/directive recognize markdown link syntax?

How fast is the myst-parser ?

Python API

Quick-Start

The Parser

The Token Stream

Renderers

Example pages

Wealth Distribution Dynamics in rST

Wealth Distribution Dynamics in MyST

Raw content of each document above

Contribute to MyST

Contributing

The MyST implementation architecture

Testing Infrastructure

Code of Conduct

MyST-Parser API reference

Directive Parsing

MyST Renderers

Sphinx Parser

Changelog

0.12.10 - 2020-09-21

0.12.9 - 2020-09-08

0.12.7 - 2020-08-31

0.12.5 - 2020-08-28

0.12.4 - 2020-08-27

0.12.3 - 2020-08-26

0.12.2 - 2020-08-25

0.12.1 - 2020-08-19

0.12.0 - 2020-08-19

0.11.2 - 2020-07-13

0.11.1 - 2020-07-12

0.11.0 - 2020-07-12

0.10.0 - 2020-07-08

Past Releases

GitHub repo

Why MyST markdown?

While markdown is ubiquitous, it is not powerful enough for writing modern,

fully-featured documentation. Some flavors of markdown support features needed for this,

but there is no community standard around various syntactic choices for these features.

Sphinx is a documentation generation framework written in Python. It heavily-utilizes

reStructuredText syntax, which is another markup language for writing documents. In

particular, Sphinx defines two extension points that are extremely useful:

p and p .

This project is an attempt at combining the simplicity and readability of Markdown

with the power and flexibility of reStructuredText and the Sphinx platform. It

starts with the CommonMark markdown specification, and selectively adds a few extra

syntax pieces to utilize the most powerful parts of reStructuredText.

Note

The CommonMark community has been discussing an “official” extension syntax for many

years now (for example, see

this seven-year-old thread about directives as well as

this more recent converstaion,

and this comment listing several more threads on this topic).

We have chosen a “roles and directives” syntax that seems reasonable and follows other

common conventions in Markdown flavors. However, if the CommonMark community ever

decides on an “official” extension syntax, we will likely utilize this syntax for

MyST.

Acknowledgements

The MyST markdown language and MyST parser are both supported by the open community,

The Executable Book Project.