🔌 Support plugins for CLI (initial work)

.changeset/afraid-weeks-glow.md

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

.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/perfect-peas-ring.md

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

.changeset/real-ducks-appear.md

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

.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

@@ -95,7 +95,7 @@ All implementations are resolved to the same `code` type in the abstract syntax
 
 ## 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 +117,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 ({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.
 
-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:`).
+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.
 
-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).
+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).
 
-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.
-
-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.
-
-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.
-
-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
+:::