.github/workflows/tests.yml

@@ -70,7 +70,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        docutils-version: ["0.16", "0.17", "0.18"]
+        docutils-version: ["0.17", "0.18", "0.19"]
 
     steps:
     - name: Checkout source

.pre-commit-config.yaml

@@ -12,15 +12,15 @@ exclude: >
 repos:
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.2.0
+    rev: v4.3.0
     hooks:
     - id: check-json
     - id: check-yaml
     - id: end-of-file-fixer
     - id: trailing-whitespace
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.34.0
+    rev: v2.38.2
     hooks:
     - id: pyupgrade
       args: [--py37-plus]
@@ -31,12 +31,12 @@ repos:
     - id: isort
 
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.8.0
     hooks:
     - id: black
 
   - repo: https://github.com/PyCQA/flake8
-    rev: 4.0.1
+    rev: 5.0.4
     hooks:
     - id: flake8
       additional_dependencies:
@@ -45,14 +45,14 @@ repos:
         # - flake8-self~=0.2.2
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.961
+    rev: v0.971
     hooks:
     - id: mypy
       args: [--config-file=pyproject.toml]
       additional_dependencies:
       - sphinx~=5.0
       - markdown-it-py>=1.0.0,<3.0.0
-      - mdit-py-plugins~=0.3.0
+      - mdit-py-plugins~=0.3.1
       files: >
         (?x)^(
             myst_parser/.*py|

CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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)

docs/conf.py

@@ -90,6 +90,7 @@
     "strikethrough",
     "substitution",
     "tasklist",
+    "attrs_image",
 ]
 myst_number_code_blocks = ["typescript"]
 myst_heading_anchors = 2

docs/develop/contributing.md

@@ -49,7 +49,7 @@ All functions and class methods should be annotated with types and include a doc
 
 ## Testing
 
