diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-29 04:23:02 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-29 04:23:02 +0000 |
commit | 943e3dc057eca53e68ddec51529bd6a1279ebd8e (patch) | |
tree | 61fb7bac619a56dfbcdcbdb7b0d4d6535fc36fe9 /docs/configuration.md | |
parent | Initial commit. (diff) | |
download | myst-parser-upstream.tar.xz myst-parser-upstream.zip |
Adding upstream version 0.18.1.upstream/0.18.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/configuration.md')
-rw-r--r-- | docs/configuration.md | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..a87ce0b --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,106 @@ +(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 +``` + +## Local configuration + +```{versionadded} 0.18 +``` + +The following configuration variables are available at the document level. +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 +``` + +### 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 + +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 |