👌 IMPROVE: MathJax compatibility with nbsphinx
nbsphinx also overrides the MathJax configuration.
For compatibility, output_area is added to the list of default processed classes, and the override warning is allowed to be suppressed with suppress_warnings = ["myst.mathjax"].
A principe change in this release is to updates the requirements of myst-parser from sphinx>=2,<4 to sphinx>=3,<5.
Instead of removing all $ processing for the whole project,
during MyST document parsing, the top-level section is now given the classes tex2jax_ignore and mathjax_ignore (turning off default MathJax processing of all HTML elements)
and MathJax is then configured to process elements with the tex2jax_process|mathjax_process|math classes.
See the math syntax guide for further information.
The myst_url_schemes default is now: ("http", "https", "mailto", "ftp").
This means that only these URL will be considered as external (e.g. [](https://example.com)),
and references like [](prefix:main) will be considered as internal references.
Set myst_url_schemes = None, to revert to the previous default.
Use this option to specify a custom function to auto-generate heading anchors (see Auto-generated header anchors).
Thanks to @jpmckinney!
This release updates the code-base to fully support the markdown-it-py v1.0.0 release.
In particular for users, this update alters the parsing of tables to be consistent with the Github Flavoured Markdown (GFM) specification.
-
Task lists utilise the markdown-it-py tasklists plugin, and are applied to Markdown list items starting with
[ ]or[x].- [ ] An item that needs doing - [x] An item that is complete
Add "tasklist" to the
myst_enable_extensionsconfiguration to enable.See the optional syntax guide for further information.
-
The
sub-refrole has been added for use identical to ReST's|name|syntax.This allows one to access Sphinx's built-in
|today|,|release|and|version|substitutions, and also introduces two new substitutions:wordcount-wordsandwordcount-minutes, computed by the markdown-it-pywordcount_plugin.> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min readSee the roles syntax guide for further information.
-
The
dmath_double_inlineconfiguration option allows display math (i.e.$$) within an inline context. See the math syntax guide for further information.
The deprecations made to extension configurations and colon fences in 0.13.0 (see below) have now been removed:
- Configuration variables:
myst_admonition_enable,myst_figure_enable,myst_dmath_enable,myst_amsmath_enable,myst_deflist_enable,myst_html_img_enable :::{admonition,class}->:::{admonition}\n:class: class:::{figure}->:::{figure-md}
Previously footnote definitions in block elements like lists would crash the parsing:
- [^e]: footnote definition in a block elementThese are now correctly extracted.
👌 IMPROVE: Add warning for nested headers:
Nested headers are not supported within most elements (this is a limitation of the docutils/sphinx document structure), and can lead to unexpected outcomes. For example in admonitions:
```{note}
# Unsupported Header
```A warning (of type myst.nested_header) is now emitted when this occurs.
🔧 MAINTAIN: Python 3.9 is now officially supported.
🐛 FIX: docutils v0.17 compatibility
- ⬆️ UPGRADE: required markdown-it-py to
v0.6.2: In particular, this fixes missing source line mappings for table rows and their children - 👌 IMPROVE: Store
rawtextin AST nodes: We now ensure that the raw text is propagated from the Markdown tokens to the Sphinx AST. In particular, this is required by thegettextbuilder, to generate translation POT templates. Thanks to @jpmckinney! - ✨ NEW: Add warning types
myst.subtype: All parsing warnings are assigned a type/subtype, and also the messages are appended with them. These warning types can be suppressed with the sphinxsuppress_warningsconfig option. See How-to suppress warnings for more information.
Minor fixes:
- 🐛 FIX: front-matter parsing for bibliographic keys
- 🐛 FIX: directive/role name translations
- 👌 IMPROVE: Add warning for multiple footnote definitions
✨ NEW: Add html_admonition extension
: By adding "html_admonition" to myst_enable_extensions, you can enable parsing of <div class="admonition"> HTML blocks to sphinx admonitions.
: This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks.
: For example:
<div class="admonition note" name="html-admonition">
<p class="title">This is the **title**</p>
This is the *content*
</div>: See the optional syntax guide for further information.
👌 IMPROVE: Footnotes
: If the label is an integer, then it will always use this integer for the rendered label (i.e. they are manually numbered).
: Add myst_footnote_transition configuration, to turn on/off transition line.
: Add footnotes class to transition <hr> in HTML.
: See the syntax guide for further information.
👌 IMPROVE: substitution extension logic
: Parse inline substitutions without block rules, unless the substitution starts with a directive.
🐛 FIX: Render front-matter as field_list
: To improve use by sphinx extensions).
👌 IMPROVE: Code quality
: Add isort and mypy type checking to code base.
(thanks to contributors @akhmerov, @tfiers)
👌 Directives can now be used for inline substitutions, e.g.
---
substitutions:
key: |
```{image} img/fun-fish.png
:alt: fishy
:height: 20px
```
---
An inline image: {{ key }}This release makes some major updates to the optional syntaxes. For full details see Optional MyST Syntaxes.
myst_enable_extensions = ["dollarmath", ...] now replaces and deprecates individual enable configuration variables: admonition_enable -> "colon_fence", figure_enable -> "colon_fence", dmath_enable -> "dollarmath", amsmath -> "colon_fence", deflist_enable -> "deflist", html_img_enable -> "html_image".
The colon_fence extension (replacing admonition_enable) now works exactly the same as normal ``` code fences, but using ::: delimiters. This is helpful for directives that contain Markdown text, for example:
:::{admonition} The title
:class: note
This note contains *Markdown*
:::The smartquotes extension will automatically convert standard quotations to their opening/closing variants:
'single quotes': ‘single quotes’"double quotes": “double quotes”
The linkify extension will automatically identify “bare” web URLs, like www.example.com, and add hyperlinks; www.example.com.
This extension requires that linkify-it-py is installed.
The replacements extension will automatically convert some common typographic texts, such as +- -> ±.
The substitution extension allows you to specify "substitution definitions" in either the conf.py (as myst_substitutions) and/or individual file's front-matter (front-matter takes precedence), which will then replace substitution references. For example:
---
substitutions:
key1: definition
---
{{ key1 }}The substitutions are assessed as jinja2 expressions and includes the Sphinx Environment as env, so you can do powerful thinks like:
{{ [key1, env.docname] | join('/') }}
The figure-md directive has been added (replacing enable_figure), which parses a "Markdown friendly" figure (used with the colon_fence extension):
:::{figure-md} fig-target
:class: myclass
<img src="img/fun-fish.png" alt="fishy" class="bg-primary mb-1" width="200px">
This is a caption in **Markdown**
:::Using the html_image extension, HTML images are now processed for both blocks and (now) inline.
So you can correctly do, for example:
I’m an inline image: <img src="img/fun-fish.png" height="20px">
| table column |
| ----------------------------------------- |
| <img src="img/fun-fish.png" width="20px"> |🐛 FIX: allow dates to be parsed in frontmatter. : This fixes a bug that would raise errors at parse time if non-string date objects were in front-matter YAML. See #253
✨ NEW: Auto-generate heading anchors.
: This utilises markdown-it-py's anchors-plugin, to generate unique anchor "slugs" for each header (up to a certain level),
and allows them to be referenced via a relative path, e.g. [](./file.md#header-anchor), or in the same document, e.g. [](#header-anchor).
Slugs are generated in the GitHub style (see here); lower-case text, removing punctuation, replacing spaces with -, enforce uniqueness via suffix enumeration -1.
It is enabled in your conf.py via myst_heading_anchors = 2 (sets maximum heading level).
🐛 FIX: doc reference resolution for singlehtml/latex.
: These reference resolutions are passed to the "missing-reference" event, and require the node["refdoc"] attribute to be available, which was missing for [text](./path/to/file.md) type references.
✨ NEW: Want to include your README.md in the documentation? : See including a file from outside the docs folder.
(👌 added relative-docs option in 0.12.8)
✨ NEW: Add Markdown figure syntax
: Setting myst_figure_enable = True in your sphinx conf.py, combines the above two extended syntaxes,
to create a fully Markdown compliant version of the figure directive.
See Markdown Figures for details.
(👌 formatting of caption improved in 0.12.6)
👌 IMPROVE: the mathjax extension is now only overridden if strictly necessary (to support dollar and ams math), and the override is more precise, to mitigate any unwanted side-effects
✨ NEW: Add definition lists.
: This addition, enabled by myst_deflist_enable = True, allows for "Pandoc style" definition lists to be parsed and rendered, e.g.
Term 1
: DefinitionSee the Definition Lists documentation for further details.
👌 IMPROVE: mathjax_config override.
: Only mathjax_config["tex2jax"] will now be overridden, in order to not interfere with other user configurations, such as adding TeX macros.
The configuration name has also changed from myst_override_mathjax to myst_update_mathjax.
See Mathjax and math parsing for further details.
✨ NEW: Add the eval-rst directive
: This directive parses its contents as ReStructuredText, which integrates back into the rest of the document, e.g. for cross-referencing. See this documentation for further explanation.
In particular, this addition solves some outstanding user requests:
Thanks to @stephenroller for the contribution 🎉
✨ NEW: Add myst_commonmark_only config option, for restricting the parser to strict CommonMark (no extensions).
If you are using math in your documents, be sure to read the updated Math syntax guide!
In particular, the Mathjax configuration is now overridden, such that LaTeX environments will only be rendered if myst_amsmath_enable=True is set.
The myst_math_delimiters option has also been removed (please open an issue if you would like brackets math parsing to be re-implemented).
In addition the myst_html_img option name has been changed to myst_html_img_enable.
Some underlying code has also been refactored, to centralise handling of configuration options (see commit 98573b9).
More configuration options for math parsing (see MyST configuration options).
<img src="file.png" width="200px">tag parsing to sphinx representation, see the image syntax guide
[title](link)syntax now works with intersphinx references. Recognised URI schemas can also be configured, see the configuration options
- Correctly pin required minimum markdown-it-py version
-
Special admonition directive syntax (optional):
:::{note} This text is **standard** _Markdown_ :::See the syntax guide section for details.
-
Direct parsing of amsmath LaTeX equations (optional). See the syntax guide section for details.
- Sphinx configuration options are now set as separate variables, rather than a single dict. See MyST configuration options for details.
- Support Sphinx version 3 #197 (@chrisjsewell)
- Update Trove Classifiers #192 (@chrisjsewell)
- Add functionality to use docutils specialized role #189 (@chrisjsewell)
(GitHub contributors page for this release)
@AakashGfude | @asmeurer | @choldgraf | @chrisjsewell | @codecov | @webknjaz | @welcome
(GitHub contributors page for these releases)
@akhmerov | @asmeurer | @certik | @choldgraf | @chrisjsewell | @codecov | @dhermes | @filippo82 | @jlperla | @jstac | @martinagvilas | @mlncn | @mmcky | @moorepants | @najuzilu | @nathancarter | @pauleveritt | @phaustin | @rossbar | @rowanc1 | @sbliven | @webknjaz