` HTML blocks.
915 | These blocks will be converted internally to Sphinx admonition directives, and so will work correctly for all output formats.
916 | This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks.
917 |
918 | If the first element within the `div` is `
` or `
`, then this will be set as the admonition title.
919 | All internal text (and the title) will be parsed as MyST-Markdown and all classes and an optional name will be passed to the admonition:
920 |
921 | ```html
922 |
923 |
This is the **title**
924 | This is the *content*
925 |
926 | ```
927 |
928 |
929 |
This is the **title**
930 | This is the *content*
931 |
932 |
933 | During the Sphinx render, both the `class` and `name` attributes will be used by Sphinx, but any other attributes like `style` will be discarded.
934 |
935 | :::{warning}
936 | There can be no empty lines in the block, otherwise they will be read as two separate blocks.
937 | If you want to use multiple paragraphs then they can be enclosed in `
`:
938 |
939 | ```html
940 |
941 |
Paragraph 1
942 |
Paragraph 2
943 |
944 | ```
945 |
946 |
947 |
Paragraph 1
948 |
Paragraph 2
949 |
950 |
951 | :::
952 |
953 | You can also nest HTML admonitions:
954 |
955 | ```html
956 |
957 |
Some **content**
958 |
959 |
A *title*
960 |
Paragraph 1
961 |
Paragraph 2
962 |
963 |
964 | ```
965 |
966 |
967 |
Some **content**
968 |
969 |
A *title*
970 |
Paragraph 1
971 |
Paragraph 2
972 |
973 |
974 |
975 | (syntax/amsmath)=
976 |
977 | ## Direct LaTeX Math
978 |
979 | By adding `"amsmath"` to `myst_enable_extensions` (in the {{ confpy }}),
980 | you can enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations.
981 | These top-level math environments will then be directly parsed:
982 |
983 | > equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.
984 |
985 | As expected, environments ending in `*` will not be numbered, for example:
986 |
987 | ```latex
988 | \begin{gather*}
989 | a_1=b_1+c_1\\
990 | a_2=b_2+c_2-d_2+e_2
991 | \end{gather*}
992 |
993 | \begin{align}
994 | a_{11}& =b_{11}&
995 | a_{12}& =b_{12}\\
996 | a_{21}& =b_{21}&
997 | a_{22}& =b_{22}+c_{22}
998 | \end{align}
999 | ```
1000 |
1001 | \begin{gather*}
1002 | a_1=b_1+c_1\\
1003 | a_2=b_2+c_2-d_2+e_2
1004 | \end{gather*}
1005 |
1006 | \begin{align}
1007 | a_{11}& =b_{11}&
1008 | a_{12}& =b_{12}\\
1009 | a_{21}& =b_{21}&
1010 | a_{22}& =b_{22}+c_{22}
1011 | \end{align}
1012 |
1013 | :::{note}
1014 | `\labels` inside the environment are not currently identified, and so cannot be referenced.
1015 | We hope to implement this in a future update (see [executablebooks/MyST-Parser#202](https://github.com/executablebooks/MyST-Parser/issues/202))!
1016 | :::
1017 |
1018 | :::{important}
1019 | See also [how Mathjax is configured with MyST-Parser](syntax/mathjax).
1020 | :::
1021 |
1022 | This syntax will also work when nested in other block elements, like lists or quotes:
1023 |
1024 | ```md
1025 | - A list
1026 | - \begin{gather*}
1027 | a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
1028 | \end{gather*}
1029 |
1030 | > A block quote
1031 | > \begin{gather*}
1032 | a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
1033 | \end{gather*}
1034 | ```
1035 |
1036 | - A list
1037 | - \begin{gather*}
1038 | a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
1039 | \end{gather*}
1040 |
1041 | > A block quote
1042 | > \begin{gather*}
1043 | a_1=b_1+c_1\\a_2=b_2+c_2-d_2+e_2
1044 | \end{gather*}
1045 |
--------------------------------------------------------------------------------
/docs/syntax/reference.md:
--------------------------------------------------------------------------------
1 | (syntax-tokens)=
2 | # Syntax tokens
3 |
4 | This page serves as a reference for the syntax that makes of MyST Markdown.
5 |
6 | :::{seealso}
7 | For more description and explanation of MyST syntax, see the [syntax guide](syntax.md).
8 | :::
9 |
10 | ## Block (Multi-line) Tokens
11 |
12 | Block tokens span multiple lines of content. They are broken down into two sections:
13 |
14 | - {ref}`extended-block-tokens` contains *extra* tokens that are not in CommonMark.
15 | - {ref}`commonmark-block-tokens` contains CommonMark tokens that also work, for reference.
16 |
17 | :::{note}
18 | Because MyST markdown was inspired by functionality that exists in reStructuredText,
19 | we have shown equivalent rST syntax for many MyST markdown features below.
20 | :::
21 |
22 | (extended-block-tokens)=
23 | ### Extended block tokens
24 |
25 | `````{list-table}
26 | :header-rows: 1
27 | :widths: 10 20 20
28 |
29 | * - Token
30 | - Description
31 | - Example
32 | * - FrontMatter
33 | - A YAML block at the start of the document enclosed by `---`
34 | - ```yaml
35 | ---
36 | key: value
37 | ---
38 | ```
39 | * - Directives
40 | - enclosed in 3 or more backticks followed by the directive name wrapped
41 | in curly brackets `{}`. See {ref}`syntax/directives` for more details.
42 | - ````md
43 | ```{directive}
44 | :option: value
45 |
46 | content
47 | ```
48 | ````
49 | * - Math
50 | - `$$` (default) or `\[`...`\]` characters wrapping multi-line math, or even direct [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations (optional).
51 | See {ref}`syntax/math` for more information.
52 | - ```latex
53 | $$
54 | a=1
55 | $$
56 | ```
57 | * - Table
58 | - Standard markdown table style, with pipe separation.
59 | - ```md
60 | | a | b |
61 | | :--- | ---: |
62 | | c | d |
63 | ```
64 | * - LineComment
65 | - A commented line. See {ref}`syntax/comments` for more information.
66 | - ```latex
67 | % this is a comment
68 | ```
69 | * - BlockBreak
70 | - Define blocks of text. See {ref}`syntax/blockbreaks` for more information.
71 | - ```md
72 | +++ {"meta": "data"}
73 | ```
74 | * - Footnote
75 | - A definition for a referencing footnote, that is placed at the bottom of the document.
76 | See {ref}`syntax/footnotes` for more details.
77 | - ```md
78 | [^ref]: Some footnote text
79 | ```
80 | * - Admonitions (optional)
81 | - An alternative approach for admonition style directives only, which has the benefit of allowing the content to be rendered in standard markdown editors.
82 | See [admonition directives](syntax/admonitions) for more details.
83 | - ````md
84 | :::{note}
85 | *content*
86 | :::
87 | ````
88 | `````
89 |
90 | (commonmark-block-tokens)=
91 | ### CommonMark tokens
92 |
93 | `````{list-table}
94 | :header-rows: 1
95 | :widths: 10 20 20
96 |
97 | * - Token
98 | - Description
99 | - Example
100 | * - HTMLBlock
101 | - Any valid HTML (rendered in HTML output only)
102 | - ```html
103 |
some text
104 | ```
105 | * - BlockCode
106 | - indented text (4 spaces or a tab)
107 | - ```md
108 | included as literal *text*
109 | ```
110 | * - Heading
111 | - Level 1-6 headings, denoted by number of `#`
112 | - ```md
113 | ### Heading level 3
114 | ```
115 | * - SetextHeading
116 | - Underlined header (using multiple `=` or `-`)
117 | - ```md
118 | Header
119 | ======
120 | ```
121 | * - Quote
122 | - Quoted text
123 | - ```md
124 | > this is a quote
125 | ```
126 | * - CodeFence
127 | - Enclosed in 3 or more `` ` `` or `~` with an optional language name.
128 | See {ref}`syntax/code-blocks` for more information.
129 | - ````md
130 | ```python
131 | print('this is python')
132 | ```
133 | ````
134 | * - ThematicBreak
135 | - Creates a horizontal line in the output
136 | - ```md
137 | ---
138 | ```
139 | * - List
140 | - bullet points or enumerated.
141 | - ```md
142 | - item
143 | - nested item
144 | 1. numbered item
145 | ```
146 | * - LinkDefinition
147 | - A substitution for an inline link, which can have a reference target (no spaces), and an optional title (in `"`)
148 | - ```md
149 | [key]: https://www.google.com "a title"
150 | ```
151 | * - Paragraph
152 | - General inline text
153 | - ```md
154 | any *text*
155 | ```
156 | `````
157 |
158 | ## Span (Inline) Tokens
159 |
160 | Span (or inline) tokens are defined on a single line of content. They are broken down into two
161 | sections below:
162 |
163 | - {ref}`extended-span-tokens` contains *extra* tokens that are not in CommonMark.
164 | - {ref}`commonmark-span-tokens` contains CommonMark tokens that also work, for reference.
165 |
166 | (extended-span-tokens)=
167 | ### Extended inline tokens
168 |
169 | `````{list-table}
170 | :header-rows: 1
171 | :widths: 10 20 20
172 |
173 | * - Token
174 | - Description
175 | - Example
176 | * - Role
177 | - See {ref}`syntax/roles` for more information.
178 | - ```md
179 | {rolename}`interpreted text`
180 | ```
181 | * - Target
182 | - Precedes element to target, e.g. header. See
183 | {ref}`syntax/targets` for more information.
184 | - ```md
185 | (target)=
186 | ```
187 | * - Math
188 | - `$` (default) or `\(`...`\)` enclosed math. See
189 | {ref}`syntax/math` for more information.
190 | - ```latex
191 | $a=1$ or $$a=1$$
192 | ```
193 | * - FootReference
194 | - Reference a footnote. See {ref}`syntax/footnotes` for more details.
195 | - ```md
196 | [^abc]
197 | ```
198 | `````
199 |
200 | (commonmark-span-tokens)=
201 | ### CommonMark inline tokens
202 |
203 | `````{list-table}
204 | :header-rows: 1
205 | :widths: 10 20 20
206 |
207 | * - Token
208 | - Description
209 | - Example
210 | * - HTMLSpan
211 | - Any valid HTML (rendered in HTML output only)
212 | - ```html
213 |
some text
214 | ```
215 | * - EscapeSequence
216 | - Escaped symbols (to avoid them being interpreted as other syntax elements)
217 | - ```md
218 | \*
219 | ```
220 | * - AutoLink
221 | - Link that is shown in final output
222 | - ```md
223 |
224 | ```
225 | * - InlineCode
226 | - Literal text
227 | - ```md
228 | `a=1`
229 | ```
230 | * - LineBreak
231 | - Soft or hard (ends with spaces or backslash)
232 | - ```md
233 | A hard break\
234 | ```
235 | * - Image
236 | - Link to an image.
237 | You can also use HTML syntax, to include image size etc, [see here](syntax/images) for details
238 | - ```md
239 | 
240 | ```
241 | * - Link
242 | - Reference `LinkDefinitions`. See {ref}`syntax/referencing` for more details.
243 | - ```md
244 | [text](target "title") or [text][key]
245 | ```
246 | * - Strong
247 | - Bold text
248 | - ```md
249 | **strong**
250 | ```
251 | * - Emphasis
252 | - Italic text
253 | - ```md
254 | *emphasis*
255 | ```
256 | * - RawText
257 | - Any text
258 | - ```md
259 | any text
260 | ```
261 | `````
262 |
--------------------------------------------------------------------------------
/docs/syntax/roles-and-directives.md:
--------------------------------------------------------------------------------
1 | (roles-directives)=
2 |
3 | # Roles and Directives
4 |
5 | Roles and directives provide a way to extend the syntax of MyST in an unbound manner,
6 | by interpreting a chuck of text as a specific type of markup, according to its name.
7 |
8 | Mostly all
9 | [docutils roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html),
10 | [docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html),
11 | [Sphinx roles](inv:sphinx#usage/*/roles), or
12 | [Sphinx directives](inv:sphinx#usage/*/directives)
13 | can be used in MyST.
14 |
15 | ## Syntax
16 |
17 | (syntax/directives)=
18 |
19 | ### Directives - a block-level extension point
20 |
21 | Directives syntax is defined with triple-backticks and curly-brackets.
22 | It is effectively a Markdown code fence with curly brackets around the language, and a directive name in place of a language name.
23 | Here is the basic structure:
24 |
25 | `````{list-table}
26 | ---
27 | header-rows: 1
28 | ---
29 | * - MyST
30 | - reStructuredText
31 | * - ````md
32 | ```{directivename} arguments
33 | ---
34 | key1: val1
35 | key2: val2
36 | ---
37 | This is
38 | directive content
39 | ```
40 | ````
41 | - ```rst
42 | .. directivename:: arguments
43 | :key1: val1
44 | :key2: val2
45 |
46 | This is
47 | directive content
48 | ```
49 | `````
50 |
51 | For example, the following code:
52 |
53 | ````md
54 | ```{admonition} This is my admonition
55 | This is my note
56 | ```
57 | ````
58 |
59 | Will generate this admonition:
60 |
61 | ```{admonition} This is my admonition
62 | This is my note
63 | ```
64 |
65 | #### Parameterizing directives
66 |
67 | For directives that take parameters as input, there are two ways to parameterize them.
68 | In each case, the options themselves are given as `key: value` pairs. An example of
69 | each is shown below:
70 |
71 | **Using YAML frontmatter**. A block of YAML front-matter just after the
72 | first line of the directive will be parsed as options for the directive. This needs to be
73 | surrounded by `---` lines. Everything in between will be parsed by YAML and
74 | passed as keyword arguments to your directive. For example:
75 |
76 | ````md
77 | ```{code-block} python
78 | ---
79 | lineno-start: 10
80 | emphasize-lines: 1, 3
81 | caption: |
82 | This is my
83 | multi-line caption. It is *pretty nifty* ;-)
84 | ---
85 | a = 2
86 | print('my 1st line')
87 | print(f'my {a}nd line')
88 | ```
89 | ````
90 |
91 | ```{code-block} python
92 | ---
93 | lineno-start: 10
94 | emphasize-lines: 1, 3
95 | caption: |
96 | This is my
97 | multi-line caption. It is *pretty nifty* ;-)
98 | ---
99 | a = 2
100 | print('my 1st line')
101 | print(f'my {a}nd line')
102 | ```
103 |
104 | **Short-hand options with `:` characters**. If you only need one or two options for your
105 | directive and wish to save lines, you may also specify directive options as a collection
106 | of lines just after the first line of the directive, each preceding with `:`. Then the
107 | leading `:` is removed from each line, and the rest is parsed as YAML.
108 |
109 | For example:
110 |
111 | ````md
112 | ```{code-block} python
113 | :lineno-start: 10
114 | :emphasize-lines: 1, 3
115 |
116 | a = 2
117 | print('my 1st line')
118 | print(f'my {a}nd line')
119 | ```
120 | ````
121 |
122 | (syntax/directives/parsing)=
123 |
124 | #### How directives parse content
125 |
126 | Some directives parse the content that is in their content block.
127 | MyST parses this content **as Markdown**.
128 |
129 | This means that MyST markdown can be written in the content areas of any directives written in MyST markdown. For example:
130 |
131 | ````md
132 | ```{admonition} My markdown link
133 | Here is [markdown link syntax](https://jupyter.org)
134 | ```
135 | ````
136 |
137 | ```{admonition} My markdown link
138 | Here is [markdown link syntax](https://jupyter.org)
139 | ```
140 |
141 | As a short-hand for directives that require no arguments, and when no parameter options are used (see below),
142 | you may start the content directly after the directive name.
143 |
144 | ````md
145 | ```{note} Notes require **no** arguments, so content can start here.
146 | ```
147 | ````
148 |
149 | ```{note} Notes require **no** arguments, so content can start here.
150 | ```
151 |
152 | For special cases, MySt also offers the `eval-rst` directive.
153 | This will parse the content **as ReStructuredText**:
154 |
155 | ````md
156 | ```{eval-rst}
157 | .. figure:: img/fun-fish.png
158 | :width: 100px
159 | :name: rst-fun-fish
160 |
161 | Party time!
162 |
163 | A reference from inside: :ref:`rst-fun-fish`
164 |
165 | A reference from outside: :ref:`syntax/directives/parsing`
166 | ```
167 | ````
168 |
169 | ```{eval-rst}
170 | .. figure:: img/fun-fish.png
171 | :width: 100px
172 | :name: rst-fun-fish
173 |
174 | Party time!
175 |
176 | A reference from inside: :ref:`rst-fun-fish`
177 |
178 | A reference from outside: :ref:`syntax/directives/parsing`
179 | ```
180 |
181 | Note how the text is integrated into the rest of the document, so we can also reference [party fish](rst-fun-fish) anywhere else in the documentation.
182 |
183 | #### Nesting directives
184 |
185 | You can nest directives by ensuring that the tick-lines corresponding to the
186 | outermost directive are longer than the tick-lines for the inner directives.
187 | For example, nest a warning inside a note block like so:
188 |
189 | `````md
190 | ````{note}
191 | The next info should be nested
192 | ```{warning}
193 | Here's my warning
194 | ```
195 | ````
196 | `````
197 |
198 | Here's how it looks rendered:
199 |
200 | ````{note}
201 | The next info should be nested
202 | ```{warning}
203 | Here's my warning
204 | ```
205 | ````
206 |
207 | You can indent inner-code fences, so long as they aren't indented by more than 3 spaces.
208 | Otherwise, they will be rendered as "raw code" blocks:
209 |
210 | `````md
211 | ````{note}
212 | The warning block will be properly-parsed
213 |
214 | ```{warning}
215 | Here's my warning
216 | ```
217 |
218 | But the next block will be parsed as raw text
219 |
220 | ```{warning}
221 | Here's my raw text warning that isn't parsed...
222 | ```
223 | ````
224 | `````
225 |
226 | ````{note}
227 | The warning block will be properly-parsed
228 |
229 | ```{warning}
230 | Here's my warning
231 | ```
232 |
233 | But the next block will be parsed as raw text
234 |
235 | ```{warning}
236 | Here's my raw text warning that isn't parsed...
237 | ```
238 | ````
239 |
240 | This can really be abused if you'd like ;-)
241 |
242 | ``````{note}
243 | The next info should be nested
244 | `````{warning}
245 | Here's my warning
246 | ````{admonition} Yep another admonition
247 | ```python
248 | # All this fuss was about this boring python?!
249 | print('yep!')
250 | ```
251 | ````
252 | `````
253 | ``````
254 |
255 | #### Markdown-friendly directives
256 |
257 | Want to use syntax that renders correctly in standard Markdown editors?
258 | See [the extended syntax option](syntax/colon_fence).
259 |
260 | ```md
261 | :::{note}
262 | This text is **standard** *Markdown*
263 | :::
264 | ```
265 |
266 | :::{note}
267 | This text is **standard** *Markdown*
268 | :::
269 |
270 | (syntax/roles)=
271 |
272 | ### Roles - an in-line extension point
273 |
274 | Roles are similar to directives - they allow you to define arbitrary new functionality, but they are used *in-line*.
275 | To define an in-line role, use the following form:
276 |
277 | ````{list-table}
278 | ---
279 | header-rows: 1
280 | ---
281 | * - MyST
282 | - reStructuredText
283 | * - ````md
284 | {role-name}`role content`
285 | ````
286 | - ```rst
287 | :role-name:`role content`
288 | ```
289 | ````
290 |
291 | For example, the following code:
292 |
293 | ```md
294 | Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`
295 | ```
296 |
297 | Becomes:
298 |
299 | Since Pythagoras, we know that {math}`a^2 + b^2 = c^2`
300 |
301 | You can use roles to do things like reference equations and other items in
302 | your book. For example:
303 |
304 | ````md
305 | ```{math} e^{i\pi} + 1 = 0
306 | ---
307 | label: euler
308 | ---
309 | ```
310 |
311 | Euler's identity, equation {math:numref}`euler`, was elected one of the
312 | most beautiful mathematical formulas.
313 | ````
314 |
315 | Becomes:
316 |
317 | ```{math} e^{i\pi} + 1 = 0
318 | ---
319 | label: euler
320 | ---
321 | ```
322 |
323 | Euler's identity, equation {math:numref}`euler`, was elected one of the
324 | most beautiful mathematical formulas.
325 |
326 | #### How roles parse content
327 |
328 | The content of roles is parsed differently depending on the role that you've used.
329 | Some roles expect inputs that will be used to change functionality. For example,
330 | the `ref` role will assume that input content is a reference to some other part of the
331 | site. However, other roles may use the MyST parser to parse the input as content.
332 |
333 | Some roles also **extend their functionality** depending on the content that you pass.
334 | For example, following the `ref` example above, if you pass a string like this:
335 | `Content to display `, then the `ref` will display `Content to display` and use
336 | `myref` as the reference to look up.
337 |
338 | How roles parse this content depends on the author that created the role.
339 |
340 | ## Common roles and directives
341 |
342 | :::{admonition} {material-regular}`engineering;1.5rem;sd-mr-1` Currently Under Construction
343 | :class: no-icon
344 | Check back for more...
345 | :::
346 |
347 | ### ToC Trees
348 |
349 | ```{doc-directive} contents
350 | Insert a table of contents tree of the documents headings.
351 | ```
352 |
353 | ```{doc-directive} toctree
354 | Inserts a Sphinx "Table of Contents" tree, containing a list of (relative) child document paths.
355 | ```
356 |
357 | ### Admonitions
358 |
359 | ```{doc-directive} admonition
360 | Create a generic "callout" box, containing the content.
361 | ```
362 |
363 | ```{doc-directive} note
364 | Create a "callout" box, specific to notes, containing the content.
365 | ```
366 |
367 | Other admonitions (same structure as `note`): `attention`, `caution`, `danger`, `error`, `hint`, `important`, `tip`, `warning`.
368 |
369 | Sphinx only: `deprecated`, `versionadded`, `versionchanged`.
370 |
371 | ### Images and Figures
372 |
373 | ```{doc-directive} image
374 | Insert an image, from a (relative) path or URL.
375 | ```
376 |
377 | ```{doc-directive} figure
378 | Insert an image, from a (relative) path or URL,
379 | with a caption (first paragraph), and optional legend (subsequent content).
380 | ```
381 |
382 | ```{doc-directive} table
383 | Insert a (MyST) table with a caption.
384 | ```
385 |
386 | ### Tables
387 |
388 | ```{doc-directive} list-table
389 | Create a table from data in a uniform two-level bullet list.
390 | ```
391 |
392 | ```{doc-directive} csv-table
393 | Create a table from CSV (comma-separated values) data.
394 | ```
395 |
396 | ### Code
397 |
398 | ```{doc-directive} code-block
399 | Syntax highlight a block of code, according to the language.
400 | ```
401 |
402 | (syntax/roles/special)=
403 |
404 | ### MyST only
405 |
406 | This section contains information about special roles and directives that come bundled with the MyST Parser Sphinx extension.
407 |
408 | #### Insert the date and reading time
409 |
410 | ```{versionadded} 0.14.0
411 | The `sub-ref` role and word counting.
412 | ```
413 |
414 | You may insert the "last updated" date and estimated reading time into your document via substitution definitions, which can be accessed *via* the `sub-ref` role.
415 |
416 | For example:
417 |
418 | ```markdown
419 | > {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
420 | ```
421 |
422 | > {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
423 |
424 | `today` is replaced by either the date on which the document is parsed, with the format set by , or the `today` variable if set in the configuration file.
425 |
426 | The reading speed is computed using the `myst_words_per_minute` configuration (see the [Sphinx configuration options](sphinx/config-options)).
427 |
--------------------------------------------------------------------------------
/docs/syntax/syntax.md:
--------------------------------------------------------------------------------
1 | (syntax/core)=
2 |
3 | # Core Syntax
4 |
5 | ## Introduction
6 |
7 | MyST is a strict superset of the [CommonMark syntax specification](https://spec.commonmark.org/).
8 | It adds features focussed on scientific and technical documentation authoring, as detailed below.
9 |
10 | In addition, the roles and directives syntax provide inline/block-level extension points for plugins.
11 | This is detailed further in the [Roles and Directives](roles-directives) section.
12 |
13 | :::{seealso}
14 | The [syntax token reference tables](syntax-tokens)
15 | :::
16 |
17 | (syntax/commonmark)=
18 |
19 | ## CommonMark
20 |
21 | The [CommonMark syntax specification](https://spec.commonmark.org/) details the full set of syntax rules.
22 | Here we provide a summary of most features:
23 |
24 | Element | Syntax
25 | --------------- | -------------------------------------------
26 | Heading | `# H1` to `###### H6`
27 | Bold | `**bold**`
28 | Italic | `*italic*`
29 | Inline Code | `` `code` ``
30 | Autolink | ``
31 | URL Link | `[title](https://www.example.com)`
32 | Image | ``
33 | Reference Link | `[title][link]`
34 | Link Definition | `[link]: https://www.example.com`
35 | Thematic break | `---`
36 | Blockquote | `> quote`
37 | Ordered List | `1. item`
38 | Unordered List | `- item`
39 | Code Fence | opening ```` ```lang ```` to closing ```` ``` ````
40 |
41 | (syntax/frontmatter)=
42 |
43 | ## Front Matter
44 |
45 | This 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/).
46 | The document should start with three or more `---` markers, and YAML is parsed until a closing `---` marker is found:
47 |
48 | ```yaml
49 | ---
50 | key1: value
51 | key2: [value1, value2]
52 | key3:
53 | subkey1: value
54 | ---
55 | ```
56 |
57 | :::{seealso}
58 | Top-matter is also used for the [substitution syntax extension](syntax/substitutions),
59 | and can be used to store information for blog posting (see [ablog's myst-parser support](https://ablog.readthedocs.io/en/latest/manual/markdown/)).
60 | :::
61 |
62 | ### Setting a title
63 |
64 | ```{versionadded} 0.17.0
65 | ```
66 |
67 | If `myst_title_to_header` is set to `True`, and a `title` key is present in the front matter,
68 | then the title will be used as the document's header (parsed as Markdown).
69 | For example:
70 |
71 | ```md
72 | ---
73 | title: My Title with *emphasis*
74 | ---
75 | ```
76 |
77 | would be equivalent to:
78 |
79 | ```md
80 | # My Title with *emphasis*
81 | ```
82 |
83 | (syntax/html_meta)=
84 |
85 | ### Setting HTML Metadata
86 |
87 | The front-matter can contain the special key `html_meta`; a dict with data to add to the generated HTML as [`` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta).
88 | This is equivalent to using the [meta directive](inv:sphinx#html-meta).
89 |
90 | 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.
91 | 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.
92 |
93 | ::::{tab-set}
94 | :::{tab-item} Sphinx Configuration
95 |
96 | ```python
97 | language = "en"
98 | myst_html_meta = {
99 | "description lang=en": "metadata description",
100 | "description lang=fr": "description des métadonnées",
101 | "keywords": "Sphinx, MyST",
102 | "property=og:locale": "en_US"
103 | }
104 | ```
105 |
106 | :::
107 |
108 | :::{tab-item} MyST Front-Matter
109 |
110 | ```yaml
111 | ---
112 | myst:
113 | html_meta:
114 | "description lang=en": "metadata description"
115 | "description lang=fr": "description des métadonnées"
116 | "keywords": "Sphinx, MyST"
117 | "property=og:locale": "en_US"
118 | ---
119 | ```
120 |
121 | :::
122 |
123 | :::{tab-item} RestructuredText
124 |
125 | ```restructuredtext
126 | .. meta::
127 | :description lang=en: metadata description
128 | :description lang=fr: description des métadonnées
129 | :keywords: Sphinx, MyST
130 | :property=og:locale: en_US
131 | ```
132 |
133 | :::
134 |
135 | :::{tab-item} HTML Output
136 |
137 | ```html
138 |
139 |
140 |
141 |
142 |
143 |
144 | ```
145 |
146 | :::
147 | ::::
148 |
149 | (syntax/comments)=
150 |
151 | ## Comments
152 |
153 | You may add comments by putting the `%` character at the beginning of a line. This will
154 | prevent the line from being parsed into the output document.
155 |
156 | For example, this code:
157 |
158 | ```md
159 | % my comment
160 | ```
161 |
162 | Is below, but it won't be parsed into the document.
163 |
164 | % my comment
165 |
166 | ````{important}
167 | Since comments are a block-level entity, they will terminate the previous block.
168 | In practical terms, this means that the following lines
169 | will be broken up into two paragraphs, resulting in a new line between them:
170 |
171 | ```
172 | a line
173 | % a comment
174 | another line
175 | ```
176 |
177 | a line
178 | % a comment
179 | another line
180 | ````
181 |
182 | :::{tip}
183 | Comments are equivalent to the RST syntax: `.. my comment`.
184 | :::
185 |
186 | (syntax/blockbreaks)=
187 |
188 | ## Block Breaks
189 |
190 | You may add a block break by putting `+++` at the beginning of a line.
191 | This constuct's intended use case is for mapping to cell based document formats,
192 | like [jupyter notebooks](https://jupyter.org/),
193 | to indicate a new text cell. It will not show up in the rendered text,
194 | but is stored in the internal document structure for use by developers.
195 |
196 | For example, this code:
197 |
198 | ```md
199 | +++ some text
200 | ```
201 |
202 | Is below, but it won't be parsed into the document.
203 |
204 | +++
205 |
206 | (syntax/referencing)=
207 |
208 | ## Markdown Links and Referencing
209 |
210 | ### CommonMark link format
211 |
212 | CommonMark links come in three forms ([see the spec](https://spec.commonmark.org/0.30/#links)):
213 |
214 | *Autolinks* are [URIs][uri] surrounded by `<` and `>`, which must always have a scheme:
215 |
216 | ```md
217 |
218 | ```
219 |
220 | *Inline links* allow for optional explicit text and titles (in HTML titles are rendered as tooltips):
221 |
222 | ```md
223 | [Explicit *Markdown* text](destination "optional explicit title")
224 | ```
225 |
226 | or, if the destination contains spaces,
227 |
228 | ```md
229 | [Explicit *Markdown* text]( "optional explicit title")
230 | ```
231 |
232 | *Reference links* define the destination separately in the document, and can be used multiple times:
233 |
234 | ```md
235 | [Explicit *Markdown* text][label]
236 | [Another link][label]
237 |
238 | [label]: destination "optional explicit title"
239 | ```
240 |
241 | [uri]: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier
242 | [url]: https://en.wikipedia.org/wiki/URL
243 |
244 | ### Default destination resolution
245 |
246 | The destination of a link can resolve to either an **external** target, such as a [URL] to another website,
247 | or an **internal** target, such as a file, heading or figure within the same project.
248 |
249 | By default, MyST will resolve link destinations according to the following rules:
250 |
251 | 1. All autolinks will be treated as external [URL] links.
252 |
253 | 2. Destinations beginning with `http:`, `https:`, `ftp:`, or `mailto:` will be treated as external [URL] links.
254 |
255 | 3. Destinations which point to a local file path are treated as links to that file.
256 | - The path must be relative and in [POSIX format](https://en.wikipedia.org/wiki/Path_(computing)#POSIX_and_Unix_paths) (i.e. `/` separators).
257 | - If the path is to another source file in the project (e.g. a `.md` or `.rst` file),
258 | then the link will be to the initial heading in that file or,
259 | if the path is appended by a `#target`, to the heading "slug" in that file.
260 | - If the path is to a non-source file (e.g. a `.png` or `.pdf` file),
261 | then the link will be to the file itself, e.g. to download it.
262 |
263 | 4. Destinations beginning with `#` will be treated as a link to a heading "slug" in the same file.
264 | - This requires the `myst_heading_anchors` configuration be set.
265 | - For more details see [](syntax/header-anchors).
266 |
267 | 5. All other destinations are treated as internal references, which can link to any type of target within the project (see [](syntax/targets)).
268 |
269 | Here are some examples:
270 |
271 | :::{list-table}
272 | :header-rows: 1
273 |
274 | * - Type
275 | - Syntax
276 | - Rendered
277 |
278 | * - Autolink
279 | - ``
280 | -
281 |
282 | * - External URL
283 | - `[example.com](https://example.com)`
284 | - [example.com](https://example.com)
285 |
286 | * - Internal source file
287 | - `[Source file](syntax.md)`
288 | - [Source file](syntax.md)
289 |
290 | * - Internal non-source file
291 | - `[Non-source file](example.txt)`
292 | - [Non-source file](example.txt)
293 |
294 | * - Local heading
295 | - `[Heading](#markdown-links-and-referencing)`
296 | - [Heading](#markdown-links-and-referencing)
297 |
298 | * - Heading in another file
299 | - `[Heading](optional.md#auto-generated-header-anchors)`
300 | - [Heading](optional.md#auto-generated-header-anchors)
301 |
302 | :::
303 |
304 | ### Customising destination resolution
305 |
306 | You can customise the default destination resolution rules by setting the following [configuration options](../configuration.md):
307 |
308 | `myst_all_links_external` (default: `False`)
309 | : If `True`, then all links will be treated as external links.
310 |
311 | `myst_url_schemes` (default: `["http", "https", "ftp", "mailto"]`)
312 | : A list of [URL] schemes which will be treated as external links.
313 |
314 | `myst_ref_domains` (default: `[]`)
315 | : A list of [sphinx domains](inv:sphinx#domain) which will be allowed for internal links.
316 | For example, `myst_ref_domains = ("std", "py")` will only allow cross-references to `std` and `py` domains.
317 | If the list is empty, then all domains will be allowed.
318 |
319 | (syntax/inv_links)=
320 | ### Cross-project (inventory) links
321 |
322 | :::{versionadded} 0.19
323 | This functionality is currently in *beta*.
324 | It is intended that eventually it will be part of the core syntax.
325 | :::
326 |
327 | Each Sphinx HTML build creates a file named `objects.inv` that contains a mapping from referenceable objects to [URIs][uri] relative to the HTML set’s root.
328 | Each object is uniquely identified by a `domain`, `type`, and `name`.
329 | As well as the relative location, the object can also include implicit `text` for the reference (like the text for a heading).
330 |
331 | You can use the `myst-inv` command line tool (installed with `myst_parser`) to visualise and filter any remote URL or local file path to this inventory file (or its parent):
332 |
333 | ```yaml
334 | # $ myst-inv https://www.sphinx-doc.org/en/master -n index
335 | name: Sphinx
336 | version: 6.2.0
337 | base_url: https://www.sphinx-doc.org/en/master
338 | objects:
339 | rst:
340 | role:
341 | index:
342 | loc: usage/restructuredtext/directives.html#role-index
343 | text: null
344 | std:
345 | doc:
346 | index:
347 | loc: index.html
348 | text: Welcome
349 | ```
350 |
351 | To load external inventories into your Sphinx project, you must load the [`sphinx.ext.intersphinx` extension](inv:sphinx#usage/*/intersphinx), and set the `intersphinx_mapping` configuration option.
352 | Then also enable the `inv_link` MyST extension e.g.:
353 |
354 | ```python
355 | extensions = ["myst_parser", "sphinx.ext.intersphinx"]
356 | intersphinx_mapping = {
357 | "sphinx": ("https://www.sphinx-doc.org/en/master", None),
358 | }
359 | myst_enable_extensions = ["inv_link"]
360 | ```
361 |
362 | :::{dropdown} Docutils configuration
363 |
364 | Use the `docutils.conf` configuration file, for more details see [](myst-docutils).
365 |
366 | ```ini
367 | [general]
368 | myst-inventories:
369 | sphinx: ["https://www.sphinx-doc.org/en/master", null]
370 | myst-enable-extensions: inv_link
371 | ```
372 |
373 | :::
374 |
375 | you can then reference inventory objects by prefixing the `inv` schema to the destination [URI]: `inv:key:domain:type#name`.
376 |
377 | `key`, `domain` and `type` are optional, e.g. for `inv:#name`, all inventories, domains and types will be searched, with a [warning emitted](myst-warnings) if multiple matches are found.
378 |
379 | Additionally, `*` is a wildcard which matches zero or characters, e.g. `inv:*:std:doc#a*` will match all `std:doc` objects in all inventories, with a `name` beginning with `a`.
380 | Note, to match to a literal `*` use `\*`.
381 |
382 | Here are some examples:
383 |
384 | :::{list-table}
385 | :header-rows: 1
386 |
387 | * - Type
388 | - Syntax
389 | - Rendered
390 |
391 | * - Autolink, full
392 | - ``
393 | -
394 |
395 | * - Link, full
396 | - `[Sphinx](inv:sphinx:std:doc#index)`
397 | - [Sphinx](inv:sphinx:std:doc#index)
398 |
399 | * - Autolink, no type
400 | - ``
401 | -
402 |
403 | * - Autolink, no domain
404 | - ``
405 | -
406 |
407 | * - Autolink, only name
408 | - ``
409 | -
410 |
411 | :::
412 |
413 | (syntax/targets)=
414 |
415 | ## Targets and Cross-Referencing
416 |
417 | Targets are used to define custom anchors that you can refer to elsewhere in your
418 | documentation. They generally go before section titles so that you can easily refer
419 | to them.
420 |
421 | :::{tip}
422 |
423 | If you'd like to *automatically* generate targets for each of your section headers,
424 | check out the [](syntax/header-anchors) section of extended syntaxes.
425 |
426 | :::
427 |
428 | Target headers are defined with this syntax:
429 |
430 | ```md
431 | (header_target)=
432 | ```
433 |
434 | They can then be referred to with the
435 | [`ref` inline role](inv:sphinx#ref-role):
436 |
437 | ```md
438 | {ref}`header_target`
439 | ```
440 |
441 | By default, the reference will use the text of the target (such as the section title), but also you can directly specify the text:
442 |
443 | ```md
444 | {ref}`my text `
445 | ```
446 |
447 | For example, see this ref: {ref}`syntax/targets`, and here's a ref back to the top of this page: {ref}`my text `.
448 |
449 | Alternatively using the markdown syntax:
450 |
451 | ```md
452 | [my text](header_target)
453 | ```
454 |
455 | is equivalent to using the [`any` inline role](inv:sphinx#any-role):
456 |
457 | ```md
458 | {any}`my text `
459 | ```
460 |
461 | but can also accept "nested" syntax (like bold text) and will recognise document paths that include extensions (e.g. `syntax/syntax` or `syntax/syntax.md`)
462 |
463 | Using the same example, see this ref: [](syntax/targets), here is a reference back to the top of
464 | this page: [my text with **nested** $\alpha$ syntax](syntax/core), and here is a reference to another page (`[](../intro.md)`): [](../intro.md).
465 |
466 | ```{note}
467 | If you wish to have the target's title inserted into your text, you can
468 | leave the "text" section of the markdown link empty. For example, this
469 | markdown: `[](syntax.md)` will result in: [](syntax.md).
470 | ```
471 |
472 | (syntax/code-blocks)=
473 | ## Code syntax highlighting
474 |
475 | Code blocks contain a language identifier, which is used to determine the language of the code.
476 | This language is used to determine the syntax highlighting, using an available [pygments lexer](https://pygments.org/docs/lexers/).
477 |
478 | ````markdown
479 | ```python
480 | from a import b
481 | c = "string"
482 | ```
483 | ````
484 |
485 | ```python
486 | from a import b
487 | c = "string"
488 | ```
489 |
490 | You can create and register your own lexer, using the [`pygments.lexers` entry point](https://pygments.org/docs/plugins/#register-plugins),
491 | or within a sphinx extension, with the [`app.add_lexer` method](inv:sphinx#*.Sphinx.add_lexer).
492 |
493 | Using the `myst_number_code_blocks` configuration option, you can also control whether code blocks are numbered by line.
494 | For example, using `myst_number_code_blocks = ["typescript"]`:
495 |
496 | ```typescript
497 | type MyBool = true | false;
498 |
499 | interface User {
500 | name: string;
501 | id: number;
502 | }
503 | ```
504 |
505 | ### Show backticks inside raw markdown blocks
506 |
507 | If you'd like to show backticks inside of your markdown, you can do so by nesting them
508 | in backticks of a greater length. Markdown will treat the outer-most backticks as the
509 | edges of the "raw" block and everything inside will show up. For example:
510 |
511 | ``` `` `hi` `` ``` will be rendered as: `` `hi` ``
512 |
513 | and
514 |
515 | `````
516 | ````
517 | ```
518 | hi
519 | ```
520 | ````
521 | `````
522 |
523 | will be rendered as:
524 |
525 | ````
526 | ```
527 | hi
528 | ```
529 | ````
530 |
531 | ## Tables
532 |
533 | Tables can be written using the standard [Github Flavoured Markdown syntax](https://github.github.com/gfm/#tables-extension-):
534 |
535 | ```md
536 | | foo | bar |
537 | | --- | --- |
538 | | baz | bim |
539 | ```
540 |
541 | | foo | bar |
542 | | --- | --- |
543 | | baz | bim |
544 |
545 | Cells in a column can be aligned using the `:` character:
546 |
547 | ```md
548 | | left | center | right |
549 | | :--- | :----: | ----: |
550 | | a | b | c |
551 | ```
552 |
553 | | left | center | right |
554 | | :--- | :----: | ----: |
555 | | a | b | c |
556 |
557 | :::{note}
558 |
559 | Text is aligned by assigning `text-left`, `text-center`, or `text-right` to the cell.
560 | It is then necessary for the theme you are using to include the appropriate css styling.
561 |
562 | ```html
563 |
564 |
565 | left |
|---|
566 |
567 |
568 | a |
569 |
570 |
571 | ```
572 |
573 | :::
574 |
575 | ## Images
576 |
577 | MyST provides a few different syntaxes for including images in your documentation.
578 |
579 | The standard Markdown syntax is:
580 |
581 | ```md
582 | 
583 | ```
584 |
585 | 
586 |
587 | But you can also enable extended image syntaxes, to control attributes like width and captions.
588 | See the [extended image syntax guide](syntax/images).
589 |
590 | (syntax/footnotes)=
591 | ## Footnotes
592 |
593 | Footnotes use the [pandoc specification](https://pandoc.org/MANUAL.html#footnotes).
594 | Their labels **start with `^`** and can then be any alphanumeric string (no spaces), which is case-insensitive.
595 |
596 | - If the label is an integer, then it will always use that integer for the rendered label (i.e. they are manually numbered).
597 | - For any other labels, they will be auto-numbered in the order which they are referenced, skipping any manually numbered labels.
598 |
599 | All footnote definitions are collected, and displayed at the bottom of the page (in the order they are referenced).
600 | Note that un-referenced footnote definitions will not be displayed.
601 |
602 | ```md
603 | - This is a manually-numbered footnote reference.[^3]
604 | - This is an auto-numbered footnote reference.[^myref]
605 |
606 | [^myref]: This is an auto-numbered footnote definition.
607 | [^3]: This is a manually-numbered footnote definition.
608 | ```
609 |
610 | - This is a manually-numbered footnote reference.[^3]
611 | - This is an auto-numbered footnote reference.[^myref]
612 |
613 | [^myref]: This is an auto-numbered footnote definition.
614 | [^3]: This is a manually-numbered footnote definition.
615 |
616 | Any preceding text after a footnote definitions, which is
617 | indented by four or more spaces, will also be included in the footnote definition, and the text is rendered as MyST Markdown, e.g.
618 |
619 | ```md
620 | A longer footnote definition.[^mylongdef]
621 |
622 | [^mylongdef]: This is the _**footnote definition**_.
623 |
624 | That continues for all indented lines
625 |
626 | - even other block elements
627 |
628 | Plus any preceding unindented lines,
629 | that are not separated by a blank line
630 |
631 | This is not part of the footnote.
632 | ```
633 |
634 | A longer footnote definition.[^mylongdef]
635 |
636 | [^mylongdef]: This is the _**footnote definition**_.
637 |
638 | That continues for all indented lines
639 |
640 | - even other block elements
641 |
642 | Plus any subsequent unindented lines,
643 | that are not separated by a blank line
644 |
645 | This is not part of the footnote.
646 |
647 | ````{important}
648 | Although footnote references can be used just fine within directives, e.g.[^myref],
649 | it is recommended that footnote definitions are not set within directives,
650 | unless they will only be referenced within that same directive:
651 |
652 | ```md
653 | [^other]
654 |
655 | [^other]: A definition within a directive
656 | ```
657 |
658 | [^other]
659 |
660 | [^other]: A definition within a directive
661 |
662 | This is because, in the current implementation, they may not be available to reference in text above that particular directive.
663 | ````
664 |
665 | By default, a transition line (with a `footnotes` class) will be placed before any footnotes.
666 | This can be turned off by adding `myst_footnote_transition = False` to the config file.
667 |
--------------------------------------------------------------------------------
/lumache.py:
--------------------------------------------------------------------------------
1 | """
2 | Lumache - Python library for cooks and food lovers.
3 | """
4 |
5 | __version__ = "0.1.0"
6 |
7 |
8 | class InvalidKindError(Exception):
9 | """Raised if the kind is invalid."""
10 | pass
11 |
12 |
13 | def get_random_ingredients(kind=None):
14 | """
15 | Return a list of random ingredients as strings.
16 |
17 | :param kind: Optional "kind" of ingredients.
18 | :type kind: list[str] or None
19 | :raise lumache.InvalidKindError: If the kind is invalid.
20 | :return: The ingredients list.
21 | :rtype: list[str]
22 | """
23 | return ["shells", "gorgonzola", "parsley"]
24 |
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
1 | [build-system]
2 | requires = ["flit_core >=3.2,<4","myst-parser >=0.18.1"]
3 | build-backend = "flit_core.buildapi"
4 |
5 | [project]
6 | name = "EasyPoi "
7 | authors = [{name = "夜雨微寒", email = "951683309@qq.com"}]
8 | dynamic = ["version", "description"]
9 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | myst-parser
2 | sphinx_design
3 | sphinx_pyscript
4 |
--------------------------------------------------------------------------------
.png)
10 | key3: |
11 | ```{image} img/fun-fish.png
12 | :alt: fishy
13 | :width: 200px
14 | ```
15 | key4: example
16 | confpy: sphinx `conf.py` [configuration file](inv:sphinx#usage/configuration)
17 | ---
18 |
19 | (syntax/extensions)=
20 |
21 | # Syntax Extensions
22 |
23 | MyST-Parser is highly configurable, utilising the inherent "plugability" of the [markdown-it-py](inv:markdown_it#index) parser.
24 | The following syntaxes are optional (disabled by default) and can be enabled *via* the {{ confpy }} (see also [](sphinx/config-options)).
25 | Their goal is generally to add more *Markdown friendly* syntaxes; often enabling and rendering [markdown-it-py plugins](inv:markdown_it#md/plugins) that extend the [CommonMark specification](https://commonmark.org/).
26 |
27 | To enable all the syntaxes explained below:
28 |
29 | ```python
30 | myst_enable_extensions = [
31 | "amsmath",
32 | "attrs_inline",
33 | "colon_fence",
34 | "deflist",
35 | "dollarmath",
36 | "fieldlist",
37 | "html_admonition",
38 | "html_image",
39 | "inv_link",
40 | "linkify",
41 | "replacements",
42 | "smartquotes",
43 | "strikethrough",
44 | "substitution",
45 | "tasklist",
46 | ]
47 | ```
48 |
49 | :::{versionchanged} 0.13.0
50 | `myst_enable_extensions` replaces previous configuration options:
51 | `admonition_enable`, `figure_enable`, `dmath_enable`, `amsmath_enable`, `deflist_enable`, `html_img_enable`
52 | :::
53 |
54 | (syntax/typography)=
55 |
56 | ## Typography
57 |
58 | Adding `"smartquotes"` to `myst_enable_extensions` (in the {{ confpy }}) will automatically convert standard quotations to their opening/closing variants:
59 |
60 | - `'single quotes'`: 'single quotes'
61 | - `"double quotes"`: "double quotes"
62 |
63 | Adding `"replacements"` to `myst_enable_extensions` (in the {{ confpy }}) will automatically convert some common typographic texts
64 |
65 | text | converted
66 | ----- | ----------
67 | ``(c)``, ``(C)`` | (c)
68 | ``(tm)``, ``(TM)`` | (tm)
69 | ``(r)``, ``(R)`` | (r)
70 | ``(p)``, ``(P)`` | (p)
71 | ``+-`` | +-
72 | ``...`` | ...
73 | ``?....`` | ?....
74 | ``!....`` | !....
75 | ``????????`` | ????????
76 | ``!!!!!`` | !!!!!
77 | ``,,,`` | ,,,
78 | ``--`` | --
79 | ``---`` | ---
80 |
81 | (syntax/strikethrough)=
82 |
83 | ## Strikethrough
84 |
85 | ```{versionadded} 0.17.0
86 | ```
87 |
88 | The `strikethrough` extension allows text within `~~` delimiters to have a strikethrough (horizontal line) placed over it.
89 | For example, `~~strikethrough with *emphasis*~~` renders as: ~~strikethrough with *emphasis*~~.
90 |
91 | :::{warning}
92 | This extension is currently only supported for HTML output,
93 | and you will need to suppress the `myst.strikethrough` warning
94 | (see [](myst-warnings))
95 | :::
96 |
97 | (syntax/math)=
98 | ## Math shortcuts
99 |
100 | Math is parsed by adding to the `myst_enable_extensions` list option, in the {{ confpy }} one or both of:
101 |
102 | - `"dollarmath"` for parsing of dollar `$` and `$$` encapsulated math.
103 | - `"amsmath"` for direct parsing of [amsmath LaTeX environments](https://ctan.org/pkg/amsmath).
104 |
105 | These options enable their respective Markdown parser plugins, as detailed in the [markdown-it plugin guide](inv:markdown_it#md/plugins).
106 |
107 | :::{versionchanged} 0.13.0
108 | `myst_dmath_enable=True` and `myst_amsmath_enable=True` are deprecated, and replaced by `myst_enable_extensions = ["dollarmath", "amsmath"]`
109 | :::
110 |
111 | ### Dollar delimited math
112 |
113 | Enabling `dollarmath` will parse the following syntax:
114 |
115 | - Inline math: `$...$`
116 | - Display (block) math: `$$...$$`
117 |
118 | Additionally if `myst_dmath_allow_labels=True` is set (the default):
119 |
120 | - Display (block) math with equation label: `$$...$$ (1)`
121 |
122 | For example, `$x_{hey}=it+is^{math}$` renders as $x_{hey}=it+is^{math}$.
123 | This is equivalent to writing:
124 |
125 | ```md
126 | {math}`x_{hey}=it+is^{math}`
127 | ```
128 |
129 | :::{admonition} Escaping Dollars
130 | :class: tip
131 |
132 | Math can be escaped (negated) by adding a `\` before the first symbol, e.g. `\$a$` renders as \$a\$.
133 | Escaping can also be used inside math, e.g. `$a=\$3$` renders as $a=\$3$.
134 |
135 | Conversely `\\` will negate the escaping, so `\\$a$` renders as \\$a$.
136 | :::
137 |
138 | Block-level math can be specified with `$$` signs that wrap the math block you'd like to parse.
139 | For example:
140 |
141 | ```latex
142 | $$
143 | y & = ax^2 + bx + c \\
144 | f(x) & = x^2 + 2xy + y^2
145 | $$
146 | ```
147 |
148 | becomes
149 |
150 | $$
151 | y & = ax^2 + bx + c \\
152 | f(x) & = x^2 + 2xy + y^2
153 | $$
154 |
155 | This is equivalent to the following directive:
156 |
157 | ````md
158 | ```{math}
159 | y & = ax^2 + bx + c \\
160 | f(x) & = x^2 + 2xy + y^2
161 | ```
162 | ````
163 |
164 | You can also add labels to block equations:
165 |
166 | ```latex
167 | $$
168 | e = mc^2
169 | $$ (eqn:best)
170 |
171 | This is the best equation {eq}`eqn:best`
172 | ```
173 |
174 | $$
175 | e = mc^2
176 | $$ (eqn:best)
177 |
178 | This is the best equation {eq}`eqn:best`
179 |
180 | There are a few other options available to control dollar math parsing:
181 |
182 | `myst_dmath_allow_space=False`, will cause inline math to only be parsed if there are no initial / final spaces, e.g. `$a$` but not `$ a$` or `$a $`.
183 |
184 | `myst_dmath_allow_digits=False`, will cause inline math to only be parsed if there are no initial / final digits, e.g. `$a$` but not `1$a$` or `$a$2`.
185 |
186 | These options can both be useful if you also wish to use `$` as a unit of currency.
187 |
188 | ```{versionadded} 0.14.0
189 | `myst_dmath_double_inline` option
190 | ```
191 |
192 | To allow display math (i.e. `$$`) within an inline context, set `myst_dmath_double_inline = True` (`False` by default).
193 | This allows for example:
194 |
195 | ```latex
196 | Hence, for $\alpha \in (0, 1)$,
197 | $$
198 | \mathbb P (\alpha \bar{X} \ge \mu) \le \alpha;
199 | $$
200 | i.e., $[\alpha \bar{X}, \infty)$ is a lower 1-sided $1-\alpha$ confidence bound for $\mu$.
201 | ```
202 |
203 | Hence, for $\alpha \in (0, 1)$,
204 | $$
205 | \mathbb P (\alpha \bar{X} \ge \mu) \le \alpha;
206 | $$
207 | i.e., $[\alpha \bar{X}, \infty)$ is a lower 1-sided $1-\alpha$ confidence bound for $\mu$.
208 |
209 | ### Math in other block elements
210 |
211 | Math will also work when nested in other block elements, like lists or quotes:
212 |
213 | ```md
214 | - A list
215 | - $$ a = 1 $$
216 |
217 | > A block quote
218 | > $$ a = 1 $$
219 | ```
220 |
221 | - A list
222 | - $$ a = 1 $$
223 |
224 | > A block quote
225 | > $$ a = 1 $$
226 |
227 | ### Direct LaTeX Math
228 |
229 | Want to use [amsmath](https://ctan.org/pkg/amsmath) LaTeX directly, with no dollars?
230 | See [the extended syntax option](syntax/amsmath).
231 |
232 | (syntax/mathjax)=
233 | ### Mathjax and math parsing
234 |
235 | When building HTML using the