Changelog
### 4.0.0
```
This release bumps the supported versions of:
- Python to ``3.10`` and greater
- Sphinx 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 <gh-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](syntax/footnotes) for more information.
**Full Changelog**: [v3.0.1...v4.0.0](https://github.com/executablebooks/MyST-Parser/compare/v3.0.1...v4.0.0)
```
### 3.0.1
```
🐛 Bug Fixes
- Account for the final directive option having an empty value, by <gh-user:chrisjsewell> in <gh-pr:924>
- Re-allow indented directive option blocks, by <gh-user:chrisjsewell> in <gh-pr:925>
**Full Changelog**: [v3.0.0...v3.0.1](https://github.com/executablebooks/MyST-Parser/compare/v3.0.0...v3.0.1)
```
### 3.0.0
```
Upgraded dependencies
- ⬆️ Add support for Python 3.12 by <gh-user:hugovk> in <gh-pr:848>
- ⬆️ Update docutils requirement from >=0.16,<0.21 to >=0.18,<0.22 by <gh-user:chrisjsewell> in <gh-pr:916>
New features
- ✨ Allow for use of the `line-block` directive by <gh-user:chrisjsewell> in <gh-pr:900>
- ✨ Emits sphinx include-read event by <gh-user:sumezulike> in <gh-pr:887>
Improvements
- 👌 Nested parse attribution in `attr_block` by <gh-user:chrisjsewell> in <gh-pr:831>
- 👌 Directive option parsing by <gh-user:chrisjsewell> in <gh-pr:796
- 👌 Improve directive parsing warnings by <gh-user:chrisjsewell> in <gh-pr:893>
- 👌 Allow for opening external links in new tabs (856) by <gh-user:marjus45> in <gh-pr:857>
Internal
- 🔧 Replace black, isort, pyupgrade with ruff formatter by <gh-user:chrisjsewell> in <gh-pr:833>
- 🔧 remove redundant mypy config by <gh-user:danieleades> in <gh-pr:866>
- 🔧 Add additional Ruff lints (and fix issues) by <gh-user:danieleades> in <gh-pr:862>
- 🔧 mypy- disallow 'any generics' by <gh-user:danieleades> in <gh-pr:865>
- 🔧 Fix docutils deprecation in option parsing by <gh-user:agoose77> in <gh-pr:842>
Documentation
- 📚 Fix a broken link in configuration.md by <gh-user:zupo> in <gh-pr:907>
- 📚 Add linkify dependency to contributing docs. by <gh-user:jhcole> in <gh-pr:792>
- 📚 Fix the double `used` in docs/syntax/math.md by <gh-user:ice-tong> in <gh-pr:810>
- 📚 Also add linkify to pip install command in README by <gh-user:n-peugnet> in <gh-pr:851>
- 📚 Fix the code section title in live preview by <gh-user:BoboTiG> in <gh-pr:875>
- 📚 Fix admonition example by <gh-user:72757373656c6c> in <gh-pr:904>
- 📚 Fix url for jupyter book gallery by <gh-user:72757373656c6c> in <gh-pr:905>
- 📚 Update theme version by <gh-user:chrisjsewell> in <gh-pr:918>
- 📚 Fix typo by <gh-user:blakeNaccarato> in <gh-pr:911>
- 📚 Fix architecture typo (855) by <gh-user:72757373656c6c> in <gh-pr:910>
**Full Changelog**: [v2.0.0...v3.0.0](https://github.com/executablebooks/MyST-Parser/compare/v2.0.0...v3.0.0)
```
### 2.0.0
```
This release primarily updates core myst-parser dependencies,
with some minor changes to parsing behaviour:
* ⬆️ UPGRADE: `markdown-it-py` to v3 (<gh-pr:773>)
* This is mainly a non-breaking change, fixing some edge cases in parsing
* See: <https://github.com/executablebooks/markdown-it-py/releases/tag/v3.0.0>
and <https://github.com/executablebooks/mdit-py-plugins/releases/tag/v0.4.0>
* ⬆️ UPGRADE: `linkify-it-py` to v2 (<gh-pr:675>)
* Also fixes some edge cases in parsing
* See: <https://github.com/tsutsu3/linkify-it-py/blob/main/CHANGELOG.md>
* ⬆️ UPGRADE: Add support for `docutils` v0.20 (<gh-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 (<gh-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 (<gh-pr:772>)
* 👌 Improve default slug generation for heading anchors, thanks to <gh-user:Cimbali> (<gh-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 not `a-b-c`
* 👌 IMPROVE: Substitution extension (<gh-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 <gh-user:webknjaz> (<gh-pr:635>)
**Full Changelog**: [v1.0.0...v2.0.0](https://github.com/executablebooks/MyST-Parser/compare/v1.0.0...v2.0.0)
```
### 1.0
```
This release updates the code-base to fully support the [markdown-it-py](https://markdown-it-py.readthedocs.io) `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](https://github.github.com/gfm/#tables-extension-).
New Features ✨
- **Task lists** utilise the [markdown-it-py tasklists plugin](inv:markdown_itmd/plugins), and are applied to Markdown list items starting with `[ ]` or `[x]`.
markdown
- [ ] 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](docs/syntax/optional.mdtask-lists) 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` and `wordcount-minutes`, computed by the markdown-it-py [`wordcount_plugin`](https://github.com/executablebooks/mdit-py-plugins/pull/20).
markdown
> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
See [the roles syntax guide](docs/syntax/roles-and-directives.md) for further information.
- The **`dmath_double_inline`** configuration option allows display math (i.e. `$$`) within an inline context.
See [the math syntax guide](docs/syntax/optional.mdmath-shortcuts) for further information.
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}`
Fix extraction of nested footnotes 🐛
Previously footnote definitions in block elements like lists would crash the parsing:
markdown
- [^e]: footnote definition in a block element
These are now correctly extracted.
```
### 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 😄
```
### 0.19.2
```
✨ NEW: Add myst_fence_as_directive config (<gh-pr:742>)
Setting the following config, for example:
python
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:
`markdown
{caption="My caption"}
{alt="HTML alt" align=center}
mermaid
graph LR
a --> b
`
and have interoperable rendering with tools like GitHub.
🎉 New contributors:
- 📚 Add `html_last_updated_fmt = ""` to conf.py to fix documentation footer, thanks to <gh-user:jeanas> (<gh-pr:691>)
- 📚 Fix the sphinx-design example, thanks to <gh-user:recfab> (<gh-pr:738>)
```
### 0.19.1
```
🐛 FIX `NoURI` error in doc reference resolution, for texinfo builds (<gh-pr:734>)
```
### 0.19.0
```
This release brings a number of exciting new features, improvements, and upgrades 🎉
Full Changelog: [v0.18.1...v0.19.0](https://github.com/executablebooks/MyST-Parser/compare/v0.18.1...v0.19.0)
📚 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](https://pyscript.readthedocs.io/), <gh-pr:717>).
The code base API is also now fully documented by [sphinx-autodoc2](https://sphinx-autodoc2.readthedocs.io/), which even allows for MyST docstrings! (<gh-pr:704>).
⬆️ 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 (<gh-pr:664>)
📄 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 (<gh-pr:655>)
- `myst_meta_html` and `myst_substitutions` options are now supported (<gh-pr:672>)
- `myst_heading_anchors` option is now supported (<gh-pr:678>)
- Math block labels syntax is now supported (<gh-pr:668>)
- Missing directive/role errors errors are now suppressable warnings (<gh-pr:687>)
- Non-fatal directive parsing errors are now suppressable warnings (<gh-pr:682>)
- Most of the extended markdown syntax below is also supported
🔗 Extended Markdown links
See the [Extended Markdown links](docs/syntax/cross-referencing.md) 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:typetarget)` 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 option
- The `myst-inv` CLI makes it easy to find the correct inventory target
:::{tip}
It is advised (although not immediately necessary) to prefix all internal references with ``.
For example, `[...](my-reference)`, should be changed to `[...](my-reference)`.
:::
`{}` Attributes syntax
The [`attrs_inline` and `attrs_block`](docs/syntax/optional.mdattributes) 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: `{id .class width=100px}`
- Text spans: `[some text]{id .class}`
A paragraph block can have attributes too:
markdown
{id .class}
This is a paragraph with an id and class
A code fence can be given line numbers and line emphasis:
`markdown
{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:
markdown
{.glossary}
term name
: Definition of the term
Quote blocks can be given an attribution:
markdown
{attribution="Chris Sewell"}
> My quote
👌 Miscellaneous improvements
- Nested headings (e.g. inside directives) are now allowed in MyST and are correctly rendered in HTML (<gh-pr:711>)
- The `colon_fence` extension now renders internal content as MyST, rather than as a code block (<gh-pr:713>)
- The `include` directive in MyST documents now supports a `:heading-offset:` option, to offset the heading levels in the included document
- The `myst_heading_slug_func` option now supports setting a `str` which points to a fully qualified function name, e.g. `"module.path.func"` (<gh-pr:696>)
- The `myst_enable_checkboxes` option allows for task list checkboxes to be enabled/disabled (<gh-pr:686>)
Additional contributions
- 🐛 FIX: Remove unnecessary assert in <gh-pr:659>, thanks to <gh-user:n-peugnet>
- 🔧 ci(deps): setup dependabot (<gh-pr:669>), thanks to <gh-user:mmorel-35>
- 🔧: Depend on typing_extensions only on `Python<3.8` in <gh-pr:642>, thanks to <gh-user:hukkin>
```
### 0.18.1
```
Full Changelog: [v0.18.0...v0.18.1](https://github.com/executablebooks/MyST-Parser/compare/v0.18.0...v0.18.1)
- ⬆️ UPGRADE: docutils 0.19 support in <gh-pr:611>
- ✨ NEW: Add `attrs_image` (experimental) extension in <gh-pr:620>
- e.g. `{id .class width=100px}`
- See: [Optional syntax section](docs/syntax/optional.md)
- **Important**: This is an experimental extension, and may change in future releases
```
### 0.18.0
```
Full Changelog: [v0.17.2...v0.18.0](https://github.com/executablebooks/MyST-Parser/compare/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](docs/configuration.md) section for more information.
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 [](docs/docutils.md)),
and for testing, functionality has been moved to <https://github.com/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.
yaml
---
html_meta:
"description lang=en": "metadata description"
substitutions:
key1: I'm a **substitution**
---
is replaced by:
yaml
---
myst:
html_meta:
"description lang=en": "metadata description"
substitutions:
key1: I'm a **substitution**
---
Key PRs
- ♻️📚 Restructure code base and documentation (<gh-pr:566>)
- ⬆️ Drop Sphinx 3 and add Sphinx 5 support (<gh-pr:579>)
- 🐛 FIX: `parse_directive_text` when body followed by options (<gh-pr:580>)
- 🐛 FIX: floor table column widths to integers (<gh-pr:568>), thanks to <gh-user:Jean-Abou-Samra>!
```
### 0.17.2
```
Full Changelog: [v0.17.1...v0.17.2](https://github.com/executablebooks/MyST-Parser/compare/v0.17.1...v0.17.2)
- ♻️ REFACTOR: Replace `attrs` by `dataclasses` for configuration (<gh-pr:557>)
```
### 0.17.1
```
Full Changelog: [v0.17.0...v0.17.1](https://github.com/executablebooks/MyST-Parser/compare/v0.17.0...v0.17.1)
- 🐛 FIX: Heading anchor resolution for parallel builds (<gh-pr:525>)
- 🔧 MAINTAIN: Move packaging from setuptools to flit (<gh-pr:553>)
- 🔧 MAINTAIN: Directly specify attrs dependency (<gh-pr:555>)
```
### 0.17.0
```
This release contains a number of breaking improvements.
Full Changelog: [v0.16.1...v0.17.0](https://github.com/executablebooks/MyST-Parser/compare/v0.16.1...v0.17.0)
‼️ 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](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors) 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:
1. A link to an external resource, e.g. `[text](http://example.com)`
2. 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.mdanchor)`
3. A link to an internal sphinx cross-reference, e.g. `[text](my-reference)`
an additional situation is now supported:
4. A link to a source file, which is not a document, e.g. `[text](file.js)`. This behaves similarly to the sphinx `download` 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](docs/syntax/cross-referencing.md) for more information.
‼️ 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](docs/syntax/optional.mdmath-shortcuts) for more information.
⬆️ Drop Python 3.6 support
MyST-Parser now supports, and is tested against, Python 3.7 to 3.10.
✨ 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](docs/syntax/optional.mdstrikethrough) for more information.
The `myst_gfm_only=True` configuration sets up specific configuration, to enable compliance only with [GitHub-flavored Markdown](https://github.github.com/gfm/), including enabling the `strikethrough`, `tasklist` and `linkify` extensions, but disabling support for roles and directives.
✨ 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:
md
---
title: My Title with *emphasis*
---
would be equivalent to:
md
My Title with *emphasis*
See [Front matter](docs/configuration.md) for more information.
👌 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#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 <gh-pr:474>
- 👌 IMPROVE: Add `bullet` attribute to `bullet_list` node in <gh-pr:465>
- 👌 IMPROVE: Use correct renderer for `state.inline_text` in <gh-pr:466>
- 👌 IMPROVE: Docutils parser settings in <gh-pr:476>
- 🐛 FIX: front-matter rendering with docutils in <gh-pr:477>
- 👌 IMPROVE: Code block highlighting in <gh-pr:478>
- 👌 IMPROVE: `note_refname` for docutils internal links in <gh-pr:481>
- 🐛 FIX: Ordered list starting number in <gh-pr:483>
- 👌 IMPROVE: Propagate enumerated list suffix in <gh-pr:484>
- 👌 IMPROVE: `DocutilsRenderer.create_highlighted_code_block` in <gh-pr:488>
- 🐛 FIX: Source line reporting for nested parsing in <gh-pr:490>
- 🔧 MAINTAIN: Implement `MockInliner.parse` in <gh-pr:504>
```
Links
- PyPI: https://pypi.org/project/myst-parser
- Changelog: https://data.safetycli.com/changelogs/myst-parser/
This PR updates myst-parser from 0.16.1 to 4.0.0.
Changelog
### 4.0.0 ``` This release bumps the supported versions of: - Python to ``3.10`` and greater - Sphinx 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 <gh-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](syntax/footnotes) for more information. **Full Changelog**: [v3.0.1...v4.0.0](https://github.com/executablebooks/MyST-Parser/compare/v3.0.1...v4.0.0) ``` ### 3.0.1 ``` 🐛 Bug Fixes - Account for the final directive option having an empty value, by <gh-user:chrisjsewell> in <gh-pr:924> - Re-allow indented directive option blocks, by <gh-user:chrisjsewell> in <gh-pr:925> **Full Changelog**: [v3.0.0...v3.0.1](https://github.com/executablebooks/MyST-Parser/compare/v3.0.0...v3.0.1) ``` ### 3.0.0 ``` Upgraded dependencies - ⬆️ Add support for Python 3.12 by <gh-user:hugovk> in <gh-pr:848> - ⬆️ Update docutils requirement from >=0.16,<0.21 to >=0.18,<0.22 by <gh-user:chrisjsewell> in <gh-pr:916> New features - ✨ Allow for use of the `line-block` directive by <gh-user:chrisjsewell> in <gh-pr:900> - ✨ Emits sphinx include-read event by <gh-user:sumezulike> in <gh-pr:887> Improvements - 👌 Nested parse attribution in `attr_block` by <gh-user:chrisjsewell> in <gh-pr:831> - 👌 Directive option parsing by <gh-user:chrisjsewell> in <gh-pr:796 - 👌 Improve directive parsing warnings by <gh-user:chrisjsewell> in <gh-pr:893> - 👌 Allow for opening external links in new tabs (856) by <gh-user:marjus45> in <gh-pr:857> Internal - 🔧 Replace black, isort, pyupgrade with ruff formatter by <gh-user:chrisjsewell> in <gh-pr:833> - 🔧 remove redundant mypy config by <gh-user:danieleades> in <gh-pr:866> - 🔧 Add additional Ruff lints (and fix issues) by <gh-user:danieleades> in <gh-pr:862> - 🔧 mypy- disallow 'any generics' by <gh-user:danieleades> in <gh-pr:865> - 🔧 Fix docutils deprecation in option parsing by <gh-user:agoose77> in <gh-pr:842> Documentation - 📚 Fix a broken link in configuration.md by <gh-user:zupo> in <gh-pr:907> - 📚 Add linkify dependency to contributing docs. by <gh-user:jhcole> in <gh-pr:792> - 📚 Fix the double `used` in docs/syntax/math.md by <gh-user:ice-tong> in <gh-pr:810> - 📚 Also add linkify to pip install command in README by <gh-user:n-peugnet> in <gh-pr:851> - 📚 Fix the code section title in live preview by <gh-user:BoboTiG> in <gh-pr:875> - 📚 Fix admonition example by <gh-user:72757373656c6c> in <gh-pr:904> - 📚 Fix url for jupyter book gallery by <gh-user:72757373656c6c> in <gh-pr:905> - 📚 Update theme version by <gh-user:chrisjsewell> in <gh-pr:918> - 📚 Fix typo by <gh-user:blakeNaccarato> in <gh-pr:911> - 📚 Fix architecture typo (855) by <gh-user:72757373656c6c> in <gh-pr:910> **Full Changelog**: [v2.0.0...v3.0.0](https://github.com/executablebooks/MyST-Parser/compare/v2.0.0...v3.0.0) ``` ### 2.0.0 ``` This release primarily updates core myst-parser dependencies, with some minor changes to parsing behaviour: * ⬆️ UPGRADE: `markdown-it-py` to v3 (<gh-pr:773>) * This is mainly a non-breaking change, fixing some edge cases in parsing * See: <https://github.com/executablebooks/markdown-it-py/releases/tag/v3.0.0> and <https://github.com/executablebooks/mdit-py-plugins/releases/tag/v0.4.0> * ⬆️ UPGRADE: `linkify-it-py` to v2 (<gh-pr:675>) * Also fixes some edge cases in parsing * See: <https://github.com/tsutsu3/linkify-it-py/blob/main/CHANGELOG.md> * ⬆️ UPGRADE: Add support for `docutils` v0.20 (<gh-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 (<gh-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 (<gh-pr:772>) * 👌 Improve default slug generation for heading anchors, thanks to <gh-user:Cimbali> (<gh-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 not `a-b-c` * 👌 IMPROVE: Substitution extension (<gh-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 <gh-user:webknjaz> (<gh-pr:635>) **Full Changelog**: [v1.0.0...v2.0.0](https://github.com/executablebooks/MyST-Parser/compare/v1.0.0...v2.0.0) ``` ### 1.0 ``` This release updates the code-base to fully support the [markdown-it-py](https://markdown-it-py.readthedocs.io) `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](https://github.github.com/gfm/#tables-extension-). New Features ✨ - **Task lists** utilise the [markdown-it-py tasklists plugin](inv:markdown_itmd/plugins), and are applied to Markdown list items starting with `[ ]` or `[x]`. markdown - [ ] 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](docs/syntax/optional.mdtask-lists) 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` and `wordcount-minutes`, computed by the markdown-it-py [`wordcount_plugin`](https://github.com/executablebooks/mdit-py-plugins/pull/20). markdown > {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read See [the roles syntax guide](docs/syntax/roles-and-directives.md) for further information. - The **`dmath_double_inline`** configuration option allows display math (i.e. `$$`) within an inline context. See [the math syntax guide](docs/syntax/optional.mdmath-shortcuts) for further information. 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}` Fix extraction of nested footnotes 🐛 Previously footnote definitions in block elements like lists would crash the parsing: markdown - [^e]: footnote definition in a block element These are now correctly extracted. ``` ### 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 😄 ``` ### 0.19.2 ``` ✨ NEW: Add myst_fence_as_directive config (<gh-pr:742>) Setting the following config, for example: python 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: `markdown {caption="My caption"} {alt="HTML alt" align=center} mermaid graph LR a --> b ` and have interoperable rendering with tools like GitHub. 🎉 New contributors: - 📚 Add `html_last_updated_fmt = ""` to conf.py to fix documentation footer, thanks to <gh-user:jeanas> (<gh-pr:691>) - 📚 Fix the sphinx-design example, thanks to <gh-user:recfab> (<gh-pr:738>) ``` ### 0.19.1 ``` 🐛 FIX `NoURI` error in doc reference resolution, for texinfo builds (<gh-pr:734>) ``` ### 0.19.0 ``` This release brings a number of exciting new features, improvements, and upgrades 🎉 Full Changelog: [v0.18.1...v0.19.0](https://github.com/executablebooks/MyST-Parser/compare/v0.18.1...v0.19.0) 📚 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](https://pyscript.readthedocs.io/), <gh-pr:717>). The code base API is also now fully documented by [sphinx-autodoc2](https://sphinx-autodoc2.readthedocs.io/), which even allows for MyST docstrings! (<gh-pr:704>). ⬆️ 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 (<gh-pr:664>) 📄 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 (<gh-pr:655>) - `myst_meta_html` and `myst_substitutions` options are now supported (<gh-pr:672>) - `myst_heading_anchors` option is now supported (<gh-pr:678>) - Math block labels syntax is now supported (<gh-pr:668>) - Missing directive/role errors errors are now suppressable warnings (<gh-pr:687>) - Non-fatal directive parsing errors are now suppressable warnings (<gh-pr:682>) - Most of the extended markdown syntax below is also supported 🔗 Extended Markdown links See the [Extended Markdown links](docs/syntax/cross-referencing.md) 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:typetarget)` 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 option - The `myst-inv` CLI makes it easy to find the correct inventory target :::{tip} It is advised (although not immediately necessary) to prefix all internal references with ``. For example, `[...](my-reference)`, should be changed to `[...](my-reference)`. ::: `{}` Attributes syntax The [`attrs_inline` and `attrs_block`](docs/syntax/optional.mdattributes) 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: `{id .class width=100px}` - Text spans: `[some text]{id .class}` A paragraph block can have attributes too: markdown {id .class} This is a paragraph with an id and class A code fence can be given line numbers and line emphasis: `markdown {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: markdown {.glossary} term name : Definition of the term Quote blocks can be given an attribution: markdown {attribution="Chris Sewell"} > My quote 👌 Miscellaneous improvements - Nested headings (e.g. inside directives) are now allowed in MyST and are correctly rendered in HTML (<gh-pr:711>) - The `colon_fence` extension now renders internal content as MyST, rather than as a code block (<gh-pr:713>) - The `include` directive in MyST documents now supports a `:heading-offset:` option, to offset the heading levels in the included document - The `myst_heading_slug_func` option now supports setting a `str` which points to a fully qualified function name, e.g. `"module.path.func"` (<gh-pr:696>) - The `myst_enable_checkboxes` option allows for task list checkboxes to be enabled/disabled (<gh-pr:686>) Additional contributions - 🐛 FIX: Remove unnecessary assert in <gh-pr:659>, thanks to <gh-user:n-peugnet> - 🔧 ci(deps): setup dependabot (<gh-pr:669>), thanks to <gh-user:mmorel-35> - 🔧: Depend on typing_extensions only on `Python<3.8` in <gh-pr:642>, thanks to <gh-user:hukkin> ``` ### 0.18.1 ``` Full Changelog: [v0.18.0...v0.18.1](https://github.com/executablebooks/MyST-Parser/compare/v0.18.0...v0.18.1) - ⬆️ UPGRADE: docutils 0.19 support in <gh-pr:611> - ✨ NEW: Add `attrs_image` (experimental) extension in <gh-pr:620> - e.g. `{id .class width=100px}` - See: [Optional syntax section](docs/syntax/optional.md) - **Important**: This is an experimental extension, and may change in future releases ``` ### 0.18.0 ``` Full Changelog: [v0.17.2...v0.18.0](https://github.com/executablebooks/MyST-Parser/compare/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](docs/configuration.md) section for more information. 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 [](docs/docutils.md)), and for testing, functionality has been moved to <https://github.com/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. yaml --- html_meta: "description lang=en": "metadata description" substitutions: key1: I'm a **substitution** --- is replaced by: yaml --- myst: html_meta: "description lang=en": "metadata description" substitutions: key1: I'm a **substitution** --- Key PRs - ♻️📚 Restructure code base and documentation (<gh-pr:566>) - ⬆️ Drop Sphinx 3 and add Sphinx 5 support (<gh-pr:579>) - 🐛 FIX: `parse_directive_text` when body followed by options (<gh-pr:580>) - 🐛 FIX: floor table column widths to integers (<gh-pr:568>), thanks to <gh-user:Jean-Abou-Samra>! ``` ### 0.17.2 ``` Full Changelog: [v0.17.1...v0.17.2](https://github.com/executablebooks/MyST-Parser/compare/v0.17.1...v0.17.2) - ♻️ REFACTOR: Replace `attrs` by `dataclasses` for configuration (<gh-pr:557>) ``` ### 0.17.1 ``` Full Changelog: [v0.17.0...v0.17.1](https://github.com/executablebooks/MyST-Parser/compare/v0.17.0...v0.17.1) - 🐛 FIX: Heading anchor resolution for parallel builds (<gh-pr:525>) - 🔧 MAINTAIN: Move packaging from setuptools to flit (<gh-pr:553>) - 🔧 MAINTAIN: Directly specify attrs dependency (<gh-pr:555>) ``` ### 0.17.0 ``` This release contains a number of breaking improvements. Full Changelog: [v0.16.1...v0.17.0](https://github.com/executablebooks/MyST-Parser/compare/v0.16.1...v0.17.0) ‼️ 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](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors) 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: 1. A link to an external resource, e.g. `[text](http://example.com)` 2. 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.mdanchor)` 3. A link to an internal sphinx cross-reference, e.g. `[text](my-reference)` an additional situation is now supported: 4. A link to a source file, which is not a document, e.g. `[text](file.js)`. This behaves similarly to the sphinx `download` 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](docs/syntax/cross-referencing.md) for more information. ‼️ 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](docs/syntax/optional.mdmath-shortcuts) for more information. ⬆️ Drop Python 3.6 support MyST-Parser now supports, and is tested against, Python 3.7 to 3.10. ✨ 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](docs/syntax/optional.mdstrikethrough) for more information. The `myst_gfm_only=True` configuration sets up specific configuration, to enable compliance only with [GitHub-flavored Markdown](https://github.github.com/gfm/), including enabling the `strikethrough`, `tasklist` and `linkify` extensions, but disabling support for roles and directives. ✨ 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: md --- title: My Title with *emphasis* --- would be equivalent to: md My Title with *emphasis* See [Front matter](docs/configuration.md) for more information. 👌 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](https://docutils.sourceforge.io/docs/ref/rst/directives.html#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 <gh-pr:474> - 👌 IMPROVE: Add `bullet` attribute to `bullet_list` node in <gh-pr:465> - 👌 IMPROVE: Use correct renderer for `state.inline_text` in <gh-pr:466> - 👌 IMPROVE: Docutils parser settings in <gh-pr:476> - 🐛 FIX: front-matter rendering with docutils in <gh-pr:477> - 👌 IMPROVE: Code block highlighting in <gh-pr:478> - 👌 IMPROVE: `note_refname` for docutils internal links in <gh-pr:481> - 🐛 FIX: Ordered list starting number in <gh-pr:483> - 👌 IMPROVE: Propagate enumerated list suffix in <gh-pr:484> - 👌 IMPROVE: `DocutilsRenderer.create_highlighted_code_block` in <gh-pr:488> - 🐛 FIX: Source line reporting for nested parsing in <gh-pr:490> - 🔧 MAINTAIN: Implement `MockInliner.parse` in <gh-pr:504> ```Links
- PyPI: https://pypi.org/project/myst-parser - Changelog: https://data.safetycli.com/changelogs/myst-parser/