executablebooks · chrisjsewell · Jan 10, 2023 · Jan 7, 2023 · Jan 9, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -363,7 +363,7 @@ In particular for users, this update alters the parsing of tables to be consiste
 
 ### 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]`.
+- **Task lists** utilise the [markdown-it-py tasklists plugin](inv:markdown_it#md/plugins), and are applied to Markdown list items starting with `[ ]` or `[x]`.
 
   ```markdown
   - [ ] An item that needs doing
@@ -541,7 +541,7 @@ substitutions:
 {{ 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:
+The substitutions are assessed as [jinja2 expressions](http://jinja.palletsprojects.com/) and includes the [Sphinx Environment](inv:sphinx#extdev/envapi) as `env`, so you can do powerful thinks like:
 
 ```
 {{ [key1, env.docname] | join('/') }}

diff --git a/docs/conf.py b/docs/conf.py
@@ -97,6 +97,7 @@
     "substitution",
     "tasklist",
     "attrs_inline",
+    "inv_link",
 ]
 myst_number_code_blocks = ["typescript"]
 myst_heading_anchors = 2

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -69,6 +69,9 @@ Full details in the [](syntax/extensions) section.
 amsmath
 : enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations
 
+attrs_inline
+: Enable inline attribute parsing, [see here](syntax/attributes) for details
+
 colon_fence
 : Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
 
@@ -87,6 +90,9 @@ html_admonition
 html_image
 : Convert HTML `<img>` elements to sphinx image nodes, [see here](syntax/images) for details
 
+inv_link
+: Enable the `inv:` schema for Markdown link destinations, [see here](syntax/inv_links) for details
+
 linkify
 : Automatically identify "bare" web URLs and add hyperlinks
 
