Configuration

MyST parsing can be configured at both the global and individual document level, with the most specific configuration taking precedence.

Global configuration

Overriding the default configuration at the global level is achieved by specifying variables in the Sphinx conf.py file. All myst_parser global configuration variables are prefixed with myst_, e.g.

myst_enable_extensions = ["deflist"]

See also

Configuration in Docutils, in the Single Page Builds section.

Name	Type	Description
myst_commonmark_only	bool	Use strict CommonMark parser (default: False)
myst_gfm_only	bool	Use strict Github Flavoured Markdown parser (default: False)
myst_enable_extensions	Sequence[str]	Enable syntax extensions (default: [])
myst_disable_syntax	Iterable[str]	Disable Commonmark syntax elements (default: [])
myst_all_links_external	bool	Parse all links as simple hyperlinks (default: False)
myst_url_schemes	Iterable[str] | None	URL scheme prefixes identified as external links (default: ('http', 'https', 'mailto', 'ftp'))
myst_ref_domains	Iterable[str] | None	Sphinx domain names to search in for link references (default: None)
myst_highlight_code_blocks	bool	Syntax highlight code blocks with pygments (default: True)
myst_number_code_blocks	Sequence[str]	Add line numbers to code blocks with these languages (default: [])
myst_title_to_header	bool	Convert a title field in the top-matter to a H1 header (default: False)
myst_heading_anchors	int | None	Heading level depth to assign HTML anchors (default: None)
myst_heading_slug_func	Callable[[str], str] | None	Function for creating heading anchors (default: None)
myst_html_meta	Dict[str, str]	HTML meta tags (default: {})
myst_footnote_transition	bool	Place a transition before any footnotes (default: True)
myst_words_per_minute	int	For reading speed calculations (default: 200)

Extensions

Configuration specific to syntax extensions:

Name	Type	Description
myst_substitutions	Dict[str, Union[str, int, float]]	substitutions: Substitutions mapping (default: {})
myst_sub_delimiters	Tuple[str, str]	substitutions: Substitution delimiters (default: ('{', '}'))
myst_linkify_fuzzy_links	bool	linkify: Recognise URLs without schema prefixes (default: True)
myst_dmath_allow_labels	bool	dollarmath: Parse $$...$$ (label) (default: True)
myst_dmath_allow_space	bool	dollarmath: Allow initial/final spaces in $ ... $ (default: True)
myst_dmath_allow_digits	bool	dollarmath: Allow initial/final digits 1$ ...$2 (default: True)
myst_dmath_double_inline	bool	dollarmath: Parse inline $$ ... $$ (default: False)
myst_update_mathjax	bool	dollarmath: Update sphinx.ext.mathjax configuration to ignore $ delimiters (default: True)
myst_mathjax_classes	str	dollarmath: MathJax classes to add to math HTML (default: 'tex2jax_process|mathjax_process|math|output_area')

Local configuration

New in version 0.18.

The following configuration variables are available at the document level. These can be set in the document front matter, under the myst key, e.g.

---
myst:
  enable_extensions: ["deflist"]
---

Name	Type	Description
commonmark_only	bool	Use strict CommonMark parser (default: False)
gfm_only	bool	Use strict Github Flavoured Markdown parser (default: False)
enable_extensions	Sequence[str]	Enable syntax extensions (default: [])
disable_syntax	Iterable[str]	Disable Commonmark syntax elements (default: [])
all_links_external	bool	Parse all links as simple hyperlinks (default: False)
url_schemes	Iterable[str] | None	URL scheme prefixes identified as external links (default: ('http', 'https', 'mailto', 'ftp'))
ref_domains	Iterable[str] | None	Sphinx domain names to search in for link references (default: None)
highlight_code_blocks	bool	Syntax highlight code blocks with pygments (default: True)
number_code_blocks	Sequence[str]	Add line numbers to code blocks with these languages (default: [])
title_to_header	bool	Convert a title field in the top-matter to a H1 header (default: False)
heading_anchors	int | None	Heading level depth to assign HTML anchors (default: None)
html_meta	Dict[str, str]	HTML meta tags (default: {})
footnote_transition	bool	Place a transition before any footnotes (default: True)
words_per_minute	int	For reading speed calculations (default: 200)

Extensions

Configuration specific to syntax extensions:

Name	Type	Description
substitutions	Dict[str, Union[str, int, float]]	substitutions: Substitutions mapping (default: {})
sub_delimiters	Tuple[str, str]	substitutions: Substitution delimiters (default: ('{', '}'))
linkify_fuzzy_links	bool	linkify: Recognise URLs without schema prefixes (default: True)
dmath_allow_labels	bool	dollarmath: Parse $$...$$ (label) (default: True)
dmath_allow_space	bool	dollarmath: Allow initial/final spaces in $ ... $ (default: True)
dmath_allow_digits	bool	dollarmath: Allow initial/final digits 1$ ...$2 (default: True)
dmath_double_inline	bool	dollarmath: Parse inline $$ ... $$ (default: False)

List of syntax extensions

Full details in the Syntax Extensions section.

amsmath

enable direct parsing of amsmath LaTeX equations

colon_fence

Enable code fences using ::: delimiters, see here for details

deflist

Enable definition lists, see here for details

dollarmath

Enable parsing of dollar $ and $$ encapsulated math

fieldlist

Enable field lists, see here for details

html_admonition

Convert <div class="admonition"> elements to sphinx admonition nodes, see the HTML admonition syntax for details

html_image

Convert HTML <img> elements to sphinx image nodes, see here for details

linkify

Automatically identify “bare” web URLs and add hyperlinks

replacements

Automatically convert some common typographic texts

smartquotes

Automatically convert standard quotations to their opening/closing variants

strikethrough

Enable strikethrough syntax, see here for details

substitution

Substitute keys, see here for details

tasklist

Add check-boxes to the start of list items, see here for details