Changelog#
1. 4.0.0 - 2024-08-05#
This release bumps the supported versions of:
Python to
3.10
and greaterSphinx to
>=7,<9
Docutils to
>=0.19,<0.22
Additionally, footnotes are now parsed similar to the corresponding reStructuredText, in that resolution (between definitions and references) and ordering is now deferred to transforms on the doctree (in PR #931).
This allows for the proper interaction with other docutils/sphinx transforms, including those that perform translations, and logging of warnings for duplicate/unreferenced footnote definitions and also for footnote references with no definitions.
See the footnotes guide for more information.
Full Changelog: v3.0.1…v4.0.0
2. 3.0.1 - 2024-04-28#
2.1. 🐛 Bug Fixes#
Account for the final directive option having an empty value, by @chrisjsewell in PR #924
Re-allow indented directive option blocks, by @chrisjsewell in PR #925
Full Changelog: v3.0.0…v3.0.1
3. 3.0.0 - 2024-04-23#
3.1. Upgraded dependencies#
⬆️ Update docutils requirement from >=0.16,<0.21 to >=0.18,<0.22 by @chrisjsewell in PR #916
3.2. New features#
✨ Allow for use of the
line-block
directive by @chrisjsewell in PR #900✨ Emits sphinx include-read event by @sumezulike in PR #887
3.3. Improvements#
👌 Nested parse attribution in
attr_block
by @chrisjsewell in PR #831👌 Directive option parsing by @chrisjsewell in <gh-pr:796
👌 Improve directive parsing warnings by @chrisjsewell in PR #893
👌 Allow for opening external links in new tabs (#856) by @marjus45 in PR #857
3.4. Internal#
🔧 Replace black, isort, pyupgrade with ruff formatter by @chrisjsewell in PR #833
🔧 remove redundant mypy config by @danieleades in PR #866
🔧 Add additional Ruff lints (and fix issues) by @danieleades in PR #862
🔧 mypy- disallow ‘any generics’ by @danieleades in PR #865
🔧 Fix docutils deprecation in option parsing by @agoose77 in PR #842
3.5. Documentation#
📚 Fix a broken link in configuration.md by @zupo in PR #907
📚 Add linkify dependency to contributing docs. by @jhcole in PR #792
📚 Fix the double
used
in docs/syntax/math.md by @ice-tong in PR #810📚 Also add linkify to pip install command in README by @n-peugnet in PR #851
📚 Fix the code section title in live preview by @BoboTiG in PR #875
📚 Fix admonition example by @72757373656c6c in PR #904
📚 Fix url for jupyter book gallery by @72757373656c6c in PR #905
📚 Update theme version by @chrisjsewell in PR #918
📚 Fix typo by @blakeNaccarato in PR #911
📚 Fix architecture typo (#855) by @72757373656c6c in PR #910
Full Changelog: v2.0.0…v3.0.0
4. 2.0.0 - 2023-06-13#
This release primarily updates core myst-parser dependencies, with some minor changes to parsing behaviour:
⬆️ UPGRADE:
markdown-it-py
to v3 (PR #773)This is mainly a non-breaking change, fixing some edge cases in parsing
See: executablebooks/markdown-it-py and executablebooks/mdit-py-plugins
⬆️ UPGRADE:
linkify-it-py
to v2 (PR #675)Also fixes some edge cases in parsing
⬆️ UPGRADE: Add support for
docutils
v0.20 (PR #775)No significant changes, see https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-20-2023-05-04
⬆️ UPGRADE: Add support for
sphinx
v7, and remove v5 support (PR #776)No significant changes, see https://www.sphinx-doc.org/en/master/changes/index.html
⬆️ UPGRADE: Remove Python 3.7 support and add testing for Python 3.11 (PR #772)
👌 Improve default slug generation for heading anchors, thanks to @Cimbali (PR #777)
This change makes the slug generation closer to GitHub, in that, starting/ending whitespace will not be stripped. For example,
# ` a` b `c `
will now correctly create the slug-a-b-c-
and nota-b-c
👌 IMPROVE: Substitution extension (PR #777)
Allow any value type (including dict, list, datetime) and emit a
myst.substitution
warning for errors in resolving the substitution content.
🧪 Introduce a gate/check GHA job, thanks to @webknjaz (PR #635)
Full Changelog: v1.0.0…v2.0.0
5. 1.0.0 - 2023-03-07#
🎉 MyST-Parser 1.0.0 🎉
This changes absolutely nothing in the code, or about the maintenance/release policy of this project. But it does feel about time 😄
6. 0.19.2 - 2023-03-02#
✨ NEW: Add myst_fence_as_directive config (PR #742)
Setting the following config, for example:
extensions = ["myst_parser", "sphinxcontrib.mermaid"]
myst_fence_as_directive = ["mermaid"]
# optional to use directive options
myst_enable_extensions = ["attrs_block"]
allows for one to write:
{caption="My caption"}
{alt="HTML alt" align=center}
```mermaid
graph LR
a --> b
```
and have interoperable rendering with tools like GitHub.
🎉 New contributors:
7. 0.19.1 - 2023-03-07#
🐛 FIX NoURI
error in doc reference resolution, for texinfo builds (PR #734)
8. 0.19.0 - 2023-03-01#
This release brings a number of exciting new features, improvements, and upgrades 🎉
Full Changelog: v0.18.1…v0.19.0
8.1. 📚 Rewritten documentation#
The documentation has been almost completely rewritten, with a clearer structure, many more examples, rich hover tips, and a new live preview page (powered by pyscript, PR #717).
The code base API is also now fully documented by sphinx-autodoc2, which even allows for MyST docstrings! (PR #704).
8.2. ⬆️ Add Sphinx 6 support, drop Sphinx 4#
The code base has been updated to support sphinx v6, and is no longer tested against sphinx v4 (PR #664)
8.3. 📄 Extended docutils (single-page) support#
The docutils
parser now supports many more features, and improvements to support live previews:
myst_suppress_warnings
option added, mirroring Sphinx, to suppress MyST warnings (PR #655)myst_meta_html
andmyst_substitutions
options are now supported (PR #672)myst_heading_anchors
option is now supported (PR #678)Math block labels syntax is now supported (PR #668)
Missing directive/role errors errors are now suppressible warnings (PR #687)
Non-fatal directive parsing errors are now suppressible warnings (PR #682)
Most of the extended markdown syntax below is also supported
8.4. 🔗 Extended Markdown links#
See the Extended Markdown links section for the full guide.
You can now use standard Markdown link syntax to reference many different types of targets, in a more consistent way.
[text](relative/path/myfile.md)
work as previously, to link to files, but they can also be relative to source directory:[text](/path/from/srcdir/myfile.md)
. You can also use<project:file.md>
<path:myfile.txt>
will link specifically to a downloadable file[text](#target)
or<project:#target>
will link (in order of priority) to any local target, local heading anchor, target in the same project, or intersphinx (inventory) target[text](inv:name:domain:type#target)
will link specifically to a Sphinx inventory target, or to any inventory<inv:#target>
, and can even use*
wildcards like<inv:*:*:*#*.target>
This can even be used in docutils, with the new
myst_inventories
config optionThe
myst-inv
CLI makes it easy to find the correct inventory target
小技巧
It is advised (although not immediately necessary) to prefix all internal references with #
.
For example, [...](my-reference)
, should be changed to [...](#my-reference)
.
8.5. {}
Attributes syntax#
The attrs_inline
and attrs_block
extensions allow for common Markdown syntaxes to be extended with greater control over the output.
For example, you can now add classes, ids, and other attributes to inline code, images, and links, as well as to code blocks and directives.
Inline code:
`a = 1`{#id .class l=python}
Images:
![image](image.png){#id .class width=100px}
Text spans:
[some text]{#id .class}
A paragraph block can have attributes too:
{#id .class}
This is a paragraph with an id and class
A code fence can be given line numbers and line emphasis:
{#id .class lineno-start=1 emphasize-lines="2,3"}
```python
a = 1
b = 2
c = 3
```
A definition list can be turned into a glossary, with referenceable terms:
{.glossary}
term name
: Definition of the term
Quote blocks can be given an attribution:
{attribution="Chris Sewell"}
> My quote
8.6. 👌 Miscellaneous improvements#
Nested headings (e.g. inside directives) are now allowed in MyST and are correctly rendered in HTML (PR #711)
The
colon_fence
extension now renders internal content as MyST, rather than as a code block (PR #713)The
include
directive in MyST documents now supports a:heading-offset:
option, to offset the heading levels in the included documentThe
myst_heading_slug_func
option now supports setting astr
which points to a fully qualified function name, e.g."module.path.func"
(PR #696)The
myst_enable_checkboxes
option allows for task list checkboxes to be enabled/disabled (PR #686)
8.7. Additional contributions#
🐛 FIX: Remove unnecessary assert in PR #659, thanks to @n-peugnet
🔧 ci(deps): setup dependabot (PR #669), thanks to @mmorel-35
🔧: Depend on typing_extensions only on
Python<3.8
in PR #642, thanks to @hukkin
9. 0.18.1 - 2022-27-09#
Full Changelog: v0.18.0…v0.18.1
10. 0.18.0 - 2022-06-07#
Full Changelog: v0.17.2…v0.18.0
This release adds support for Sphinx v5 (dropping v3), restructures the code base into modules, and also restructures the documentation, to make it easier for developers/users to follow.
It also introduces document-level configuration via the Markdown front-matter, under the myst
key.
See the Local configuration section for more information.
10.1. Breaking changes#
This should not be breaking, for general users of the sphinx extension (with sphinx>3
),
but will be for anyone directly using the Python API, mainly just requiring changes in import module paths.
The to_docutils
, to_html
, to_tokens
(from myst_parser/main.py
) and mock_sphinx_env
/parse
(from myst_parser.sphinx_renderer.py
) functions have been removed, since these were primarily for internal testing.
Instead, for single page builds, users should use the docutils parser API/CLI (see Single Page Builds),
and for testing, functionality has been moved to chrisjsewell/sphinx-pytest.
The top-level html_meta
and substitutions
front-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the myst
config, e.g.
---
html_meta:
"description lang=en": "metadata description"
substitutions:
key1: I'm a **substitution**
---
is replaced by:
---
myst:
html_meta:
"description lang=en": "metadata description"
substitutions:
key1: I'm a **substitution**
---
10.2. Key PRs#
♻️📚 Restructure code base and documentation (PR #566)
⬆️ Drop Sphinx 3 and add Sphinx 5 support (PR #579)
🐛 FIX:
parse_directive_text
when body followed by options (PR #580)🐛 FIX: floor table column widths to integers (PR #568), thanks to @Jean-Abou-Samra!
11. 0.17.2 - 2022-04-17#
Full Changelog: v0.17.1…v0.17.2
♻️ REFACTOR: Replace
attrs
bydataclasses
for configuration (PR #557)
12. 0.17.1 - 2022-04-15#
Full Changelog: v0.17.0…v0.17.1
13. 0.17.0 - 2022-02-11#
This release contains a number of breaking improvements.
Full Changelog: v0.16.1…v0.17.0
13.1. ‼️ Markdown link resolution improvements#
WARNING: This is a breaking change for links that rely on auto-generated anchor links. You should now manually enable auto-generated anchor links if you see errors like WARNING reference target not found
.
Markdown links are of the format [text](link)
.
MyST-Parser looks to smartly resolve such links, by identifying if they are:
A link to an external resource, e.g.
[text](http://example.com)
A link to another source document, e.g.
[text](file.md)
If
header-anchors
are enabled, anchor links are also supported, e.g.[text](file.md#anchor)
A link to an internal sphinx cross-reference, e.g.
[text](my-reference)
an additional situation is now supported:
A link to a source file, which is not a document, e.g.
[text](file.js)
. This behaves similarly to the sphinxdownload
role.
In addition, configuration to more finely tune this behaviour has been added.
myst_all_links_external=True
, will make all links be treated as (1)myst_url_schemes=("http", "https")
, sets what URL schemes are treated as (1)myst_ref_domains=("std", "py")
, sets what Sphinx reference domains are checked, when handling (3)
See Markdown Links and Referencing for more information.
13.2. ‼️ Dollarmath is now disabled by default#
WARNING: This is a breaking change for dollar math. You should now manually enable dollar math (see below).
The default configuration is now myst_enable_extensions=()
, instead of myst_enable_extensions=("dollarmath",)
.
If you are using math enclosed in $
or $$
in your documents, you should enable dollarmath
explicitly.
See Dollar delimited math for more information.
13.3. ⬆️ Drop Python 3.6 support#
MyST-Parser now supports, and is tested against, Python 3.7 to 3.10.
13.4. ✨ Add the strikethrough
extension and myst_gfm_only
configuration#
The strikethrough
extension allows text within ~~
delimiters to have a strike-through (horizontal line) placed over it.
For example, ~~strikethrough with *emphasis*~~
renders as: strikethrough with emphasis.
Important: This extension is currently only supported for HTML output.
See Strikethrough for more information.
The myst_gfm_only=True
configuration sets up specific configuration, to enable compliance only with GitHub-flavored Markdown, including enabling the strikethrough
, tasklist
and linkify
extensions, but disabling support for roles and directives.
13.5. ✨ Add myst_title_to_header
configuration#
Setting myst_title_to_header=True
, allows for a title
key in the frontmatter to be used as the document title.
for example:
---
title: My Title with *emphasis*
---
would be equivalent to:
# My Title with *emphasis*
See Front matter for more information.
13.6. 👌 Internal improvements#
👌 IMPROVE: Convert nested headings to rubrics.
Headings within directives are not directly supported by sphinx, since they break the structure of the document. Previously myst-parser would emit a myst.nested_header
warning, but still generate the heading, leading to unexpected outcomes.
Now the warning is still emitted, but also the heading is rendered as a rubric non-structural heading (i.e. it will not show in the ToC).
Other internal improvements primarily focused in improving support for the for “docutils-only” use, introduced in v0.16
:
♻️ REFACTOR:
default_parser
->create_md_parser
in PR #474👌 IMPROVE: Add
bullet
attribute tobullet_list
node in PR #465👌 IMPROVE: Use correct renderer for
state.inline_text
in PR #466👌 IMPROVE: Docutils parser settings in PR #476
🐛 FIX: front-matter rendering with docutils in PR #477
👌 IMPROVE: Code block highlighting in PR #478
👌 IMPROVE:
note_refname
for docutils internal links in PR #481🐛 FIX: Ordered list starting number in PR #483
👌 IMPROVE: Propagate enumerated list suffix in PR #484
👌 IMPROVE:
DocutilsRenderer.create_highlighted_code_block
in PR #488🐛 FIX: Source line reporting for nested parsing in PR #490
🔧 MAINTAIN: Implement
MockInliner.parse
in PR #504
14. 0.16.1 - 2021-12-16#
✨ NEW: Add myst_linkify_fuzzy_links
option.
When using the linkify
extension, this option can be used to disable matching of links that do not contain a schema (such as http://
).
15. 0.16.0 - 2021-12-06#
This release contains a number of exciting improvements:
15.1. Upgrade of Markdown parser#
markdown-it-py
has been upgraded to v2.0.0.
This upgrade brings full compliance with the CommonMark v0.30 specification.
Additionally, mdit-py-plugins
has been upgraded to v0.3.0.
This improves the parsing of the MyST target syntax, to allow for spaces and additional special characters in the target name,
for example this is now valid:
(a bc |@<>*./_-+:)=
# Header
Also MyST role syntax now supports unlimited length in the role name and new lines in the content. For example, this is now valid:
{abc}`xy
new line`
15.2. Improvements for Docutils-only use#
MyST now allows for Docutils-only use (outside of Sphinx), that allows for MyST configuration options to be set via the docutils.conf
file, or on the command line.
On installing MyST-Parser, the following CLI-commands are made available:
myst-docutils-html
: converts MyST to HTMLmyst-docutils-html5
: converts MyST to HTML5myst-docutils-latex
: converts MyST to LaTeXmyst-docutils-xml
: converts MyST to docutils-native XMLmyst-docutils-pseudoxml
: converts MyST to pseudo-XML (to visualise the AST structure)
You can also install the myst-docutils package from pip
,
which includes no direct install requirements on docutils or sphinx.
See MyST with Docutils for more information.
Thanks to help from @cpitclaudel!
15.3. Include MyST files in RST files#
With docutils>=0.17
, the include
directive has a parser
option.
This can be used with myst-parser to include MyST files in RST files.
Parse using the docutils only parser:
.. include:: include.md
:parser: myst_parser.docutils_
Parse using the sphinx parser:
.. include:: include.md
:parser: myst_parser.sphinx_
15.4. Addition of the fieldlist
syntax extension#
Field lists are mappings from field names to field bodies, based on the reStructureText syntax:
:name only:
:name: body
:name:
Multiple
Paragraphs
This should eventually allow for MyST Markdown docstrings! (see executablebooks/MyST-Parser#228)
See Field Lists syntax for more information.
15.5. Improvements to table rendering#
Tables with no body are now allowed, for example:
| abc | def |
| --- | --- |
Also cell alignment HTML classes have now been changed to: text-left
, text-center
, or text-right
, for example:
| left | center | right |
| :--- | :----: | ----: |
| a | b | c |
is converted to:
<table class="colwidths-auto">
<thead>
<tr>
<th class="text-left head"><p>left</p></th>
<th class="text-center head"><p>center</p></th>
<th class="text-right head"><p>right</p></th>
</tr>
</thead>
<tbody>
<tr>
<td class="text-left"><p>a</p></td>
<td class="text-center"><p>b</p></td>
<td class="text-right"><p>c</p></td>
</tr>
</tbody>
</table>
These classes should be supported by most sphinx HTML themes.
See Tables syntax for more information.
15.6. Pull Requests#
🐛 FIX: Add mandatory attributes on
enumerated_list
by @cpitclaudel in PR #418📚 DOCS: Add reference to MySTyc in landing page by @astrojuanlu in PR #413
⬆️ UPGRADE: markdown-it-py v2, mdit-py-plugins v0.3 by @chrisjsewell in PR #449
👌 IMPROVE: Table rendering by @chrisjsewell in PR #450
🐛 FIX: Ensure parent files are re-built if
include
file changes by @chrisjsewell in PR #451🐛 FIX: Convert empty directive option to
None
by @chrisjsewell in PR #452👌 IMPROVE: Add
\\
for hard-breaks in latex by @chrisjsewell in PR #453🔧 MAINTAIN: Remove empty “sphinx” extra by @hukkin in PR #350
✨ NEW: Add
fieldlist
extension by @chrisjsewell in PR #455✨ NEW: Add Docutils MyST config and CLI by @cpitclaudel in PR #426
🔧 MAINTAIN: Add publishing job for
myst-docutils
by @chrisjsewell in PR #456🧪 TESTS: Add for
gettext_additional_targets
by @jpmckinney in PR #459
15.7. New Contributors#
@cpitclaudel made their first contribution in PR #418
@astrojuanlu made their first contribution in PR #413
Full Changelog: executablebooks/MyST-Parser
16. 0.15.2 - 2021-08-26#
This is mainly a maintenance release that fixes some incompatibilities with sphinx<3.1
, improvements for compatibility
with docutils=0.17
, and improvements to robustness.
17. 0.15.1 - 2021-06-18#
👌 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"]
.
18. 0.15.0 - 2021-06-13#
18.1. Upgraded to sphinx
v4 ⬆️#
A principe change in this release is to updates the requirements of myst-parser from sphinx>=2,<4
to sphinx>=3,<5
.
18.2. Changed MathJax handling ♻️#
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.
18.3. Set URL scheme defaults ‼️#
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.
18.4. Added myst_heading_slug_func
option 👌#
Use this option to specify a custom function to auto-generate heading anchors (see Auto-generated header anchors).
Thanks to @jpmckinney!
19. 0.14.0 - 2021-05-04#
19.1. Upgrade to markdown-it-py
v1.0 ⬆️#
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.
19.2. New Features ✨#
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_extensions
configuration to enable.See the optional syntax guide for further information.
The
sub-ref
role 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-words
andwordcount-minutes
, computed by the markdown-it-pywordcount_plugin
.> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
See the roles syntax guide for further information.
The
dmath_double_inline
configuration option allows display math (i.e.$$
) within an inline context. See the math syntax guide for further information.
19.3. Remove v0.13 deprecations ‼️#
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}
19.4. Fix extraction of nested footnotes 🐛#
Previously footnote definitions in block elements like lists would crash the parsing:
- [^e]: footnote definition in a block element
These are now correctly extracted.
20. 0.13.7 - 2021-04-25#
👌 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.
21. 0.13.6 - 2021-04-10#
🐛 FIX: docutils v0.17
compatibility
22. 0.13.5 - 2021-02-15#
⬆️ 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
rawtext
in 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 thegettext
builder, 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_warnings
config option. See How-to suppress warnings for more information.
23. 0.13.3 - 2021-01-20#
Minor fixes:
🐛 FIX: front-matter parsing for bibliographic keys
🐛 FIX: directive/role name translations
👌 IMPROVE: Add warning for multiple footnote definitions
24. 0.13.2 - 2021-01-20#
- ✨ NEW: Add
html_admonition
extension By adding
"html_admonition"
tomyst_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 typography 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.
25. 0.13.1 - 2020-12-31#
👌 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 }}
26. 0.13.0 - 2020-12-18#
This release makes some major updates to the optional syntaxes. For full details see Optional MyST Syntaxes.
26.1. 🗑 Deprecations#
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*
:::
26.2. ✨ New#
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**
:::
26.3. 👌 Improvements#
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"> |
27. 0.12.10 - 2020-09-21#
- 🐛 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 PR #253
28. 0.12.9 - 2020-09-08#
- ✨ NEW: Auto-generate heading anchors.
This utilises
markdown-it-py
’sanchors-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
viamyst_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.
29. 0.12.7 - 2020-08-31#
- ✨ NEW: Want to include your README.md in the documentation?
(👌 added relative-docs
option in 0.12.8)
30. 0.12.5 - 2020-08-28#
- ✨ NEW: Add Markdown figure syntax
Setting
myst_figure_enable = True
in your sphinxconf.py
, combines the above two extended syntaxes, to create a fully Markdown compliant version of thefigure
directive. See Markdown Figures for details.
(👌 formatting of caption improved in 0.12.6)
31. 0.12.4 - 2020-08-27#
👌 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
32. 0.12.3 - 2020-08-26#
- ✨ 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
: Definition
See 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 frommyst_override_mathjax
tomyst_update_mathjax
. See Mathjax and math parsing for further details.
33. 0.12.2 - 2020-08-25#
- ✨ 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 🎉
34. 0.12.1 - 2020-08-19#
✨ NEW: Add myst_commonmark_only
config option, for restricting the parser to strict CommonMark (no extensions).
35. 0.12.0 - 2020-08-19#
35.1. ‼️ BREAKING#
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).
35.2. Improved 👌#
More configuration options for math parsing (see MyST configuration options).
36. 0.11.2 - 2020-07-13#
36.1. Added ✨#
<img src="file.png" width="200px">
tag parsing to sphinx representation, see the image syntax guide
36.2. Improved 👌#
[title](link)
syntax now works with intersphinx references. Recognised URI schemas can also be configured, see the configuration options
37. 0.11.1 - 2020-07-12#
37.1. Fix#
Correctly pin required minimum markdown-it-py version
38. 0.11.0 - 2020-07-12#
38.1. Added ✨#
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.
38.2. Breaking ‼️#
Sphinx configuration options are now set as separate variables, rather than a single dict. See MyST configuration options for details.
39. 0.10.0 - 2020-07-08#
39.1. Improved 👌#
Support Sphinx version 3 in PR #197 (@chrisjsewell)
Update Trove Classifiers in PR #192 (@chrisjsewell)
Add functionality to use docutils specialized role in PR #189 (@chrisjsewell)
39.2. Contributors to this release#
(GitHub contributors page for this release)
@AakashGfude | @asmeurer | @choldgraf | @chrisjsewell | @codecov | @webknjaz | @welcome
40. Past Releases#
40.1. Contributors#
(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