# MyST - Markedly Structured Text [![PyPI][pypi-badge]][pypi-link] [![Conda][conda-badge]][conda-link] **MyST is a rich and extensible flavor of Markdown meant for technical documentation and publishing**. MyST is a flavor of markdown that is designed for simplicity, flexibility, and extensibility. Here are a few major features :::{panels} :container: +full-width text-center :column: col-lg-4 px-2 py-2 :card: **[CommonMark compliant](commonmark-block-tokens)** ✔ ^^^ MyST is a superset of [CommonMark Markdown][commonmark]. Any CommonMark document is also MyST-compliant. --- **[Extra syntax for authoring](extended-block-tokens)** ✍ ^^^ MyST extends CommonMark with [syntax meant for scholarly writing and technical documentation](extended-block-tokens). --- **[Extendable syntax](syntax/directives)** 🚀 ^^^ MyST provides [roles](syntax/roles) and [directives](syntax/directives), allowing you to extend MyST's functionality. --- **[Compatible with Sphinx](sphinx/index.md)** 📄 ^^^ MyST is inspired by Sphinx, and comes with [its own Sphinx parser](sphinx/index.md). [Write your Sphinx docs in Markdown](sphinx:usage/quickstart), or convert existing [RST to Markdown][rst-to-myst] from the CLI or [using an interactive web interface][mystyc]! --- **[Hackable with Python](api/index.md)** 🐍 ^^^ This MyST parser is built on top of the [`markdown-it-py` package][markdown-it-py], an pluggable Python parser for Markdown. --- **[Hackable with Javascript][markdown-it-myst]** 🌍 ^^^ The [Javascript parser][markdown-it-myst] builds on [markdown-it][markdown-it], and allows you to parse MyST in websites. ::: ## Find the right documentation resources This documentation is organized into a few major sections. **Tutorials** are step-by-step introductory guides to MyST Markdown. **Topic Guides** cover specific areas in more depth, and are organized as discrete "how-to" sections. **Reference** sections describe the API/syntax/etc of the MyST Parser in detail. In addition, here are a few pointers to help you get started. :::{panels} :container: full-width :column: col-lg-4 p-2 --- :header: bg-myst-one **Get started with MyST** ^^^ **[](sphinx/intro.md)**: a step-by-step tutorial. **[](syntax/syntax.md)**: discusses major MyST syntax components. **[The Sphinx guide](sphinx/index.md)**: how to use MyST with your Sphinx documentation. --- :header: bg-myst-two **Learn more about MyST** ^^^ **[](syntax/optional.md)**: additional syntax you can enable for extra features. **[The Python API guide](api/index.md)**: parsing and rendering MyST with Python. **[](explain/index.md)**: background understanding and discussions of MyST markdown. --- :header: bg-myst-three **Get inspired** ^^^ **[Jupyter Book](https://jupyterbook.org)**: An open source project for building beautiful, publication-quality books and documents from computational material, built on top of the MyST Parser. **[The Jupyter Book gallery](https://gallery.jupyterbook.org)**: examples of documents built with MyST. ::: ```{toctree} :hidden: sphinx/intro.md ``` ```{toctree} :caption: MyST Syntax :hidden: syntax/syntax syntax/optional syntax/reference ``` ```{toctree} :hidden: :caption: Topic Guides explain/index.md sphinx/index.md docutils.md api/index.md develop/index.md ``` ```{toctree} :hidden: :caption: About the project examples/index.md develop/_changelog.md GitHub repo ``` ## Acknowledgements The MyST markdown language and MyST parser are both supported by the open community, [The Executable Book Project](https://executablebooks.org). [commonmark]: https://commonmark.org/ [github-ci]: https://github.com/executablebooks/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master [github-link]: https://github.com/executablebooks/MyST-Parser [codecov-badge]: https://codecov.io/gh/executablebooks/MyST-Parser/branch/master/graph/badge.svg [codecov-link]: https://codecov.io/gh/executablebooks/MyST-Parser [rtd-badge]: https://readthedocs.org/projects/myst-parser/badge/?version=latest [rtd-link]: https://myst-parser.readthedocs.io/en/latest/?badge=latest [black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg [pypi-badge]: https://img.shields.io/pypi/v/myst-parser.svg [pypi-link]: https://pypi.org/project/myst-parser [conda-badge]: https://anaconda.org/conda-forge/myst-parser/badges/version.svg [conda-link]: https://anaconda.org/conda-forge/myst-parser [black-link]: https://github.com/ambv/black [github-badge]: https://img.shields.io/github/stars/executablebooks/myst-parser?label=github [markdown-it-py]: https://markdown-it-py.readthedocs.io/ [markdown-it-myst]: https://github.com/executablebooks/markdown-it-myst [markdown-it]: https://markdown-it.github.io/ [rst-to-myst]: https://rst-to-myst.readthedocs.io [mystyc]: https://mystyc.herokuapp.com