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

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

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
---

See also

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.

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:
  html_meta:
    "description lang=en": "metadata description"
    "description lang=fr": "description des métadonnées"
    "keywords": "Sphinx, MyST"
    "property=og:locale": "en_US"
---

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

<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.

Contents