1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
(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.
```python
myst_enable_extensions = ["deflist"]
```
:::{seealso}
Configuration in Docutils, in the [](docutils.md) section.
:::
```{myst-config}
:sphinx:
:scope: global
```
### Extensions
Configuration specific to syntax extensions:
```{myst-config}
: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](https://en.wikipedia.org/wiki/YAML) block at the start of the document, as used for example in [jekyll](https://jekyllrb.com/docs/front-matter/).
The document should start with three or more `---` markers, and YAML is parsed until a closing `---` marker is found:
```yaml
---
key1: value
key2: [value1, value2]
key3:
subkey1: value
---
```
:::{seealso}
Frontmatter is also used for the [substitution syntax extension](syntax/substitutions),
and can be used to store information for blog posting (see [ablog's myst-parser support](https://ablog.readthedocs.io/en/latest/manual/markdown.html)).
:::
The following configuration variables are available to be set in the document frontmatter.
These can be set in the document [front matter](syntax/frontmatter), under the `myst` key, e.g.
```yaml
---
myst:
enable_extensions: ["deflist"]
---
```
```{myst-config}
: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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta).
This is equivalent to using the [meta directive](inv:sphinx#html-meta).
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
```python
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
```yaml
---
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
```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
<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:
```{myst-config}
:sphinx:
:extensions:
:scope: local
```
## List of syntax extensions
Full details in the [](syntax/extensions) section.
amsmath
: enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations
attrs_inline
: Enable inline attribute parsing, [see here](syntax/attributes) for details
colon_fence
: Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
deflist
: Enable definition lists, [see here](syntax/definition-lists) for details
dollarmath
: Enable parsing of dollar `$` and `$$` encapsulated math
fieldlist
: Enable field lists, [see here](syntax/fieldlists) for details
html_admonition
: Convert `<div class="admonition">` elements to sphinx admonition nodes, see the [HTML admonition syntax](syntax/html-admonition) for details
html_image
: Convert HTML `<img>` elements to sphinx image nodes, [see here](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
strikethrough
: Enable strikethrough syntax, [see here](syntax/strikethrough) for details
substitution
: Substitute keys, [see here](syntax/substitutions) for details
tasklist
: Add check-boxes to the start of list items, [see here](syntax/tasklists) 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](https://github.com/executablebooks/MyST-Parser/issues/new/choose) 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.
```python
suppress_warnings = ["myst.header"]
```
Or use `--myst-suppress-warnings="myst.header"` for the [docutils CLI](myst-docutils).
```{myst-warnings}
```
|
