Myst-parser

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>)

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>

✨ NEW: Add `myst_linkify_fuzzy_links` option.
When using the [`linkify` extension](docs/syntax/optional.mdlinkify), this option can be used to disable matching of links that do not contain a schema (such as `http://`).

This release contains a number of exciting improvements:

Upgrade of Markdown parser

`markdown-it-py` has been upgraded to [v2.0.0](https://github.com/executablebooks/markdown-it-py/releases/tag/v2.0.0).
This upgrade brings full compliance with the [CommonMark v0.30 specification](https://spec.commonmark.org/0.30/).

Additionally, `mdit-py-plugins` has been upgraded to [v0.3.0](https://github.com/executablebooks/mdit-py-plugins/releases/tag/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:

md
(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:

md
{abc}`xy
new line`


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 HTML
- `myst-docutils-html5`: converts MyST to HTML5
- `myst-docutils-latex`: converts MyST to LaTeX
- `myst-docutils-xml`: converts MyST to docutils-native XML
- `myst-docutils-pseudoxml`: converts MyST to pseudo-XML (to visualise the AST structure)

You can also install the [myst-docutils](https://pypi.org/project/myst-docutils/) package from `pip`,
which includes no direct install requirements on docutils or sphinx.

See [MyST with Docutils](docs/docutils.md) for more information.

Thanks to help from <gh-user:cpitclaudel>!

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.

md
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_


Addition of the `fieldlist` syntax extension

Field lists are mappings from field names to field bodies, based on the [reStructureText syntax](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists):

rst
:name only:
:name: body
:name:
Multiple

Paragraphs


This should eventually allow for MyST Markdown docstrings! (see <https://github.com/executablebooks/MyST-Parser/issues/228>)

See [Field Lists syntax](docs/syntax/optional.mdfield-lists) for more information.

Improvements to table rendering

Tables with no body are now allowed, for example:

md
| abc | def |
| --- | --- |


Also cell alignment HTML classes have now been changed to: `text-left`, `text-center`, or `text-right`, for example:

md
| left | center | right |
| :--- | :----: | ----: |
| a | b | c |


is converted to:

html
<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](docs/syntax/tables.md) for more information.

Pull Requests

- 🐛 FIX: Add mandatory attributes on `enumerated_list` by <gh-user:cpitclaudel> in <gh-pr:418>
- 📚 DOCS: Add reference to MySTyc in landing page by <gh-user:astrojuanlu> in <gh-pr:413>
- ⬆️ UPGRADE: markdown-it-py v2, mdit-py-plugins v0.3 by <gh-user:chrisjsewell> in <gh-pr:449>
- 👌 IMPROVE: Table rendering by <gh-user:chrisjsewell> in <gh-pr:450>
- 🐛 FIX: Ensure parent files are re-built if `include` file changes by <gh-user:chrisjsewell> in <gh-pr:451>
- 🐛 FIX: Convert empty directive option to `None` by <gh-user:chrisjsewell> in <gh-pr:452>
- 👌 IMPROVE: Add `\\` for hard-breaks in latex by <gh-user:chrisjsewell> in <gh-pr:453>
- 🔧 MAINTAIN: Remove empty "sphinx" extra by <gh-user:hukkin> in <gh-pr:350>
- ✨ NEW: Add `fieldlist` extension by <gh-user:chrisjsewell> in <gh-pr:455>
- ✨ NEW: Add Docutils MyST config and CLI by <gh-user:cpitclaudel> in <gh-pr:426>
- 🔧 MAINTAIN: Add publishing job for `myst-docutils` by <gh-user:chrisjsewell> in <gh-pr:456>
- 🧪 TESTS: Add for `gettext_additional_targets` by <gh-user:jpmckinney> in <gh-pr:459>

New Contributors

- <gh-user:cpitclaudel> made their first contribution in <gh-pr:418>
- <gh-user:astrojuanlu> made their first contribution in <gh-pr:413>

**Full Changelog**: <https://github.com/executablebooks/MyST-Parser/compare/v0.15.2...v0.16.0>

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.

👌 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"]`.