Merge pull request #617 from executablebooks/feat/plugins

🔌 Support plugins for CLI (roles/directives only)

.changeset/afraid-weeks-glow.md

@@ -0,0 +1,5 @@
+---
+'myst-common': patch
+---
+
+Export `BodyDefinition` and `OptionDefinition`.

.changeset/brave-seahorses-help.md

@@ -0,0 +1,10 @@
+---
+'myst-ext-exercise': patch
+'myst-ext-reactive': patch
+'myst-ext-proof': patch
+'myst-ext-card': patch
+'myst-ext-grid': patch
+'myst-ext-tabs': patch
+---
+
+Change to use String/Number/Boolean instead of ParsedEnumType

.changeset/curly-comics-tell.md

@@ -0,0 +1,5 @@
+---
+'myst-spec-ext': patch
+---
+
+Improve the citation node

.changeset/empty-feet-hammer.md

@@ -0,0 +1,5 @@
+---
+'myst-directives': patch
+---
+
+Move from ParseTypesEnum to String/Number/Boolean in many cases.

.changeset/fifty-kangaroos-think.md

@@ -0,0 +1,7 @@
+---
+'myst-ext-card': patch
+'myst-ext-tabs': patch
+'myst-roles': patch
+---
+
+Change from alias as string to alias as a string-list.

.changeset/great-keys-end.md

@@ -0,0 +1,5 @@
+---
+'myst-common': patch
+---
+
+Add `pluginLoads` ruleId

.changeset/odd-pots-peel.md

@@ -0,0 +1,6 @@
+---
+'myst-common': patch
+'myst-cli': patch
+---
+
+Add MySTPlugin to common exported types

.changeset/perfect-peas-ring.md

@@ -0,0 +1,5 @@
+---
+'myst-parser': patch
+---
+
+Support ParseTypesEnum as String/Number/Boolean or `"myst"`

.changeset/pretty-olives-fly.md

@@ -0,0 +1,5 @@
+---
+'myst-directives': patch
+---
+
+Document images and figure and iframe directives

.changeset/purple-snails-return.md

@@ -0,0 +1,5 @@
+---
+'myst-roles': patch
+---
+
+Support additional citation roles

.changeset/real-ducks-appear.md

@@ -0,0 +1,5 @@
+---
+'myst-config': patch
+---
+
+Allow for plugins in the ProjectConfig

.changeset/silver-suits-rush.md

@@ -0,0 +1,7 @@
+---
+'myst-directives': patch
+'myst-transforms': patch
+'myst-spec-ext': patch
+---
+
+Add filename to codeblock and include directives

.changeset/soft-cups-melt.md

@@ -0,0 +1,5 @@
+---
+'myst-common': patch
+---
+
+Only allow `alias` to be a string list, which simplifies the downstream implementations

.changeset/soft-singers-warn.md

@@ -0,0 +1,5 @@
+---
+'myst-cli': patch
+---
+
+Support for loading plugins in the session

.changeset/tidy-points-bow.md

@@ -0,0 +1,5 @@
+---
+'myst-directives': patch
+---
+
+Improve documentation for admonition and include

.changeset/wild-mayflies-lay.md

@@ -0,0 +1,5 @@
+---
+'myst-common': patch
+---
+
+Allow for `ParseTypesEnum` to also be a `Number`, `String` or `Boolean` object or `"myst"` for parsed content.

docs/_toc.yml

@@ -45,12 +45,16 @@ parts:
       - file: creating-pdf-documents
       - file: creating-word-documents
       - file: creating-jats-xml
+  - caption: Extensions
+    chapters:
+      - file: plugins
   - caption: Reference
     chapters:
       - file: background
       - file: installing
       - file: installing-prerequisites
       - file: commonmark
       - file: syntax-overview
+      - file: directives
       - file: frontmatter
       - file: glossary

docs/admonitions.md

