(sphinx/config-options)=
# 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_`.
`````{list-table}
:header-rows: 1
* - 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](https://github.com/executablebooks/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](markdown_it:using).
* - `myst_enable_extensions`
- `["dollarmath"]`
- Enable Markdown extensions, [see here](../syntax/optional.md) for details.
* - `myst_url_schemes`
- `None`
- [URI schemes](https://en.wikipedia.org/wiki/List_of_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](syntax/header-anchors) for details.
* - `myst_heading_slug_func`
- `None`
- Use the specified function to auto-generate heading anchors, [see here](syntax/header-anchors) 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 [](syntax/html_meta).
* - `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](https://ctan.org/pkg/amsmath) LaTeX equations
- "colon_fence": Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
- "deflist"
- "dollarmath": Enable parsing of dollar `$` and `$$` encapsulated math
- "html_admonition": Convert `
` elements to sphinx admonition nodes, see the [HTML admonition syntax](syntax/html-admonition) for details
- "html_image": Convert HTML `
` elements to sphinx image nodes, see the [image syntax](syntax/images) 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](syntax/substitutions) for details
- "tasklist": add check-boxes to the start of list items, see the [tasklist syntax](syntax/tasklists) for details
Math specific, when `"dollarmath"` activated, see the [Math syntax](syntax/math) for more details:
`````{list-table}
:header-rows: 1
* - 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](https://ctan.org/pkg/amsmath)
* - `myst_update_mathjax`
- `True`
- If using [sphinx.ext.mathjax](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-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:
```python
myst_disable_syntax = ["emphasis"]
```
emphasis syntax will now be disabled. For example, the following will be rendered
*without* any italics:
```md
*emphasis is now disabled*
```
For a list of all the syntax elements you can disable, see the [markdown-it parser guide](markdown_it:using).