Configuration

Configuration#

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

1. 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"]

参见

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`	`set[str]`	Enable syntax extensions (default: `set()`)
`myst_disable_syntax`	`collections.abc.Iterable[str]`	Disable Commonmark syntax elements (default: `[]`)
`myst_all_links_external`	`bool`	Parse all links as simple hyperlinks (default: `False`)
`myst_links_external_new_tab`	`bool`	Open all external links in a new tab (default: `False`)
`myst_url_schemes`	`list[str] \| dict[str, None \| str \| dict]`	URI schemes that are converted to external links (default: `{'http': None, 'https': None, 'mailto': None, 'ftp': None}`)
`myst_ref_domains`	`collections.abc.Iterable[str] \| None`	Sphinx domain names to search in for link references (default: `None`)
`myst_fence_as_directive`	`set[str]`	Interpret a code fence as a directive, for certain language names. This can be useful for fences like dot and mermaid, and interoperability with other Markdown renderers. (default: `set()`)
`myst_number_code_blocks`	`collections.abc.Sequence[str]`	Add line numbers to code blocks with these languages (default: `[]`)
`myst_title_to_header`	`bool`	Convert a `title` field in the front-matter to a H1 header (default: `False`)
`myst_heading_anchors`	`int`	Heading level depth to assign HTML anchors (default: `0`)
`myst_heading_slug_func`	`None \| Callable[[str], str] \| str`	Function for creating heading anchors, or a python import path e.g. `my_package.my_module.my_function` (default: `None`)
`myst_html_meta`	`dict[str, str]`	HTML meta tags (default: `{}`)
`myst_footnote_sort`	`bool`	Move all footnotes to the end of the document, and sort by reference order (default: `True`)
`myst_footnote_transition`	`bool`	Place a transition before sorted footnotes (default: `True`)
`myst_words_per_minute`	`int`	For reading speed calculations (default: `200`)

1.1. Extensions#

Configuration specific to syntax extensions:

Name	Type	Description
`myst_substitutions`	`dict[str, Any]`	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'`)
`myst_enable_checkboxes`	`bool`	tasklist: Enable checkboxes (default: `False`)

2. Frontmatter (local) configuration#

Frontmatter allows you to specify metadata and options about how a single document should behave or render. It is a YAML block at the start of the document, as used for example in jekyll. The document should start with three or more --- markers, and YAML is parsed until a closing --- marker is found:

---
key1: value
key2: [value1, value2]
key3:
  subkey1: value
---

参见

Frontmatter is also used for the substitution syntax extension, and can be used to store information for blog posting (see ablog’s myst-parser support).

