📖 Documentation updates

docs/executable-plugins.md

@@ -1,15 +1,14 @@
 ---
-title: Executable Plugins
+title: Executable Plugins (Python)
 description: Plugins built as stand-alone applications can be written in languages such as Python, and may be more familiar to some developers.
 ---
 
-MyST is able to invoke plugins written in different languages through standard IO protocols. Executable MyST plugins are treated as a [](wiki:Black_box), whereby MyST only sees the data it passes to the plugin, and the response from the plugin itself.
-
+MyST is able to invoke plugins written in different languages through standard IO protocols, for example, in Python. Executable MyST plugins are treated as a [](wiki:black_box), whereby MyST only sees the data it passes to the plugin, and the response from the plugin itself.
 
 ## Defining a new directive
 
 :::{note}
-There are many different ways to create an executable plugin. Here we'll use Python to implement an `unsplash-py` directive, but any programming language that can read and write from stdin, stdout, and stderr, and define a commandline interface would work.
+There are many different ways to create an executable plugin. Here we'll use Python to implement an `unsplash-py` directive, but any programming language that can read and write from stdin, stdout, and stderr, and define a command line interface would work.
 :::
 
 First, we'll declare the plugin _specification_ that allows MyST to discover the directives, transforms, and/or roles that the plugin implements. This specification looks very similar to [the definition of a JavaScript plugin](javascript-plugins.md#unsplash-js-source), except the implementation logic (e.g. the directive `run` method) is not defined.
@@ -18,9 +17,11 @@ First, we'll declare the plugin _specification_ that allows MyST to discover the
 :caption: a plugin to add an `unsplash-py` directive that includes a beautiful, random picture based on a query string.
 :::
 this file should be executable, e.g.
+
 ```{code} shell
 chmod +x ./unsplash.py
 ```
+
 and should be referenced from your `myst.yml` under the `projects.plugins`:
 
 ```{code} yaml
@@ -57,7 +58,7 @@ The types are defined in `myst-common` ([npm](https://www.npmjs.com/package/myst
 
 ## Implementing a custom transform
 
-Directives can be used to extend MyST with rich structured content. However, sometimes we want to _modify_ the existing behavior of MyST. One of the ways to do this is by writing a custom transform. In this section, we'll implement a transform that replaces **bold** text with _emphasis_.
+Directives can be used to extend MyST with rich structured content. However, sometimes we want to _modify_ the existing behavior of MyST. One of the ways to do this is by writing a custom transform. In this section, we'll implement a transform that replaces **bold** text with **special bold text**.
 
 First, let's define the transform
 :::{literalinclude} markup.py
@@ -89,4 +90,3 @@ I am **special bold text (python)**, whilst I am **normal bold text**
 ```
 
 I am **special bold text (python)**, whilst I am **normal bold text**
-

docs/markup.mjs

@@ -10,7 +10,12 @@ const plugin = {
           const childTextNodes = utils.selectAll('text', strongNode);
           const childText = childTextNodes.map((child) => child.value).join('');
           if (childText === 'special bold text') {
-            strongNode['type'] = 'emphasis';
+            strongNode['type'] = 'span';
+            strongNode['style'] = {
+              background: '-webkit-linear-gradient(20deg, #09009f, #E743D9)',
+              '-webkit-background-clip': 'text',
+              '-webkit-text-fill-color': 'transparent',
+            };
           }
         });
       },

docs/markup.py

@@ -27,7 +27,7 @@ def find_all_by_type(node: dict, type_: str):
 
     if "children" not in node:
         return
-    for next_node in node["children"]:      
+    for next_node in node["children"]:
         yield from find_all_by_type(next_node, type_)
 
 
@@ -56,8 +56,13 @@ def run_transform(name, data):
 
         # Only transform nodes whose text reads "special bold text (python)"
         if child_text == "special bold text (python)":
-            strong_node["type"] = "emphasis"
-
+            strong_node["type"] = "span"
+            strong_node["style"] = {
+              "background": "-webkit-linear-gradient(20deg, #09009f, #E743D9)",
+              "-webkit-background-clip": "text",
+              "-webkit-text-fill-color": "transparent",
+            };
+
     return data
 
 

docs/myst.yml

@@ -45,7 +45,7 @@ project:
     TLA: Three Letter Acronym
     OA: Open Access
     CSV: comma-separated values
-    TOC: table of contents  
+    TOC: table of contents
   plugins:
     - directives.mjs
     - unsplash.mjs

docs/plugins.md

@@ -46,9 +46,8 @@ There are two ways to implement a plugin in MyST: JavaScript plugins, and execut
 Plugins written in JavaScript with access to helpful AST manipulation routines.
 :::
 
-:::{card} Executable Plugins
+:::{card} Any Executable Plugins (e.g. Python)
 :link: ./executable-plugins.md
 
 Plugins written in other languages which communicate with MyST over stdin and stdout.
 :::
-

docs/tables.md

@@ -132,9 +132,10 @@ CSS styles are currently only used for HTML outputs and are not carried through
 
 ## Include tables from file
 
-If you have tables in a file (e.g. output from your data analysis elsewhere), you can use the {myst:directive}`include` directive. This works both for HTML and LaTeX tables.
+If you have tables in a file (e.g. output from your data analysis elsewhere), you can use the {myst:directive}`include` directive. This works both for HTML and LaTeX tables ([`table-from-file.html`](table-from-file.html)).
 
-```{myst}
+````{card}
+```myst
 ::::{table} Area Comparisons (imported HTML file)
 :label: tbl:areas-html-file
 
@@ -144,6 +145,15 @@ If you have tables in a file (e.g. output from your data analysis elsewhere), yo
 ::::
 ```
 
+::::{table} Area Comparisons (imported HTML file)
+:label: tbl:areas-html-file
+
+:::{include} table-from-file.html
+:::
+
+::::
+````
+
 ## Notebook outputs as tables
 
 You can embed Jupyter Notebook outputs as tables.