📖 Add brackets to directive and roles in docs

docs/admonitions.md

@@ -1,5 +1,5 @@
 ---
-title: Callouts
+title: Callouts & Admonitions
 description: Callout blocks or admonitions, like "notes" or "hints" are outlined or shaded areas of a document to bring attention to particular information.
 thumbnail: ./thumbnails/admonitions.png
 ---
@@ -13,20 +13,20 @@ Try changing `tip` to `warning`!
 :::
 ```
 
-In MyST we call these kind of directives {myst:directive}`admonitions <admonition>`, however, they are almost always used through their _named_ directives, like `{note}` or `{danger}`. Admonitions can be styled as `simple` or as a `dropdown`, and can optionally hide the icon using the {myst:directive}`admonition.class` option. There are ten kinds[^docutils-admonitions] of admonitions available:
+In MyST we call these kind of directives {myst:directive}`admonitions <admonition>`, however, they are almost always used through their _named_ directives, like {myst:directive}`note` or {myst:directive}`danger`. Admonitions can be styled as `simple` or as a `dropdown`, and can optionally hide the icon using the {myst:directive}`admonition.class` option. There are ten kinds[^docutils-admonitions] of admonitions available:
 
 ```{list-table} Named admonitions that can be used as directives
 :label: admonitions-list
-* - 🔵 `note`
-  - 🟠 `attention`
-* - 🔵 `important`
-  - 🟠 `caution`
-* - 🟢 `hint`
-  - 🟠 `warning`
-* - 🟢 `seealso`
-  - 🔴 `danger`
-* - 🟢 `tip`
-  - 🔴 `error`
+* - 🔵 {myst:directive}`note`
+  - 🟠 {myst:directive}`attention`
+* - 🔵 {myst:directive}`important`
+  - 🟠 {myst:directive}`caution`
+* - 🟢 {myst:directive}`hint`
+  - 🟠 {myst:directive}`warning`
+* - 🟢 {myst:directive}`seealso`
+  - 🔴 {myst:directive}`danger`
+* - 🟢 {myst:directive}`tip`
+  - 🔴 {myst:directive}`error`
 ```
 
 [^docutils-admonitions]: These admonitions are the same as those used in [docutils](https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions) and Sphinx.
@@ -134,7 +134,7 @@ GitHub markdown transforms blockquotes that start with a bold `Note` or text wit
 ::::{tip} Compatibility with Pandoc & Quarto
 :class: dropdown
 In Quarto/Pandoc markdown admonitions are styled with special classes like `{.callout-note}` or `{.callout-tip}`).
-If you are using JupyterBook or Sphinx documentation, use an `{admonition}` directive with the specific class, for example:
+If you are using JupyterBook or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
 
 ```{myst}
 ::: {.callout-tip}
@@ -149,7 +149,7 @@ This is an example of a callout with a caption.
 :class: dropdown
 In Sphinx, all named admonitions (e.g. `{note}` or `{tip}`), have **no arguments**.
 If you place content on the first line it will instead be prepended to the admonition body.
-If you are using JupyterBook or Sphinx documentation, use an `{admonition}` directive with the specific class, for example:
+If you are using JupyterBook or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
 
 ```{myst}
 :::{admonition} The Title

docs/code.md

@@ -68,7 +68,7 @@ You can also set the start number using the {myst:directive}`code.lineno-start`
 ```{tip} Docutils and Sphinx Compatibility
 :class: dropdown
 
