Adding upstream version 0.18.1.upstream/0.18.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 728 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..0fe72f4
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,728 @@
+# Changelog
+
+## 0.18.1 - 2022-27-09
+
+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 (#611)
+- ✨ NEW: Add `attrs_image` (experimental) extension (#620)
+  - e.g. `![image](image.png){#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 - 2022-06-07
+
+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 top-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` top-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 (#566)
+- ⬆️ Drop Sphinx 3 and add Sphinx 5 support (#579)
+- 🐛 FIX: `parse_directive_text` when body followed by options (#580)
+- 🐛 FIX: floor table column widths to integers (#568), thanks to @Jean-Abou-Samra!
+
+## 0.17.2 - 2022-04-17
+
+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 (#557)
+
+## 0.17.1 - 2022-04-15
+
+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 (#525)
+- 🔧 MAINTAIN: Move packaging from setuptools to flit (#553)
+- 🔧 MAINTAIN: Directly specify attrs dependency (#555)
+
+## 0.17.0 - 2022-02-11
+
+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.md#anchor)`
+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/syntax.md#markdown-links-and-referencing) 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.md#math-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.md#strikethrough) 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/syntax/syntax.md#front-matter) 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 [#474](https://github.com/executablebooks/MyST-Parser/pull/474)
+- 👌 IMPROVE: Add `bullet` attribute to `bullet_list` node in [#465](https://github.com/executablebooks/MyST-Parser/pull/465)
+- 👌 IMPROVE: Use correct renderer for `state.inline_text` in [#466](https://github.com/executablebooks/MyST-Parser/pull/466)
+- 👌 IMPROVE: Docutils parser settings in [#476](https://github.com/executablebooks/MyST-Parser/pull/476)
+- 🐛 FIX: front-matter rendering with docutils in [#477](https://github.com/executablebooks/MyST-Parser/pull/477)
+- 👌 IMPROVE: Code block highlighting in [#478](https://github.com/executablebooks/MyST-Parser/pull/478)
+- 👌 IMPROVE: `note_refname` for docutils internal links in [#481](https://github.com/executablebooks/MyST-Parser/pull/481)
+- 🐛 FIX: Ordered list starting number in [#483](https://github.com/executablebooks/MyST-Parser/pull/483)
+- 👌 IMPROVE: Propagate enumerated list suffix in [#484](https://github.com/executablebooks/MyST-Parser/pull/484)
+- 👌 IMPROVE: `DocutilsRenderer.create_highlighted_code_block` in [#488](https://github.com/executablebooks/MyST-Parser/pull/488)
+- 🐛 FIX: Source line reporting for nested parsing in [#490](https://github.com/executablebooks/MyST-Parser/pull/490)
+- 🔧 MAINTAIN: Implement `MockInliner.parse` in [#504](https://github.com/executablebooks/MyST-Parser/pull/504)
+
+## 0.16.1 - 2021-12-16
+
+✨ NEW: Add `myst_linkify_fuzzy_links` option.
+When using the [`linkify` extension](docs/syntax/optional.md#linkify), this option can be used to disable matching of links that do not contain a schema (such as `http://`).
+
+## 0.16.0 - 2021-12-06
+
+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 [@cpitclaudel](https://github.com/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.md#field-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/syntax.md#tables) for more information.
+
+### Pull Requests
+
+- 🐛 FIX: Add mandatory attributes on `enumerated_list` by @cpitclaudel in [#418](https://github.com/executablebooks/MyST-Parser/pull/418)
+- 📚 DOCS: Add reference to MySTyc in landing page by @astrojuanlu in [#413](https://github.com/executablebooks/MyST-Parser/pull/413)
+- ⬆️ UPGRADE: markdown-it-py v2, mdit-py-plugins v0.3 by @chrisjsewell in [#449](https://github.com/executablebooks/MyST-Parser/pull/449)
+- 👌 IMPROVE: Table rendering by @chrisjsewell in [#450](https://github.com/executablebooks/MyST-Parser/pull/450)
+- 🐛 FIX: Ensure parent files are re-built if `include` file changes by @chrisjsewell in [#451](https://github.com/executablebooks/MyST-Parser/pull/451)
+- 🐛 FIX: Convert empty directive option to `None` by @chrisjsewell in [#452](https://github.com/executablebooks/MyST-Parser/pull/452)
+- 👌 IMPROVE: Add `\\` for hard-breaks in latex by @chrisjsewell in [#453](https://github.com/executablebooks/MyST-Parser/pull/453)
+- 🔧 MAINTAIN: Remove empty "sphinx" extra by @hukkin in [#350](https://github.com/executablebooks/MyST-Parser/pull/350)
+- ✨ NEW: Add `fieldlist` extension by @chrisjsewell in [#455](https://github.com/executablebooks/MyST-Parser/pull/455)
+- ✨ NEW: Add Docutils MyST config and CLI by @cpitclaudel in [#426](https://github.com/executablebooks/MyST-Parser/pull/426)
+- 🔧 MAINTAIN: Add publishing job for `myst-docutils` by @chrisjsewell in [#456](https://github.com/executablebooks/MyST-Parser/pull/456)
+- 🧪 TESTS: Add for `gettext_additional_targets` by @jpmckinney in [#459](https://github.com/executablebooks/MyST-Parser/pull/459)
+
+### New Contributors
+
+- @cpitclaudel made their first contribution in [#418](https://github.com/executablebooks/MyST-Parser/pull/418)
+- @astrojuanlu made their first contribution in [#413](https://github.com/executablebooks/MyST-Parser/pull/413)
+
+**Full Changelog**: <https://github.com/executablebooks/MyST-Parser/compare/v0.15.2...v0.16.0>
+
+## 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.
+
+## 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"]`.
+
+## 0.15.0 - 2021-06-13
+
+### 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`.
+
+### 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](docs/syntax/optional.md#math-shortcuts) for further information.
+
+### 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.
+
+### Added `myst_heading_slug_func` option 👌
+
+Use this option to specify a custom function to auto-generate heading anchors (see [Auto-generated header anchors](docs/syntax/optional.md#auto-generated-header-anchors)).
+
+Thanks to [@jpmckinney](https://github.com/jpmckinney)!
+
+## 0.14.0 - 2021-05-04
+
+### Upgrade to `markdown-it-py` v1.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](markdown_it:md/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.md#task-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/syntax.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.md#math-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.
+
+## 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:
+
+````markdown
+```{note}
+# Unsupported Header
+```
+````
+
+A warning (of type `myst.nested_header`) is now emitted when this occurs.
+
+🔧 MAINTAIN: Python 3.9 is now officially supported.
+
+## 0.13.6 - 2021-04-10
+
+🐛 FIX: docutils `v0.17` compatibility
+
+## 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 the `gettext` builder, to generate translation POT templates.
+  Thanks to [@jpmckinney](https://github.com/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 sphinx `suppress_warnings` config option.
+  See [How-to suppress warnings](howto/warnings) for more information.
+
+## 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
+
+## 0.13.2 - 2021-01-20
+
+✨ 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:
+  ```html
+  <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](docs/syntax/optional.md) 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](docs/syntax/syntax.md) 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)
+
+## 0.13.1 - 2020-12-31
+
+👌 Directives can now be used for inline substitutions, e.g.
+
+```md
+---
+substitutions:
+  key: |
+    ```{image} img/fun-fish.png
+    :alt: fishy
+    :height: 20px
+    ```
+---
+
+An inline image: {{ key }}
+```
+
+## 0.13.0 - 2020-12-18
+
+This release makes some major updates to the optional syntaxes.
+For full details see [Optional MyST Syntaxes](docs/syntax/optional.md).
+
+### 🗑 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:
+
+```md
+:::{admonition} The title
+:class: note
+
+This note contains *Markdown*
+:::
+```
+
+### ✨ 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](https://github.com/tsutsu3/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:
+
+```md
+---
+substitutions:
+  key1: definition
+---
+{{ key1 }}
+```
+
+The substitutions are assessed as [jinja2 expressions](http://jinja.palletsprojects.com/) and includes the [Sphinx Environment](https://www.sphinx-doc.org/en/master/extdev/envapi.html) 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):
+
+```md
+:::{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**
+:::
+```
+
+### 👌 Improvements
+
+Using the `html_image` extension, HTML images are now processed for both blocks and (now) inline.
+
+So you can correctly do, for example:
+
+```md
+I’m an inline image: <img src="img/fun-fish.png" height="20px">
+
+| table column                              |
+| ----------------------------------------- |
+| <img src="img/fun-fish.png" width="20px"> |
+```
+
+## 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 [#253](https://github.com/executablebooks/MyST-Parser/pull/253)
+
+## 0.12.9 - 2020-09-08
+
+✨ 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](https://github.com/Flet/github-slugger)); 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).
+
+  See [the documentation here](docs/syntax/optional.md#auto-generated-header-anchors).
+
+🐛 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.
+
+## 0.12.7 - 2020-08-31
+
+✨ NEW: Want to include your README.md in the documentation?
+: See [including a file from outside the docs folder](howto/include-readme).
+
+(👌 added `relative-docs` option in 0.12.8)
+
+## 0.12.5 - 2020-08-28
+
+✨ 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](docs/syntax/optional.md#markdown-figures) for details.
+
+(👌 formatting of caption improved in 0.12.6)
+
+## 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
+
+## 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.
+
+```md
+Term 1
+: Definition
+```
+
+See the [Definition Lists documentation](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists) 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](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#mathjax-and-math-parsing) for further details.
+
+## 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](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#how-directives-parse-content) for further explanation.
+
+  In particular, this addition solves some outstanding user requests:
+
+  - How-to [include rST files into a Markdown file](https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-rst-files-into-a-markdown-file)
+  - How-to [Use sphinx.ext.autodoc in Markdown files](https://myst-parser.readthedocs.io/en/latest/using/howto.html#use-sphinx-ext-autodoc-in-markdown-files)
+
+  Thanks to [@stephenroller](https://github.com/stephenroller) for the contribution 🎉
+
+## 0.12.1 - 2020-08-19
+
+✨ NEW: Add `myst_commonmark_only` config option, for restricting the parser to strict CommonMark (no extensions).
+
+## 0.12.0 - 2020-08-19
+
+### ‼️ BREAKING
+
+If you are using math in your documents, be sure to read the updated [Math syntax guide](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#math-shortcuts)!
+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](https://github.com/executablebooks/MyST-Parser/commit/98573b9c6e3602ab31d627b5266ae5c1ba2c9e5f)).
+
+### Improved 👌
+
+More configuration options for math parsing (see [MyST configuration options](https://myst-parser.readthedocs.io/en/latest/using/intro.html#myst-configuration-options)).
+
+## 0.11.2 - 2020-07-13
+
+### Added ✨
+
+- `<img src="file.png" width="200px">` tag parsing to sphinx representation, see [the image syntax guide](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#images)
+
+### Improved 👌
+
+- `[title](link)` syntax now works with intersphinx references.
+  Recognised URI schemas can also be configured, see the [configuration options](https://myst-parser.readthedocs.io/en/latest/using/intro.html#myst-configuration-options)
+
+## 0.11.1 - 2020-07-12
+
+### Fix
+
+- Correctly pin required minimum markdown-it-py version
+
+## 0.11.0 - 2020-07-12
+
+### Added ✨
+
+* Special admonition directive syntax (optional):
+
+  ```md
+  :::{note}
+  This text is **standard** _Markdown_
+  :::
+  ```
+
+  See [the syntax guide section](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#admonition-directives-special-syntax-optional) for details.
+
+* Direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations (optional).
+  See [the syntax guide section](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#direct-latex-math-optional) for details.
+
+### Breaking ‼️
+
+* Sphinx configuration options are now set as separate variables, rather than a single dict.
+  See [MyST configuration options](https://myst-parser.readthedocs.io/en/latest/using/intro.html#myst-configuration-options) for details.
+
+## 0.10.0 - 2020-07-08
+
+([full changelog](https://github.com/executablebooks/MyST-Parser/compare/v0.9.1...aaed58808af485c29bbbf73c5aac10697bfa08b9))
+
+### Improved 👌
+
+* Support Sphinx version 3 [#197](https://github.com/executablebooks/MyST-Parser/pull/197) ([@chrisjsewell](https://github.com/chrisjsewell))
+* Update Trove Classifiers [#192](https://github.com/executablebooks/MyST-Parser/pull/192) ([@chrisjsewell](https://github.com/chrisjsewell))
+* Add functionality to use docutils specialized role [#189](https://github.com/executablebooks/MyST-Parser/pull/189) ([@chrisjsewell](https://github.com/chrisjsewell))
+
+### Contributors to this release
+
+([GitHub contributors page for this release](https://github.com/executablebooks/MyST-Parser/graphs/contributors?from=2020-07-20&to=2020-08-07&type=c))
+
+[@AakashGfude](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3AAakashGfude+updated%3A2020-07-20..2020-08-07&type=Issues) | [@asmeurer](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Aasmeurer+updated%3A2020-07-20..2020-08-07&type=Issues) | [@choldgraf](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Acholdgraf+updated%3A2020-07-20..2020-08-07&type=Issues) | [@chrisjsewell](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Achrisjsewell+updated%3A2020-07-20..2020-08-07&type=Issues) | [@codecov](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Acodecov+updated%3A2020-07-20..2020-08-07&type=Issues) | [@webknjaz](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Awebknjaz+updated%3A2020-07-20..2020-08-07&type=Issues) | [@welcome](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Awelcome+updated%3A2020-07-20..2020-08-07&type=Issues)
+
+## Past Releases
+
+### Contributors
+
+([GitHub contributors page for these releases](https://github.com/executablebooks/MyST-Parser/graphs/contributors?from=2020-01-01&to=2020-07-20&type=c))
+
+[@akhmerov](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Aakhmerov+updated%3A2020-01-01..2020-07-20&type=Issues) | [@asmeurer](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Aasmeurer+updated%3A2020-01-01..2020-07-20&type=Issues) | [@certik](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Acertik+updated%3A2020-01-01..2020-07-20&type=Issues) | [@choldgraf](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Acholdgraf+updated%3A2020-01-01..2020-07-20&type=Issues) | [@chrisjsewell](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Achrisjsewell+updated%3A2020-01-01..2020-07-20&type=Issues) | [@codecov](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Acodecov+updated%3A2020-01-01..2020-07-20&type=Issues) | [@dhermes](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Adhermes+updated%3A2020-01-01..2020-07-20&type=Issues) | [@filippo82](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Afilippo82+updated%3A2020-01-01..2020-07-20&type=Issues) | [@jlperla](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Ajlperla+updated%3A2020-01-01..2020-07-20&type=Issues) | [@jstac](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Ajstac+updated%3A2020-01-01..2020-07-20&type=Issues) | [@martinagvilas](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Amartinagvilas+updated%3A2020-01-01..2020-07-20&type=Issues) | [@mlncn](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Amlncn+updated%3A2020-01-01..2020-07-20&type=Issues) | [@mmcky](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Ammcky+updated%3A2020-01-01..2020-07-20&type=Issues) | [@moorepants](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Amoorepants+updated%3A2020-01-01..2020-07-20&type=Issues) | [@najuzilu](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Anajuzilu+updated%3A2020-01-01..2020-07-20&type=Issues) | [@nathancarter](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Anathancarter+updated%3A2020-01-01..2020-07-20&type=Issues) | [@pauleveritt](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Apauleveritt+updated%3A2020-01-01..2020-07-20&type=Issues) | [@phaustin](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Aphaustin+updated%3A2020-01-01..2020-07-20&type=Issues) | [@rossbar](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Arossbar+updated%3A2020-01-01..2020-07-20&type=Issues) | [@rowanc1](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Arowanc1+updated%3A2020-01-01..2020-07-20&type=Issues) | [@sbliven](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Asbliven+updated%3A2020-01-01..2020-07-20&type=Issues) | [@webknjaz](https://github.com/search?q=repo%3Aexecutablebooks%2FMyST-Parser+involves%3Awebknjaz+updated%3A2020-01-01..2020-07-20&type=Issues)