Skip to content

Latest commit

 

History

History
215 lines (155 loc) · 5.69 KB

configuration.md

File metadata and controls

215 lines (155 loc) · 5.69 KB
Raw

(sphinx/config-options)=

Configuration

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

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

:::{seealso} Configuration in Docutils, in the section. :::

:sphinx:
:scope: global

Extensions

Configuration specific to syntax extensions:

:sphinx:
:extensions:
:scope: global

(syntax/frontmatter)=

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

:::{seealso} 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"]
---
:sphinx:
:scope: local

(syntax/html_meta)=

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.

::::{tab-set} :::{tab-item} 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"
}

:::

:::{tab-item} 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"
---

:::

:::{tab-item} RestructuredText

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

:::

:::{tab-item} 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" />

::: ::::

Extensions

Configuration specific to syntax extensions:

:sphinx:
:extensions:
:scope: local

List of syntax extensions

Full details in the 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

(howto/warnings)= (myst-warnings)=

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 inv:sphinx#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 inv:sphinx#suppress_warnings configuration option, e.g.

suppress_warnings = ["myst.header"]

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