From 943e3dc057eca53e68ddec51529bd6a1279ebd8e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 29 Apr 2024 06:23:02 +0200 Subject: Adding upstream version 0.18.1. Signed-off-by: Daniel Baumann --- CHANGELOG.md | 728 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 728 insertions(+) create mode 100644 CHANGELOG.md (limited to 'CHANGELOG.md') 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 . + +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 ) + +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 + + + + + + + + + + + + + + + +

left

center

right

a

b

c

+``` + +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**: + +## 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 `
` HTML blocks to sphinx admonitions. +: This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks. +: For example: + ```html +
+

This is the **title**

+ This is the *content* +
+ ``` +: 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 `
` 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 + +fishy + +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: + +| table column | +| ----------------------------------------- | +| | +``` + +## 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 ✨ + +- `` 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) -- cgit v1.2.3