Introduction

MyST Markdown (Markedly Structured Text) is an extended Markdown flavor that adds directives and roles inspired by reStructuredText. It is designed for technical documentation and scientific publishing, offering features like admonitions, cross-references, figures with captions, and math blocks within a Markdown-based syntax.

Usage

To convert to/from MyST Markdown, use the .myst file extension, or the --to myst or --from myst options e.g.

stencila convert doc.smd doc.myst

Warning

Stencila's MyST Markdown support is in beta status. If you find bugs or unexpected results please file an issue.

Implementation

Stencila supports bi-directional conversion between Stencila documents and MyST Markdown. MyST directives and roles are mapped to Stencila Schema node types where equivalents exist. The underlying Markdown parser and encoder are shared with CommonMark and other Markdown flavors; see the CommonMark documentation for implementation details.

Limitations

Not all MyST directives and roles have Stencila equivalents; unsupported directives may be imported as raw content or dropped.

Stencila node types without MyST equivalents are lost when encoding to MyST.

MyST-specific features like substitutions, glossaries, and some Sphinx extensions are not supported.

MyST Markdown rendered by Stencila may differ in behavior from MyST rendered by the official MyST parser.