Sphinx configuration options
Contents
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 |
---|---|---|
|
|
If |
|
|
If |
|
() |
List of markdown syntax elements to disable, see the markdown-it parser guide. |
|
|
Enable Markdown extensions, see here for details. |
|
|
If |
|
|
URI schemes that will be recognised as external URLs in |
|
|
If a list, then only these sphinx domains will be searched for when resolving Markdown links like |
|
|
If |
|
|
If |
|
|
Enable auto-generated heading anchors, up to a maximum level, see here for details. |
|
|
Use the specified function to auto-generate heading anchors, see here for details. |
|
|
Add line numbers to code blocks with these languages, see here for details. |
|
|
A mapping of keys to substitutions, used globally for all MyST documents when the “substitution” extension is enabled. |
|
|
A mapping of keys to HTML metadata, used globally for all MyST documents. See Setting HTML Metadata. |
|
|
Place a transition before any footnotes. |
|
|
Reading speed used to calculate |
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 |
---|---|---|
|
|
Allow display math (i.e. |
|
|
Parse |
|
|
If False then inline math will only be parsed if there are no initial/final spaces,
e.g. |
|
|
If False then inline math will only be parsed if there are no initial/final digits,
e.g. |
|
|
Enable direct parsing of amsmath LaTeX environments |
|
|
If using sphinx.ext.mathjax (the default) then |
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.