-For code tests, myst-parser uses [pytest](https://docs.pytest.org)):
+For code tests, myst-parser uses [pytest](https://docs.pytest.org):
 
 ```shell
 >> cd MyST-Parser

docs/index.md

@@ -89,15 +89,15 @@ to modify parsing behaviour and access extended syntax features.
 : For MyST extended syntax highlighting and authoring tools.
 
 [Convert existing ReStructuredText files to Markdown][rst-to-myst]
-: Use the [rst-to-myst] CLI or [the MySTyc interactive web interface](https://mystyc.herokuapp.com)
+: Use the [rst-to-myst] CLI or [the MySTyc interactive web interface](https://astrojuanlu.github.io/mystyc/).
 
 [MyST-NB](https://myst-nb.readthedocs.io)
 : A Sphinx and Docutils extension for compiling Jupyter Notebooks into high quality documentation formats, built on top of the MyST-Parser.
 
 [Jupyter Book](https://jupyterbook.org)
 : An open source project for building beautiful, publication-quality books and documents from computational material, built on top of the MyST-Parser and MyST-NB.
 
-[The Jupyter Book gallery](https://gallery.jupyterbook.org)
+[The Jupyter Book gallery](https://executablebooks.org/en/latest/gallery.html)
 : Examples of documents built with MyST.
 
 [Javascript MyST parser][mystjs]

docs/intro.md

@@ -171,7 +171,7 @@ myst:
 
 The other way to extend MyST in Sphinx is to install Sphinx extensions that define new roles, directives, etc.
 
-For example, let's install the `sphinxcontib.mermaid` extension,
+For example, let's install the `sphinxcontrib.mermaid` extension,
 which will allow us to generate [Mermaid diagrams](https://mermaid-js.github.io/mermaid/#/) with MyST.
 
 First, install `sphinxcontrib.mermaid`:

docs/syntax/optional.md

@@ -786,6 +786,42 @@ HTML image can also be used inline!
 
 I'm an inline image: <img src="img/fun-fish.png" height="20px">
 
+### Inline attributes
+
+:::{warning}
+This extension is currently experimental, and may change in future versions.
+:::
+
+By adding `"attrs_image"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+you can enable parsing of inline attributes for images.
+
+For example, the following Markdown:
+
+```md
+![image attrs](img/fun-fish.png){#imgattr .bg-primary width="100px" align=center}
+
+{ref}`a reference to the image <imgattr>`
+```
+
+will be parsed as:
+
+![image attrs](img/fun-fish.png){#imgattr .bg-primary width="100px" align=center}
+
+{ref}`a reference to the image <imgattr>`
+
+Inside the curly braces, the following syntax is possible:
+
+- `.foo` specifies `foo` as a class.
+  Multiple classes may be given in this way; they will be combined.
+- `#foo` specifies `foo` as an identifier.
+  An element may have only one identifier;
+  if multiple identifiers are given, the last one is used.
+- `key="value"` or `key=value` specifies a key-value attribute.
+    Quotes are not needed when the value consists entirely of
+    ASCII alphanumeric characters or `_` or `:` or `-`.
+    Backslash escapes may be used inside quoted values.
+- `%` begins a comment, which ends with the next `%` or the end of the attribute (`}`).
+
 (syntax/figures)=
 
 ## Markdown Figures

docs/syntax/syntax.md

@@ -464,14 +464,14 @@ A longer footnote definition.[^mylongdef]
 
     - even other block elements
 
-    Plus any preceding unindented lines,
+    Plus any subsequent unindented lines,
 that are not separated by a blank line
 
 This is not part of the footnote.
 
 ````{important}
 Although footnote references can be used just fine within directives, e.g.[^myref],
-it it recommended that footnote definitions are not set within directives,
+it is recommended that footnote definitions are not set within directives,
 unless they will only be referenced within that same directive:
 
 ```md

myst_parser/__init__.py

@@ -1,5 +1,5 @@
 """An extended commonmark compliant parser, with bridges to docutils & sphinx."""
-__version__ = "0.18.0"
+__version__ = "0.18.1"
 
 
 def setup(app):

myst_parser/cli.py

@@ -13,14 +13,14 @@ def print_anchors(args=None):
     arg_parser.add_argument(
         "input",
         nargs="?",
-        type=argparse.FileType("r"),
+        type=argparse.FileType("r", encoding="utf8"),
         default=sys.stdin,
         help="Input file (default stdin)",
     )
     arg_parser.add_argument(
         "-o",
         "--output",
-        type=argparse.FileType("w"),
+        type=argparse.FileType("w", encoding="utf8"),
         default=sys.stdout,
         help="Output file (default stdout)",
     )

myst_parser/config/main.py

@@ -31,6 +31,7 @@ def check_extensions(_, __, value):
     diff = set(value).difference(
         [
             "amsmath",
+            "attrs_image",
             "colon_fence",
             "deflist",
             "dollarmath",

myst_parser/mdit_to_docutils/base.py

@@ -381,7 +381,7 @@ def add_line_and_source_path_r(
         """
         for node in nodes:
             self.add_line_and_source_path(node, token)
-            for child in node.traverse():
+            for child in findall(node)():
                 self.add_line_and_source_path(child, token)
 
     def update_section_level_state(self, section: nodes.section, level: int) -> None:
@@ -785,6 +785,51 @@ def render_image(self, token: SyntaxTreeNode) -> None:
         title = token.attrGet("title")
         if title:
             img_node["title"] = token.attrGet("title")
+
+        # apply other attributes that can be set on the image
+        if "class" in token.attrs:
+            img_node["classes"].extend(str(token.attrs["class"]).split())
+        if "width" in token.attrs:
+            try:
+                width = directives.length_or_percentage_or_unitless(
+                    str(token.attrs["width"])
+                )
+            except ValueError:
+                self.create_warning(
+                    f"Invalid width value for image: {token.attrs['width']!r}",
+                    line=token_line(token, default=0),
+                    subtype="image",
+                    append_to=self.current_node,
+                )
+            else:
+                img_node["width"] = width
+        if "height" in token.attrs:
+            try:
+                height = directives.length_or_unitless(str(token.attrs["height"]))
+            except ValueError:
+                self.create_warning(
+                    f"Invalid height value for image: {token.attrs['height']!r}",
+                    line=token_line(token, default=0),
+                    subtype="image",
+                    append_to=self.current_node,
+                )
+            else:
+                img_node["height"] = height
+        if "align" in token.attrs:
+            if token.attrs["align"] not in ("left", "center", "right"):
+                self.create_warning(
+                    f"Invalid align value for image: {token.attrs['align']!r}",
+                    line=token_line(token, default=0),
+                    subtype="image",
+                    append_to=self.current_node,
+                )
+            else:
+                img_node["align"] = token.attrs["align"]
+        if "id" in token.attrs:
+            name = nodes.fully_normalize_name(str(token.attrs["id"]))
+            img_node["names"].append(name)
+            self.document.note_explicit_target(img_node, img_node)
+
         self.current_node.append(img_node)
 
     # ### render methods for plugin tokens
@@ -1391,11 +1436,16 @@ def html_meta_to_nodes(
         return []
 
     try:
+        # if sphinx available
         from sphinx.addnodes import meta as meta_cls
     except ImportError:
-        from docutils.parsers.rst.directives.html import MetaBody
+        try:
+            # docutils >= 0.19
+            meta_cls = nodes.meta  # type: ignore
+        except AttributeError:
+            from docutils.parsers.rst.directives.html import MetaBody
 
-        meta_cls = MetaBody.meta  # type: ignore
+            meta_cls = MetaBody.meta  # type: ignore
 
     output = []
 

myst_parser/parsers/mdit.py

@@ -9,6 +9,7 @@
 from markdown_it.renderer import RendererProtocol
 from mdit_py_plugins.amsmath import amsmath_plugin
 from mdit_py_plugins.anchors import anchors_plugin
+from mdit_py_plugins.attrs import attrs_plugin
 from mdit_py_plugins.colon_fence import colon_fence_plugin
 from mdit_py_plugins.deflist import deflist_plugin
 from mdit_py_plugins.dollarmath import dollarmath_plugin
@@ -100,6 +101,8 @@ def create_md_parser(
         md.use(tasklists_plugin)
     if "substitution" in config.enable_extensions:
         md.use(substitution_plugin, *config.sub_delimiters)
+    if "attrs_image" in config.enable_extensions:
+        md.use(attrs_plugin, after=("image",))
     if config.heading_anchors is not None:
         md.use(
             anchors_plugin,

myst_parser/sphinx_ext/myst_refs.py

@@ -151,11 +151,7 @@ def resolve_myst_ref(
             except NotImplementedError:
                 # the domain doesn't yet support the new interface
                 # we have to manually collect possible references (SLOW)
-                if not (
-                    getattr(domain, "__module__", "").startswith("sphinx.")
-                    # TODO glue can be removed when myst-nb fixed
-                    or "glue" in getattr(domain, "__module__", "")
-                ):
+                if not (getattr(domain, "__module__", "").startswith("sphinx.")):
                     logger.warning(
                         f"Domain '{domain.__module__}::{domain.name}' has not "
                         "implemented a `resolve_any_xref` method [myst.domains]",

pyproject.toml

@@ -34,10 +34,10 @@ keywords = [
 ]
 requires-python = ">=3.7"
 dependencies = [
-    "docutils>=0.15,<0.19",
+    "docutils>=0.15,<0.20",
     "jinja2", # required for substitutions, but let sphinx choose version
     "markdown-it-py>=1.0.0,<3.0.0",
-    "mdit-py-plugins~=0.3.0",
+    "mdit-py-plugins~=0.3.1",
     "pyyaml",
     "sphinx>=4,<6",
     "typing-extensions",
@@ -68,6 +68,7 @@ testing = [
     "pytest-regressions",
     "pytest-param-files~=0.3.4",
     "sphinx-pytest",
+    "sphinx<5.2",  # TODO 5.2 changes the attributes of desc/desc_signature nodes
 ]
 
 [project.scripts]

tests/test_renderers/fixtures/docutil_roles.md

@@ -93,7 +93,7 @@
 .
 <document source="notset">
     <paragraph>
-        <reference refuri="http://www.python.org/dev/peps/pep-0000">
+        <reference refuri="https://peps.python.org/pep-0000">
             PEP 0
 .
 
@@ -104,7 +104,7 @@
 .
 <document source="notset">
     <paragraph>
-        <reference refuri="http://tools.ietf.org/html/rfc1.html">
+        <reference refuri="https://tools.ietf.org/html/rfc1.html">
             RFC 1
 .