Sphinx configuration options¶

You can control the behaviour of the MyST parser in Sphinx by modifying your conf.py file. To do so, use the keywords beginning myst_.

Option	Default	Description
`myst_commonmark_only`	`False`	If `True` convert text as strict CommonMark (all options below are then ignored). Note that strict CommonMark is unable to parse any directives, including the `toctree` directive, thus limiting MyST parser to single-page documentations. Use in conjunction with sphinx-external-toc Sphinx extension to counter this limitation.
`myst_disable_syntax`	()	List of markdown syntax elements to disable, see the markdown-it parser guide.
`myst_enable_extensions`	`["dollarmath"]`	Enable Markdown extensions, see here for details.
`myst_url_schemes`	`None`	URI schemes that will be recognised as external URLs in `[](scheme:loc)` syntax, or set `None` to recognise all. Other links will be resolved as internal cross-references.
`myst_heading_anchors`	`None`	Enable auto-generated heading anchors, up to a maximum level, see here for details.
`myst_heading_slug_func`	`None`	Use the specified function to auto-generate heading anchors, see here for details.
`myst_substitutions`	`{}`	A mapping of keys to substitutions, used globally for all MyST documents when the “substitution” extension is enabled.
`myst_html_meta`	`{}`	A mapping of keys to HTML metadata, used globally for all MyST documents. See Setting HTML Metadata.
`myst_footnote_transition`	`True`	Place a transition before any footnotes.
`myst_words_per_minute`	`200`	Reading speed used to calculate {sub-ref}`wordcount-minutes`

List of extensions:

“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
“html_admonition”: Convert <div class="admonition"> elements to sphinx admonition nodes, see the HTML admonition syntax for details
“fieldlist”: Enable field lists, see here for details
“html_image”: Convert HTML <img> elements to sphinx image nodes, see the image syntax 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
“substitution”: substitute keys, see the substitutions syntax for details
“tasklist”: add check-boxes to the start of list items, see the tasklist syntax for details

Math specific, when "dollarmath" activated, see the Math syntax for more details:

Option	Default	Description
`myst_dmath_double_inline`	`False`	Allow display math (i.e. `$$`) within an inline context
`myst_dmath_allow_labels`	`True`	Parse `$$...$$ (label)` syntax
`myst_dmath_allow_space`	`True`	If False then inline math will only be parsed if there are no initial/final spaces, e.g. $a$ but not $ a$ or $a $
`myst_dmath_allow_digits`	`True`	If False then inline math will only be parsed if there are no initial/final digits, e.g. $a$ but not `1$a$` or `$a$2` (this is useful for using `$` as currency)
`myst_amsmath_enable`	`False`	Enable direct parsing of amsmath LaTeX environments
`myst_update_mathjax`	`True`	If using sphinx.ext.mathjax (the default) then `mathjax_config` will be updated, to ignore `$` delimiters and LaTeX environments, which should instead be handled by `myst_dmath_enable` and `myst_amsmath_enable` respectively.

Disable markdown syntax for the parser¶

If you’d like to either enable or disable custom markdown syntax, use myst_disable_syntax. Anything in this list will no longer be parsed by the MyST parser.

For example, to disable the emphasis in-line syntax, use this configuration:

myst_disable_syntax = ["emphasis"]

emphasis syntax will now be disabled. For example, the following will be rendered without any italics:

*emphasis is now disabled*

For a list of all the syntax elements you can disable, see the markdown-it parser guide.