The following configuration variables are available to be set in the document frontmatter. 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`	`set[str]`	Enable syntax extensions (default: `set()`)
`disable_syntax`	`collections.abc.Iterable[str]`	Disable Commonmark syntax elements (default: `[]`)
`all_links_external`	`bool`	Parse all links as simple hyperlinks (default: `False`)
`links_external_new_tab`	`bool`	Open all external links in a new tab (default: `False`)
`url_schemes`	`list[str] \| dict[str, None \| str \| dict]`	URI schemes that are converted to external links (default: `{'http': None, 'https': None, 'mailto': None, 'ftp': None}`)
`ref_domains`	`collections.abc.Iterable[str] \| None`	Sphinx domain names to search in for link references (default: `None`)
`fence_as_directive`	`set[str]`	Interpret a code fence as a directive, for certain language names. This can be useful for fences like dot and mermaid, and interoperability with other Markdown renderers. (default: `set()`)
`number_code_blocks`	`collections.abc.Sequence[str]`	Add line numbers to code blocks with these languages (default: `[]`)
`title_to_header`	`bool`	Convert a `title` field in the front-matter to a H1 header (default: `False`)
`heading_anchors`	`int`	Heading level depth to assign HTML anchors (default: `0`)
`html_meta`	`dict[str, str]`	HTML meta tags (default: `{}`)
`footnote_sort`	`bool`	Move all footnotes to the end of the document, and sort by reference order (default: `True`)
`footnote_transition`	`bool`	Place a transition before sorted footnotes (default: `True`)
`words_per_minute`	`int`	For reading speed calculations (default: `200`)

2.1. Setting HTML Metadata#

The front-matter can contain the special key html_meta; a dict with data to add to the generated HTML as <meta> elements. This is equivalent to using the meta directive.

HTML metadata can also be added globally in the conf.py via the myst_html_meta variable, in which case it will be added to all MyST documents. For each document, the myst_html_meta dict will be updated by the document level front-matter html_meta, with the front-matter taking precedence.

Sphinx Configuration

language = "en"
myst_html_meta = {
    "description lang=en": "metadata description",
    "description lang=fr": "description des métadonnées",
    "keywords": "Sphinx, MyST",
    "property=og:locale":  "en_US"
}

MyST Front-Matter

---
myst:
  html_meta:
    "description lang=en": "metadata description"
    "description lang=fr": "description des métadonnées"
    "keywords": "Sphinx, MyST"
    "property=og:locale": "en_US"
---

RestructuredText

.. meta::
   :description lang=en: metadata description
   :description lang=fr: description des métadonnées
   :keywords: Sphinx, MyST
   :property=og:locale: en_US

HTML Output

<html lang="en">
  <head>
    <meta content="metadata description" lang="en" name="description" xml:lang="en" />
    <meta content="description des métadonnées" lang="fr" name="description" xml:lang="fr" />
    <meta name="keywords" content="Sphinx, MyST">
    <meta content="en_US" property="og:locale" />

2.2. Extensions#

Configuration specific to syntax extensions:

Name	Type	Description
`substitutions`	`dict[str, Any]`	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`)
`enable_checkboxes`	`bool`	tasklist: Enable checkboxes (default: `False`)

3. List of syntax extensions#

Full details in the Syntax Extensions section.

amsmath: enable direct parsing of amsmath LaTeX equations
attrs_inline: Enable inline attribute parsing, see here for details
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

4. Build Warnings#

Below lists the MyST specific warnings that may be emitted during the build process. These will be prepended to the end of the warning message (see also show_warning_types), e.g.

WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]

In general, if your build logs any warnings, you should either fix them or raise an Issue if you think the warning is erroneous.

However, in some circumstances if you wish to suppress the warning you can use the suppress_warnings configuration option, e.g.

suppress_warnings = ["myst.header"]

Or use --myst-suppress-warnings="myst.header" for the docutils CLI.

myst.deprecated: Deprecated usage.
myst.not_supported: Functionality that is not yet supported in docutils.
myst.render: The render method is not implemented.
myst.topmatter: Issue reading front-matter.
myst.duplicate_def: Duplicate Markdown reference definition.
myst.header: Non-consecutive heading levels.
myst.directive_parse: Issue parsing directive.
myst.directive_option: Issue parsing directive options.
myst.directive_comments: Directive options has # comments, which may not be supported in future versions.
myst.directive_body: Issue parsing directive body.
myst.directive_unknown: Unknown directive.
myst.role_unknown: Unknown role.
myst.xref_ambiguous: Multiple targets were found for a cross-reference.
myst.xref_missing: A target was not found for a cross-reference.
myst.inv_retrieval: Failure to retrieve or load an inventory.
myst.iref_missing: A target was not found for an inventory reference.
myst.iref_ambiguous: Multiple targets were found for an inventory reference.
myst.domains: A legacy domain found, which does not support resolve_any_xref.
myst.heading_slug: An error occurred computing a heading slug.
myst.strikethrough: Strikethrough warning, since only implemented in HTML.
myst.html: HTML could not be parsed.
myst.attribute: Invalid attribute value.
myst.substitution: Substitution could not be resolved.