@@ -13,7 +13,7 @@ Try changing `tip` to `warning`!
 :::
 ```
 
-In MyST we call these kind of directives admonitions, 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. 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 `{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:
 
 ```{list-table} Named admonitions that can be used as directives
 :name: admonitions-list
@@ -99,8 +99,8 @@ This is an error admonition
 
 ## Admonition Titles
 
-All admonitions have a single argument, which is the admonition title and can use markdown.
-If a title argument is not supplied the first node is used if it is a `heading` or a paragraph with fully bold text; otherwise the name of the directive is used (e.g. `seealso` becomes `See Also`; `note` becomes `Note`).
+All admonitions have a single argument ({myst:directive}`docs <admonition.arg>`), which is the admonition title and can use markdown.
+If a title argument is not supplied the first node of the {myst:directive}`admonition.body` is used if it is a `heading` or a paragraph with fully bold text; otherwise the name of the directive is used (e.g. `seealso` becomes `See Also`; `note` becomes `Note`).
 
 ```{myst}
 :::{tip} Admonition _title_
@@ -110,7 +110,7 @@ Here is an admonition!
 
 :::::::{tip} Compatibility with GitHub
 :class: dropdown
-GitHub markdown transforms blockquotes that start with a bold `Note` or text with `[!NOTE]` into a simple admonition (see [GitHub](https://github.com/community/community/discussions/16925)). This syntax only works for `note`, `important` or `warning`. MyST transforms these blockquotes into the appropriate admonitions with a `simple` class.
+GitHub markdown transforms blockquotes that start with a bold `Note` or text with `[!NOTE]` into a simple admonition (see [GitHub](https://github.com/community/community/discussions/16925)). This syntax only works for `note`, `important` or `warning`. MyST transforms these blockquotes into the appropriate admonitions with a `simple` {myst:directive}`admonition.class`.
 
 ```{myst}
 > [!NOTE]
@@ -164,7 +164,7 @@ This is the body.
 
 ## Admonition Dropdown
 
-To turn an admonition into a dropdown, add the `dropdown` class to them.
+To turn an admonition into a dropdown, add the `dropdown` {myst:directive}`admonition.class` to them.
 Dropdown admonitions use the `<details>` HTML element (meaning they also will work without Javascript!),
 and they can be helpful when including text that shouldn't immediately visible to your readers.
 
@@ -177,23 +177,5 @@ and they can be helpful when including text that shouldn't immediately visible t
 
 :::{seealso} You can also use a `{dropdown}`
 :class: dropdown
-You can also use a `{dropdown}` directive, which provides a more compact writing experience and is simpler in the displayed style. See [](#dropdowns) for more information.
+You can also use a {myst:directive}`dropdown` directive, which provides a more compact writing experience and is simpler in the displayed style. See [](#dropdowns) for more information.
 :::
-
-### Reference
-
-**Arguments** _(markdown)_
-: The `admonition` requires a single argument that is the title, parsed as markdown.
-
-**Options**
-: No options are required
-
-    class _(optional, string)_
-    : CSS classes to add to your admonition. Special classes include:
-      - `dropdown`: turns the admonition into a `<details>` html element
-      - `simple`: an admonition with "simple" styles
-      - the name of an admonition, the first admonition name encountered will be used
-    : Note that if you provide conflicting class names, the first one in the {ref}`list above <admonitions-list>` will be used.
-
-    icon _(optional, boolean)_
-    : setting icon to false will hide the icon

docs/code.md

@@ -9,7 +9,7 @@ numbering:
 ```{warning}
 The code blocks on this page are for **presentation** of code only, they are not executed.
 
-For code execution, see the `{code-cell}` directive in the execution section of the documentation.
+For code execution, see the {myst:directive}`code-cell` directive in the execution section of the documentation.
 ```
 
 You can include code in your documents using the standard markup syntax of ` ```language `,
@@ -31,10 +31,10 @@ A list of language names supported by the  `myst-react` package is here: [HLJS l
 
 ## Code blocks
 
-The above code is not a directive, it is just standard markdown syntax, which cannot add a caption or label. To caption or label blocks of code use the `code-block` directive.
+The above code is not a directive, it is just standard markdown syntax, which cannot add a {myst:directive}`code.caption` or {myst:directive}`code.label`. To caption or label blocks of code use the {myst:directive}`code` directive.
 
 ````{myst}
-```{code-block} python
+```{code} python
 :name: my-program
 :caption: Creating a TensorMesh using SimPEG
 from discretize import TensorMesh
@@ -50,52 +50,42 @@ In the [](#my-program), we create a mesh for simulation using [SimPEG](https://d
 
 ## Numbering and Highlighting
 
-To add numbers and emphasis to lines, we are following the [sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) `code-block` directive. You can use `linenos` which is a flag, with no value, and `emphasize-lines` with a comma-separated list of line numbers to emphasize.
+To add numbers and emphasis to lines use the {myst:directive}`code` directive. You can use {myst:directive}`code.linenos` which is a flag, with no value, and {myst:directive}`code.emphasize-lines` with a comma-separated list of line numbers to emphasize.
 
-````{code-block} md
+````{code} md
 :linenos:
 :emphasize-lines: 2,3
 :caption: Emphasize lines inside of a `code` block.
-```{code-block}
+```{code}
 :linenos:
 :emphasize-lines: 2,3
 ...
 ````
 
-You can also set the start number using the `lineno-start` directive, and all emphasized lines will be relative to that number.
+You can also set the start number using the {myst:directive}`code.lineno-start` directive, and all emphasized lines will be relative to that number.
 
-## `code-block` reference
-
-linenos (no value)
-: Show line numbers for the code block
-
-lineno-start (number)
-: Set the first line number of the code block. If present, `linenos` option is also automatically activated.
-: Default line numbering starts at `1`.
-
-emphasize-lines (string)
-: Emphasize lines of the code block, for example, `1, 2` highlights the first and second lines.
-: The line number counting starts at `lineno-start`, which is by default `1`.
-
-caption (string)
-: Add a caption to the code block.
+```{tip} Docutils and Sphinx Compatibility
+:class: dropdown
 
-name (string)
-: The target label for the code-block, can be used by `ref` and `numref` roles.
+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.
 
-```{note} Alternative implementations
-:class: dropdown
+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.
+```
 
-The parser also supports the `docutils` implementation (see [docutils documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#code)) of a `{code}` directive, which only supports the `number-lines` option.
+## Showing a Filename
 
-It is recommended to use the more fully featured `code-block` directive documented above, or a simple markdown code block.
+Adding a {myst:directive}`code.filename` option will show the name of the file at the top of the code block. For example, `myst.yml` in the following example:
 
-All implementations are resolved to the same `code` type in the abstract syntax tree.
+```{code} yaml
+:filename: myst.yml
+project:
+  title: Showing Filenames in code-blocks
 ```
 
 ## Including Files
 
-If your code is in a separate file you can use the `literalinclude` directive (or the `include` directive with the `literal` flag).
+If your code is in a separate file you can use the {myst:directive}`literalinclude` directive (or the {myst:directive}`include` directive with the {myst:directive}`include.literal` flag).
 This directive is helpful for showing code snippets without duplicating your content.
 
 For example, a `literalinclude` of a snippet of the `myst.yml` such as:
@@ -117,45 +107,15 @@ creates a snippet that has matching line numbers, and starts at a line including
 ```
 
 :::{note} Auto Reload
-If you are working with the auto-reload (e.g. `myst start`), currently you will need to save the file with the `literalinclude` directive for the contents to update.code for the contents to update.
+If you are working with the auto-reload (e.g. `myst start`), currently you will need to save the file with the {myst:directive}`literalinclude` directive for the contents to update.code for the contents to update.
 :::
 
-## `include` Reference
-
-The argument of an include directive is the file path, relative to the file from which it was referenced.
-By default the file will be parsed using MyST, you can also set the file to be `literal`, which will show as a code-block; this is the same as using the `literalinclude` directive.
-If in literal mode, the directive also accepts all of the options from the `code-block` (e.g. `:linenos:`).
-
-To select a portion of the file to be shown using the `start-at`/`start-after` selectors with the `end-before`/`end-at`, which use a snippet of included text.
-Alternatively, you can explicitly select the lines (e.g. `1,3,5-10,20-`) or the `start-line`/`end-line` (which is zero based for compatibility with Sphinx).
-
-literal (boolean)
-: Flag the include block as literal, and show the contents as a code block. This can also be set automatically by setting the `language` or using the `literalinclude` directive.
-
-lang (string)
-: The language of the code to be highlighted as. If set, this automatically changes an `include` into a `literalinclude`.
-: You can alias this as `language` or `code`
-
-start-line (number)
-: Only the content starting from this line will be included. The first line has index 0 and negative values count from the end.
-
-start-at (string)
-: Only the content after and including the first occurrence of the specified text in the external data file will be included.
-
-start-after (string)
-: Only the content after the first occurrence of the specified text in the external data file will be included.
-
-end-line (number)
-: Only the content up to (but excluding) this line will be included.
-
-end-at (string)
-: Only the content up to and including the first occurrence of the specified text in the external data file (but after any start-after text) will be included.
+The argument of an include directive is the file path ({myst:directive}`docs <include.arg>`), which is relative to the file from which it was referenced.
+By default the file will be parsed using MyST, you can also set the file to be {myst:directive}`include.literal`, which will show as a code-block; this is the same as using the {myst:directive}`literalinclude` directive.
 
-end-before (string)
-: Only the content before the first occurrence of the specified text in the external data file (but after any start-after text) will be included.
+If in {myst:directive}`include.literal` mode, the directive also accepts all of the options from the `code-block` (e.g. {myst:directive}`include.linenos`).
+To select a portion of the file to be shown using the {myst:directive}`include.start-at`/{myst:directive}`include.start-after` selectors with the {myst:directive}`include.end-before`/{myst:directive}`include.end-at`, which use a snippet of included text.
 
-lines (string)
-: Specify exactly which lines to include from the original file, starting at 1. For example, `1,3,5-10,20-` includes the lines 1, 3, 5 to 10 and lines 20 to the last line of the original file.
+Alternatively, you can explicitly select the lines (e.g. `1,3,5-10,20-`) or the {myst:directive}`include.start-line`/{myst:directive}`include.end-line` (which is zero based for compatibility with Sphinx).
 
-lineno-match (boolean)
-: Display the original line numbers, correct only when the selection consists of contiguous lines.
+The include directive is based on [RST](https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment) and [Sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude).

docs/directives.md

@@ -0,0 +1,58 @@
+---
+title: Directives
+description: Code and code-blocks can be used to show programming languages.
+---
+
+:::{myst:directive} admonition
+:::
+
+:::{myst:directive} bibliography
+:::
+
+:::{myst:directive} code
+:::
+
+:::{myst:directive} code-cell
+:::
+
+:::{myst:directive} dropdown
+:::
+
+:::{myst:directive} embed
+:::
+
+:::{myst:directive} figure
+:::
+
+:::{myst:directive} glossary
+:::
+
+:::{myst:directive} iframe
+:::
+
+:::{myst:directive} image
+:::
+
+:::{myst:directive} include
+:::
+
+:::{myst:directive} list-table
+:::
+
+:::{myst:directive} margin
+:::
+
+:::{myst:directive} math
+:::
+
+:::{myst:directive} mdast
+:::
+
+:::{myst:directive} mermaid
+:::
+
+:::{myst:directive} myst
+:::
+
+:::{myst:directive} output
+:::