-For full compatibility with Sphinx we suggest using `{code-block}` directive, which is an alias of the {myst:directive}`code` directive. The MyST implementation supports both the Sphinx [`{code-block} directive`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) as well as the `docutils` [{code} directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#code) implementation, which only supports the `number-lines` option.
+For full compatibility with Sphinx we suggest using {myst:directive}`code-block` directive, which is an alias of the {myst:directive}`code` directive. The MyST implementation supports both the Sphinx [`{code-block} directive`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) as well as the `docutils` [{code} directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#code) implementation, which only supports the `number-lines` option.
 
 You can use either `code` or `code-block` directive documented above or even a normal markdown code block.
 All implementations in MyST are resolved to the same `code` type in the abstract syntax tree.
@@ -112,7 +112,7 @@ creates a snippet that has matching line numbers, and starts at a line including
 ```
 
 :::{important} Paths are Relative
-The {myst:directive}`argument <include.arg>` of a `{literalinclude}` directive is the file path, which is relative to the file from which it was referenced.
+The {myst:directive}`argument <include.arg>` of a {myst:directive}`literalinclude` directive is the file path, which is relative to the file from which it was referenced.
 :::
 
 In {myst:directive}`include.literal` mode, the include directive also accepts all of the options from the `code-block` (e.g. {myst:directive}`include.linenos`).

docs/cross-references.md

@@ -90,8 +90,8 @@ Results in:
 :::{note} This is a short-hand for several types of references
 The `@` short-hand syntax for referencing maps on to many different types of [referencing roles](#reference:roles), depending on the target that you are referencing.
 
-For example, if `@target` is a bibliography entry, it will map onto the {myst:role}`{cite} <cite>` role.
-If it is an image or a section header, it will map on to the {myst:role}`{ref} <ref>` role.
+For example, if `@target` is a bibliography entry, it will map onto the {myst:role}`cite` role.
+If it is an image or a section header, it will map on to the {myst:role}`ref` role.
 :::
 
 (reference:roles)=
@@ -106,13 +106,13 @@ Below we describe the most commonly-used ones.
 (ref-role)=
 
 ref
-: The `{ref}` role can be used to bring the title or caption directly in line, the role can take a single argument which is the label, for example, `` {ref}`reference-target` ``
+: The {myst:role}`ref` role can be used to bring the title or caption directly in line, the role can take a single argument which is the label, for example, `` {ref}`reference-target` ``
 : You can also choose the reference text directly (not taking from the title or caption) by using, `` {ref}`your text here <reference-target>` ``.
 
 (numref-role)=
 
 numref
-: The `{numref}` role is exactly the same as the above `{ref}` role, but also allows you to use a `%s` in place of the number, which will get filled in when the content is rendered. For example, ``{numref}`Custom Table %s text <my-table-ref>`.`` will become `Custom Table 3 text`.
+: The {myst:role}`numref` role is exactly the same as the above {myst:role}`ref` role, but also allows you to use a `%s` in place of the number, which will get filled in when the content is rendered. For example, ``{numref}`Custom Table %s text <my-table-ref>`.`` will become `Custom Table 3 text`.
 
 (eq-role)=
 
@@ -177,7 +177,7 @@ You can use this syntax to also reference [Section/Header targets](#targeting-he
 
 ### Header Targets
 
-To add labels to a header use `(my-section)=` before the header, these can then be used in markdown links and `{ref}` roles. This is helpful if you want to quickly insert links to other parts of your book. Referencing a heading will show the heading and the subsequent two pieces of content[^3], unless a header is encountered.
+To add labels to a header use `(my-section)=` before the header, these can then be used in markdown links and {myst:role}`ref` roles. This is helpful if you want to quickly insert links to other parts of your book. Referencing a heading will show the heading and the subsequent two pieces of content[^3], unless a header is encountered.
 
 [^3]: The content could be a single paragraph, a figure, table or list. It can also be fully interactive content, with cross-references to other content, allowing you to nest and follow references easily!
 
@@ -239,7 +239,7 @@ numbering:
 
 ### Equations Targets
 
-To reference equations, use the `{eq}` role. It will automatically insert the number of the equation. Note that you cannot modify the text of equation links.
+To reference equations, use the {myst:role}`eq` role. It will automatically insert the number of the equation. Note that you cannot modify the text of equation links.
 
 (example-equation-targets)=
 
@@ -301,7 +301,7 @@ This figure has been included from [](./interactive-notebooks.ipynb) and can be
 
 ### Label Anything
 
-It is possible to label any document node by adding `(my-label)=` before any other block of content. These can be referenced using the `{ref}` role, but by default will not be enumerated, so you cannot use `%s` or `{number}` in the content.
+It is possible to label any document node by adding `(my-label)=` before any other block of content. These can be referenced using the {myst:role}`ref` role, but by default will not be enumerated, so you cannot use `%s` or `{number}` in the content.
 
 ```{myst}
 (my-paragraph)=

docs/diagrams.md

@@ -4,7 +4,7 @@ description: Include simple programmatic mermaid diagrams in your documents.
 thumbnail: ./thumbnails/diagrams.png
 ---
 
-It is possible to add [mermaid diagrams](https://mermaid-js.github.io/mermaid) using the `{mermaid}` directive, for example:
+It is possible to add [mermaid diagrams](https://mermaid-js.github.io/mermaid) using the {myst:directive}`mermaid` directive, for example:
 
 ````{myst}
 ```{mermaid}

docs/directives.mjs

@@ -182,8 +182,12 @@ const mystDirectiveRole = {
     const identifier = opt
       ? `directive-${directive?.name ?? name}-${opt}`
       : `directive-${directive?.name ?? name}`;
+    var textToDisplay = modified?.trim() || name;
+    if (opt) {
+      textToDisplay = `${textToDisplay}.${opt}`;
+    }
     return [
-      u('crossReference', { identifier }, [u('inlineCode', modified?.trim() || opt || name)]),
+      u('crossReference', { identifier }, [u('inlineCode', `{${textToDisplay}}`)]),
     ];
   },
 };
@@ -206,8 +210,12 @@ const mystRoleRole = {
     const [name, opt] = label?.split('.') ?? [];
     const role = defaultRoles.find((d) => d.name === name || d.alias?.includes(name));
     const identifier = opt ? `role-${role?.name ?? name}-${opt}` : `role-${role?.name ?? name}`;
+    var textToDisplay = modified?.trim() || name;
+    if (opt) {
+      textToDisplay = `${textToDisplay}.${opt}`;
+    }
     return [
-      u('crossReference', { identifier }, [u('inlineCode', modified?.trim() || opt || name)]),
+      u('crossReference', { identifier }, [u('inlineCode', `{${textToDisplay}}`)]),
     ];
   },
 };

docs/embed.md

@@ -27,9 +27,9 @@ Here's a cool figure.
 
 (docs:embed)=
 
-## The `{embed}` directive
+## The {myst:directive}`embed` directive
 
-The `{embed}` directive allows you to insert snippets of content at the time a page is rendered.
+The {myst:directive}`embed` directive allows you to insert snippets of content at the time a page is rendered.
 
 See {myst:directive}`the {embed} directive documentation <embed>` for details about all the arguments you can give to `{embed}`.
 
@@ -144,7 +144,7 @@ The following content is embedded from `![](xref:spec#admonition)`:
 
 (docs:include)=
 
-## The `{include}` directive
+## The {myst:directive}`include` directive
 
 If a portion of your content is in a separate file that is **not already included in your project** you can use the {myst:directive}`include` directive to parse and include that content.
 This directive is helpful for including content snippets, such as a table, equation, that you want to keep in a different file on disk, but present as if it were one document. In addition to Markdown, MyST will also parse `.ipynb`, `.tex`, and `.html`.

docs/execute-notebooks.md

@@ -21,8 +21,8 @@ myst build --execute
 The following computational content will be executed:
 
 - **Notebook cells** will be executed in the order they appeared in a notebook (ie, a file ending in `.ipynb`).
-- **`{code-block}` directives** will be executed similar to a code block cell. See [](./notebooks-with-markdown.md) for more information.
-- **Inline expressions with the `{eval}` role** can be used to insert the outputs of a computation in-line with other text.
+- **{myst:directive}`code-block` directives** will be executed similar to a code block cell. See [](./notebooks-with-markdown.md) for more information.
+- **Inline expressions with the {myst:role}`eval` role** can be used to insert the outputs of a computation in-line with other text.
 
 :::{note} Jupyter is required for execution
 In order to execute your MyST content, you must install a Jupyter Server and the kernel needed to execute your code (e.g., the [IPython kernel](https://ipython.readthedocs.io/en/stable/), the [Xeus Python kernel](https://github.com/jupyter-xeus/xeus-python), or the [IRKernel](https://irkernel.github.io/).)

docs/exercises.md

@@ -14,7 +14,7 @@ The implementation and documentation for exercises and solutions is based on [Sp
 
 Changes to the original extension include being able to click on the exercise label (e.g. "Exercise 1"), and having a link to that exercise anchor. We have also updated the styles from both Sphinx and JupyterBook to be more distinct from admonitions.
 
-You can also reference exercises with any cross-reference syntax (including the `{ref}` and `{numref}` roles). We recommend the markdown link syntax.
+You can also reference exercises with any cross-reference syntax (including the {myst:role}`ref` and {myst:role}`numref` roles). We recommend the markdown link syntax.
 :::
 
 ## Exercise Directive
@@ -57,7 +57,7 @@ The following options for exercise and solution directives are supported:
 
 - `label`: text
 
-  A unique identifier for your exercise that you can use to reference it with a Markdown link or `{ref}` and `{numref}` roles. Cannot contain spaces or special characters.
+  A unique identifier for your exercise that you can use to reference it with a Markdown link or {myst:role}`ref` and {myst:role}`numref` roles. Cannot contain spaces or special characters.
 
 - `class`: text
 
@@ -141,9 +141,9 @@ You can refer to an exercise using the standard link syntax:
 :::{tip} Compatibility with Sphinx Exercise
 :class: dropdown
 
-You can also refer to an exercise using the `{ref}` role like `` {ref}`my-exercise` ``, which will display the title of the exercise directive. In the event that directive does not have a title, the title will be the default "Exercise" or "Exercise {number}" like so: {ref}`my-exercise`.
+You can also refer to an exercise using the {myst:role}`ref` role like `` {ref}`my-exercise` ``, which will display the title of the exercise directive. In the event that directive does not have a title, the title will be the default "Exercise" or "Exercise {number}" like so: {ref}`my-exercise`.
 
-Enumerable directives can also be referenced through the `numref` role like `` {numref}`my-exercise` ``, which will display the number of the exercise directive. Referencing the above directive will display {numref}`my-exercise`. In this case it displays the same result as the `{ref}` role as `exerise` notes are (by default) enumerated.
+Enumerable directives can also be referenced through the {myst:role}`numref` role like `` {numref}`my-exercise` ``, which will display the number of the exercise directive. Referencing the above directive will display {numref}`my-exercise`. In this case it displays the same result as the {myst:role}`ref` role as `exercise` notes are (by default) enumerated.
 
 Furthermore, `numref` can take in three additional placeholders for more customized titles:
 
@@ -160,7 +160,7 @@ For example,\
 
 ### Referencing Solutions
 
-You can refer to a solution directly as well using a Markdown link or using the `{ref}` role like: `` {ref}`my-solution` `` the output of which depends on the attributes of the linked directive. If the linked directive is enumerable, the role will replace the solution reference with the linked directive type and its appropriate number like so: {ref}`my-solution`.
+You can refer to a solution directly as well using a Markdown link or using the {myst:role}`ref` role like: `` {ref}`my-solution` `` the output of which depends on the attributes of the linked directive. If the linked directive is enumerable, the role will replace the solution reference with the linked directive type and its appropriate number like so: {ref}`my-solution`.
 
 In the event that the directive being referenced is unenumerable, the reference will display its title: {ref}`nfactorial-solution`.
 

docs/glossaries-and-terms.md

@@ -3,7 +3,7 @@ title: Glossaries, Terms and Abbreviations
 short_title: Glossaries & Terms
 ---
 
-To add a glossary to your content, add the `{glossary}` directive with the content as [definition lists](#definition-lists).
+To add a glossary to your content, add the {myst:directive}`glossary` directive with the content as [definition lists](#definition-lists).
 
 ```{myst}
 :::{glossary}
@@ -36,7 +36,7 @@ A second term
 
 ## Referencing a Term
 
-To reference a term in a glossary use the `{term}` role:
+To reference a term in a glossary use the {myst:role}`term` role:
 
 - `` {term}`MyST` `` produces {term}`MyST`
 - `` {term}`MyST Markdown <MyST>` `` produces {term}`MyST Markdown <MyST>`

docs/math.md

@@ -184,7 +184,7 @@ w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
 ```{warning}
 If you are using JupyterBook or Sphinx, there are the following limitations:
 (1) the `label` analysis of the source is not yet implemented;
-(2) you can not reference equations using the `{numref}` role; and
+(2) you can not reference equations using the {myst:role}`numref` role; and
 (3) labels must not have spaces or start with a number (this is good practice anyways!).
 ```
 `````

docs/notebooks-with-markdown.md

@@ -15,7 +15,7 @@ import numpy as np
 
 (myst:code-cell)=
 
-## Code cells with the `{code-cell}` directive
+## Code cells with the {myst:directive}`code-cell` directive
 
 You can use the {myst:directive}`code-cell` directive to create block-level computational outputs in MyST Markdown.
 
@@ -24,7 +24,7 @@ Markdown-based code cells are still in the works, and missing key functionality.
 Their behavior is subject to change unpredictably!
 ```
 
-`{code-cell}` directives have the following form:
+{myst:directive}`code-cell` directives have the following form:
 
 ````
 ```{code-cell} LANGUAGE
@@ -56,9 +56,9 @@ phrase = f"{hello}, {there}!"
 print(phrase)
 ```
 
-### Add tags to `{code-cell}` directives
+### Add tags to {myst:directive}`code-cell` directives
 
-You can add tags to the `{code-cell}` directive.
+You can add tags to the {myst:directive}`code-cell` directive.
 They will be parsed and used in the same way that cell tag metadata is used in `.ipynb` files.
 
 For example, the following code defines a `remove-input` tag:
@@ -131,9 +131,9 @@ See [](#notebooks:cell-visibility) for more information.
 
 (myst:inline-expressions)=
 
-## Inline expressions with the `{eval}` role
+## Inline expressions with the {myst:role}`eval` role
 
-You can use the `{eval}` role to evaluate code that is surrounded by text.
+You can use the {myst:role}`eval` role to evaluate code that is surrounded by text.
 This allows you to quickly insert its output in a way that flows with the text around it.
 
 For example, the following MyST Markdown would re-use the variable defined above.

docs/proofs-and-theorems.md

@@ -14,7 +14,7 @@ The implementation and documentation for proofs, theorems, etc. is based on [Sph
 
 Changes to the original extension include being able to click on the proof label (e.g. "Theorem 1"), and having a link to that proof anchor. We have also updated the styles from both Sphinx and JupyterBook to be more distinct from admonitions.
 
-You can also reference proofs with any cross-reference syntax (including the `{prf:ref}` role). We recommend the markdown link syntax.
+You can also reference proofs with any cross-reference syntax (including the {myst:role}`prf:ref` role). We recommend the markdown link syntax.
 :::
 
 Here is an example of a `{prf:theorem}` with a custom title:
@@ -63,7 +63,7 @@ The following options for proof directives are supported:
 
 - `label`: text
 
-  A unique identifier for your theorem that you can use to reference it with a Markdown link or the `{prf:ref}` role. Cannot contain spaces or special characters.
+  A unique identifier for your theorem that you can use to reference it with a Markdown link or the {myst:role}`prf:ref` role. Cannot contain spaces or special characters.
 
 - `class`: text