@@ -117,7 +123,7 @@ WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]
 
 **In general, if your build logs any warnings, you should either fix them or [raise an Issue](https://github.com/executablebooks/MyST-Parser/issues/new/choose) if you think the warning is erroneous.**
 
-However, in some circumstances if you wish to suppress the warning you can use the [`suppress_warnings`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings) configuration option, e.g.
+However, in some circumstances if you wish to suppress the warning you can use the <inv:sphinx#suppress_warnings> configuration option, e.g.
 
 ```python
 suppress_warnings = ["myst.header"]

diff --git a/docs/docutils.md b/docs/docutils.md
@@ -36,7 +36,7 @@ The commands are based on the [Docutils Front-End Tools](https://docutils.source
 :::
 
 :::{versionadded} 0.19.0
-`myst-suppress-warnings` replicates the functionality of sphinx's [`suppress_warnings`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings) for `myst.` warnings in the `docutils` CLI.
+`myst-suppress-warnings` replicates the functionality of sphinx's <inv:sphinx#suppress_warnings> for `myst.` warnings in the `docutils` CLI.
 :::
 
 The CLI commands can also utilise the [`docutils.conf` configuration file](https://docutils.sourceforge.io/docs/user/config.html) to configure the behaviour of the CLI commands. For example:

diff --git a/docs/faq/index.md b/docs/faq/index.md
@@ -102,7 +102,7 @@ If you encounter any issues with this feature, please don't hesitate to report i
 (howto/autodoc)=
 ### Use `sphinx.ext.autodoc` in Markdown files
 
-The [Sphinx extension `autodoc`](sphinx:sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to parse reStructuredText.
+The [Sphinx extension `autodoc`](inv:sphinx#sphinx.ext.autodoc), which pulls in code documentation from docstrings, is currently hard-coded to parse reStructuredText.
 It is therefore incompatible with MyST's Markdown parser.
 However, the special [`eval-rst` directive](syntax/directives/parsing) can be used to "wrap" `autodoc` directives:
 
@@ -142,7 +142,7 @@ See the [](syntax/header-anchors) section of extended syntaxes.
 :::
 
 If you'd like to *automatically* generate targets for each of your section headers,
-check out the {external+sphinx:std:doc}`autosectionlabel <usage/extensions/autosectionlabel>`
+check out the [autosectionlabel](inv:sphinx#usage/*/autosectionlabel)
 sphinx feature. You can activate it in your Sphinx site by adding the following to your
 `conf.py` file:
 
@@ -179,7 +179,7 @@ Moved to [](myst-warnings)
 ### Sphinx-specific page front matter
 
 Sphinx intercepts front matter and stores them within the global environment
-(as discussed in the {external+sphinx:std:doc}`sphinx documentation <usage/restructuredtext/field-lists>`.
+(as discussed in the [sphinx documentation](inv:sphinx#usage/*/field-lists)).
 There are certain front-matter keys (or their translations) that are also recognised specifically by docutils and parsed to inline Markdown:
 
 - `author`
@@ -228,7 +228,7 @@ emphasis syntax will now be disabled. For example, the following will be rendere
 *emphasis is now disabled*
 ```
 
-For a list of all the syntax elements you can disable, see the [markdown-it parser guide](markdown_it:using).
+For a list of all the syntax elements you can disable, see the [markdown-it parser guide](inv:markdown_it#using).
 
 ## Common errors and questions
 

diff --git a/docs/intro.md b/docs/intro.md
@@ -28,7 +28,7 @@ conda install -c conda-forge myst-parser
 (intro/sphinx)=
 ## Enable MyST in Sphinx
 
-To get started with Sphinx, see their {external+sphinx:std:doc}`quick-start guide <usage/quickstart>`.
+To get started with Sphinx, see their [quick-start guide](inv:sphinx#usage/quickstart).
 
 To use the MyST parser in Sphinx, simply add the following to your `conf.py` file:
 
@@ -80,7 +80,7 @@ $ myst-docutils-html5 --stylesheet= myfile.md
 ```
 
 To include this document within a Sphinx project,
-include `myfile.md` in a [`toctree` directive](sphinx:toctree-directive) on an index page.
+include `myfile.md` in a [`toctree` directive](inv:sphinx#toctree-directive) on an index page.
 
 ## Extend CommonMark with roles and directives
 

diff --git a/docs/syntax/optional.md b/docs/syntax/optional.md
@@ -13,16 +13,16 @@ myst:
       :width: 200px
       ```
     key4: example
-    confpy: sphinx `conf.py` {external+sphinx:std:doc}`configuration file <usage/configuration>`
+    confpy: sphinx `conf.py` [configuration file](inv:sphinx#usage/configuration)
 ---
 
 (syntax/extensions)=
 
 # Syntax Extensions
 
-MyST-Parser is highly configurable, utilising the inherent "plugability" of the [markdown-it-py](markdown_it:index) parser.
+MyST-Parser is highly configurable, utilising the inherent "plugability" of the [markdown-it-py](inv:markdown_it#index) parser.
 The following syntaxes are optional (disabled by default) and can be enabled *via* the sphinx `conf.py` (see also [](sphinx/config-options)).
-Their goal is generally to add more *Markdown friendly* syntaxes; often enabling and rendering [markdown-it-py plugins](markdown_it:md/plugins) that extend the [CommonMark specification](https://commonmark.org/).
+Their goal is generally to add more *Markdown friendly* syntaxes; often enabling and rendering [markdown-it-py plugins](inv:markdown_it#md/plugins) that extend the [CommonMark specification](https://commonmark.org/).
 
 To enable all the syntaxes explained below:
 
@@ -36,6 +36,7 @@ myst_enable_extensions = [
     "fieldlist",
     "html_admonition",
     "html_image",
+    "inv_link",
     "linkify",
     "replacements",
     "smartquotes",
@@ -101,7 +102,7 @@ Math is parsed by adding to the `myst_enable_extensions` list option, in the {{
 - `"dollarmath"` for parsing of dollar `$` and `$$` encapsulated math.
 - `"amsmath"` for direct parsing of [amsmath LaTeX environments](https://ctan.org/pkg/amsmath).
 
-These options enable their respective Markdown parser plugins, as detailed in the [markdown-it plugin guide](markdown_it:md/plugins).
+These options enable their respective Markdown parser plugins, as detailed in the [markdown-it plugin guide](inv:markdown_it#md/plugins).
 
 :::{versionchanged} 0.13.0
 `myst_dmath_enable=True` and `myst_amsmath_enable=True` are deprecated, and replaced by `myst_enable_extensions = ["dollarmath", "amsmath"]`
@@ -231,7 +232,7 @@ See [the extended syntax option](syntax/amsmath).
 (syntax/mathjax)=
 ### Mathjax and math parsing
 
-When building HTML using the {external+sphinx:mod}`sphinx.ext.mathjax <sphinx.ext.mathjax>` extension (enabled by default),
+When building HTML using the <inv:sphinx#sphinx.ext.mathjax> extension (enabled by default),
 If `dollarmath` is enabled, Myst-Parser injects the `tex2jax_ignore` (MathJax v2) and  `mathjax_ignore` (MathJax v3) classes in to the top-level section of each MyST document, and adds the following default MathJax configuration:
 
 MathJax version 2 (see [the tex2jax preprocessor](https://docs.mathjax.org/en/v2.7-latest/options/preprocessors/tex2jax.html#configure-tex2jax):
@@ -353,7 +354,7 @@ This may lead to unexpected outcomes.
 
 :::
 
-Substitution references are assessed as [Jinja2 expressions](http://jinja.palletsprojects.com) which can use [filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters), and also contains the {external+sphinx:std:doc}`Sphinx Environment <extdev/envapi>` in the context (as `env`).
+Substitution references are assessed as [Jinja2 expressions](http://jinja.palletsprojects.com) which can use [filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters), and also contains the [Sphinx Environment](inv:sphinx#extdev/envapi) in the context (as `env`).
 Therefore you can do things like:
 
 ```md
@@ -540,7 +541,7 @@ $ myst-anchors -l 2 docs/syntax/optional.md
 
 By adding `"deflist"` to `myst_enable_extensions` (in the {{ confpy }}),
 you will be able to utilise definition lists.
-Definition lists utilise the [markdown-it-py deflist plugin](markdown_it:md/plugins), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
+Definition lists utilise the [markdown-it-py deflist plugin](inv:markdown_it#md/plugins), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
 
 This syntax can be useful, for example, as an alternative to nested bullet-lists:
 
@@ -619,7 +620,7 @@ Term 3
 
 By adding `"tasklist"` to `myst_enable_extensions` (in the {{ confpy }}),
 you will be able to utilise task lists.
-Task lists utilise the [markdown-it-py tasklists plugin](markdown_it:md/plugins),
+Task lists utilise the [markdown-it-py tasklists plugin](inv:markdown_it#md/plugins),
 and are applied to markdown list items starting with `[ ]` or `[x]`:
 
 ```markdown
@@ -691,7 +692,7 @@ based on the [reStructureText syntax](https://docutils.sourceforge.io/docs/ref/r
   print("Hello, world!")
   ```
 
-A prominent use case of field lists is for use in API docstrings, as used in [Sphinx's docstring renderers](sphinx:python-domain):
+A prominent use case of field lists is for use in API docstrings, as used in [Sphinx's docstring renderers](inv:sphinx#python-domain):
 
 ````md
 ```{py:function} send_message(sender, priority)
@@ -726,16 +727,16 @@ Currently `sphinx.ext.autodoc` does not support MyST, see [](howto/autodoc).
 (syntax/attributes)=
 ## Inline attributes
 
+:::{versionadded} 0.19
+This feature is in *beta*, and may change in future versions.
+It replace the previous `attrs_image` extension, which is now deprecated.
+:::
+
 By adding `"attrs_inline"` to `myst_enable_extensions` (in the {{ confpy }}),
 you can enable parsing of inline attributes after certain inline syntaxes.
 This is adapted from [djot inline attributes](https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#inline-attributes),
 and also related to [pandoc bracketed spans](https://pandoc.org/MANUAL.html#extension-bracketed_spans).
 
-:::{important}
-This feature is in *beta*, and may change in future versions.
-It replace the previous `attrs_image` extension, which is now deprecated.
-:::
-
 Attributes are specified in curly braces after the inline syntax.
 Inside the curly braces, the following syntax is recognised:
 

diff --git a/docs/syntax/roles-and-directives.md b/docs/syntax/roles-and-directives.md
@@ -8,8 +8,8 @@ by interpreting a chuck of text as a specific type of markup, according to its n
 Mostly all
 [docutils roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html),
 [docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html),
-{external+sphinx:std:doc}`Sphinx roles <usage/restructuredtext/roles>`, or
-{external+sphinx:std:doc}`Sphinx directives <usage/restructuredtext/directives>`
+[Sphinx roles](inv:sphinx#usage/*/roles), or
+[Sphinx directives](inv:sphinx#usage/*/directives)
 can be used in MyST.
 
 ## Syntax
@@ -421,6 +421,6 @@ For example:
 
 > {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
 
-`today` is replaced by either the date on which the document is parsed, with the format set by [`today_fmt`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-today_fmt), or the `today` variable if set in the configuration file.
+`today` is replaced by either the date on which the document is parsed, with the format set by <inv:sphinx#today_fmt>, or the `today` variable if set in the configuration file.
 
 The reading speed is computed using the `myst_words_per_minute` configuration (see the [Sphinx configuration options](sphinx/config-options)).