apex-ruby 1.0.18 → 1.0.20

data/ext/apex_ext/apex_src/documentation/app-transformed/Plugins.md

@@ -0,0 +1,678 @@
+## Plugins
+
+Apex supports a lightweight plugin system that lets you add new syntax and post‑processing behavior **without patching the core**. Plugins can be small scripts (Ruby, Python, etc.) or simple declarative regex rules defined in YAML.
+
+This page covers:
+
+- **Where plugins live**
+- **How to enable/disable plugins**
+- **Processing phases**
+- **Plugin manifest format (`plugin.yml`)**
+- **External handler plugins (scripts/commands)**
+- **Declarative regex plugins (pure YAML)**
+- **Plugin bundles (`bundle` key)**
+- **Support directory and environment variables**
+- **Plugin metadata for directories and installers**
+- **Installing plugins from the directory or a Git URL**
+- **Examples: `kbd` liquid tag and `:emoji:` spans**
+
+---
+
+## Enabling and disabling plugins
+
+By design, **plugins are disabled by default** so Apex's performance and behavior are unchanged unless you explicitly opt in.
+
+Enable plugins by checking **Settings->Processor->Include Plugins**.
+
+You can also enable plugins in document metadata (in the document's front matter):
+
+```yaml
+---
+title: Plugin demo
+plugins: true
+---
+```
+
+If you never enable plugins in settings or set `plugins: true` in metadata, Apex will not load or run any plugins.
+
+---
+
+## Where plugins live
+
+Plugins are discovered from **two locations**, in this order:
+
+- **Project-local plugins**
+  - Directory: `.apex/plugins/` in the same project as your documents
+  - Structure: **one subdirectory per plugin**, for example:
+    - `.apex/plugins/kbd/plugin.yml`
+    - `.apex/plugins/kbd/kbd_plugin.rb`
+    - `.apex/plugins/emoji/plugin.yml`
+
+- **Global (user) plugins**
+  - Directory (XDG-aware):
+    - If `$XDG_CONFIG_HOME` is set:
+      - `$XDG_CONFIG_HOME/apex/plugins/`
+    - Otherwise:
+      - `~/.config/apex/plugins/`
+  - Same structure: one subdirectory per plugin:
+    - `~/.config/apex/plugins/kbd/plugin.yml`
+    - `~/.config/apex/plugins/emoji/plugin.yml`
+
+**Plugin IDs must be unique.** If a project plugin and a global plugin share the same `id`, the **project plugin wins** and the global one is ignored.
+
+---
+
+## Installing plugins in Marked
+
+Marked provides an **Install Plugins** option that allows you to select a plugin directory on your disk and have it automatically installed to `~/.config/apex/plugins`. This makes it easy to install plugins from local directories or cloned repositories.
+
+Marked will list available plugins in a **Plugins panel** within the Processor settings. From there, you can:
+
+- View all installed plugins
+- Enable or disable individual plugins
+- Install new plugins from the central directory
+- Remove installed plugins
+
+---
+
+## Processing phases
+
+Apex exposes several **phases** in its pipeline. Plugins can hook into one or more phases; for now, two are wired up:
+
+- **`pre_parse`**
+  - Runs on the **raw Markdown text** *before* it is parsed.
+  - Good for:
+    - Custom syntax (e.g. `{% kbd ... %}`)
+    - Textual rewrites
+    - Adding/removing markup before Apex sees it
+
+- **`post_render`**
+  - Runs on the **final HTML output** after Apex finishes rendering.
+  - Good for:
+    - Wrapping elements in spans/divs
+    - Adding CSS classes
+    - Simple HTML post-processing (e.g. turning `:emoji:` into `<span>`)
+
+Internally, plugins for each phase are run in a **deterministic order**:
+
+1. Sorted by **priority** (lower numbers first; default is `100`).
+2. Ties broken by **plugin `id`** (lexicographically).
+
+---
+
+## Plugin manifest: `plugin.yml`
+
+Each plugin is defined by a **manifest** file:
+
+- **File name**: `plugin.yml`
+- **Location**: inside the plugin's directory, e.g.:
+
+  ```text
+  .apex/plugins/kbd/plugin.yml
+  ~/.config/apex/plugins/emoji/plugin.yml
+  ```
+
+At minimum, a plugin needs:
+
+```yaml
+---
+id: my-plugin
+# Optional, but strongly recommended metadata:
+# title: Human-friendly name (if omitted, tools may fall back to id)
+# author: Name or handle of the plugin author
+# description: Short, human-readable description of what the plugin does
+# homepage: URL for the plugin landing page or README
+# repo: Canonical Git repository URL used for installation/updates
+phase: pre_parse           # or post_render
+priority: 100              # optional, lower runs earlier
+timeout_ms: 0              # optional, 0 = no extra timeout logic (best-effort)
+---
+```
+
+From there, you choose **one of two plugin types**:
+
+- **External handler plugin**
+  - Runs an external command (Ruby, Python, shell, etc.).
+  - Declared with a `handler.command` field.
+- **Declarative regex plugin**
+  - No external code; in-process regex search/replace.
+  - Declared with `pattern` and `replacement` fields.
+
+You can't mix both styles in a single plugin; if `handler.command` is present, the plugin is treated as external.
+
+### Metadata fields for directories and installers
+
+To support plugin directories, automatic installation, and future auto-update tools, Apex understands several **optional metadata fields** in `plugin.yml`:
+
+- **`title`**: Short, human-friendly name for the plugin (e.g. `Keyboard Shortcuts`).
+- **`author`**: Free-form author string (your name, handle, or organization).
+- **`description`**: One–two sentence description of what the plugin does. This is already used in examples and is what directory listings will usually display.
+- **`homepage`**: Informational URL where users can learn more about the plugin—often a README, documentation site, or the GitHub project page. This field is **not** used for cloning, but may be shown in plugin listings.
+- **`repo`**: **Canonical Git URL** for the plugin repository, used by Apex when installing plugins from the central directory (for example, `https://github.com/ApexMarkdown/apex-kbd-plugin.git`). The repository must contain the `plugin.yml` manifest (and any supporting files) at its root.
+- **`post_install`**: Optional command that Apex will run after cloning the plugin during installation. See "Post-install hooks" below.
+
+Only `id`, `phase`, and either `handler.command` (for external plugins) or `pattern`/`replacement` (for declarative plugins) are required for execution—everything else is optional metadata used by tools.
+
+### Post-install hooks (`post_install`)
+
+External plugins can define an optional `post_install` command in `plugin.yml` that Apex will run immediately after installing the plugin:
+
+```yaml
+---
+id: kbd
+# ... other fields ...
+post_install: ./post_install.sh
+---
+```
+
+When you install a plugin, Apex will:
+
+1. Clone or copy the plugin into your user plugin directory (e.g. `~/.config/apex/plugins/kbd`).
+2. Look for `plugin.yml` (or `plugin.yaml`) in the root of that directory.
+3. If it finds a `post_install` key, run the value as a shell command from the plugin directory (equivalent to `cd <plugin_dir> && <post_install>`).
+
+This hook is useful for:
+
+- Creating initial configuration files or support data under `APEX_SUPPORT_DIR`.
+- Printing a welcome or usage message via `echo`.
+- Running an interactive setup script that asks the user questions and writes config.
+
+If the `post_install` command exits with a non-zero status, Apex prints a warning but considers the plugin installed successfully (the installation is not rolled back).
+
+---
+
+## Plugin bundles (`bundle` key)
+
+Sometimes it is convenient for a single repository to provide **multiple related plugins** as a bundle—for example, a "documentation" bundle that contains:
+
+- `kbd` – expands `{% kbd @3 %}` keyboard shortcuts
+- `prefpane` – expands `{% prefspane Advanced, Processor %}`
+- `menubar` – expands `{% menubar File, Open %}`
+
+Instead of creating a separate repo (and `plugin.yml`) for each, Apex supports a **bundle** syntax in `plugin.yml` when built with full YAML (libyaml) support.
+
+### Bundle structure
+
+A **bundle manifest** has:
+
+- Top-level metadata that applies to the bundle as a whole.
+- A `bundle:` key whose value is a YAML sequence (array) of per-plugin configs.
+
+Example:
+
+```yaml
+---
+id: documentation
+title: Documentation helpers
+author: Brett Terpstra
+description: A bundle of documentation-related helpers (kbd, menubar, prefpane).
+homepage: https://github.com/ApexMarkdown/apex-plugin-documentation
+repo: https://github.com/ApexMarkdown/apex-plugin-documentation.git
+
+# Each entry in bundle defines a child plugin
+bundle:
+  - id: kbd
+    title: Keyboard Shortcuts
+    description: Render {% kbd ... %} key combos to HTML <kbd> elements
+    phase: pre_parse
+    priority: 100
+    handler:
+      command: "ruby kbd_plugin.rb"
+
+  - id: menubar
+    title: Menubar Paths
+    description: Render {% menubar File, Open %} to a styled menu path
+    phase: pre_parse
+    handler:
+      command: "ruby menubar_plugin.rb"
+
+  - id: prefspane
+    title: Preferences Pane
+    description: Render {% prefspane Advanced, Processor %} to a styled preference path
+    phase: pre_parse
+    handler:
+      command: "ruby prefspane_plugin.rb"
+---
+```
+
+Apex will treat this as **three distinct plugins**:
+
+- `kbd`
+- `menubar`
+- `prefspane`
+
+all sourced from the same repository and manifest.
+
+### Inheritance and overrides
+
+When loading a bundle, Apex:
+
+1. Parses the top-level mapping (the "bundle header"), and the `bundle:` sequence, using full YAML.
+2. For each entry in `bundle`:
+   - Starts with the **top-level metadata**.
+   - Applies the child entry's fields as **overrides**.
+
+Concretely:
+
+- Top-level `author`, `homepage`, and `repo` are used as defaults for every child plugin.
+- Each child **must** define its own:
+  - `id`
+  - `phase`
+  - and either:
+    - `handler.command` (external plugin), or
+    - `pattern` + `replacement` (declarative plugin)
+- A child **may** also define its own:
+  - `title`
+  - `description`
+  - `priority`
+  - `timeout_ms`
+  - `flags`
+- If a child defines `author`, `homepage`, or `repo`, those values **override** the bundle-level defaults for that child only.
+
+After merging, each child is turned into a normal internal plugin record, just like if it had its own standalone `plugin.yml`.
+
+### Behavior and limitations
+
+- **Discovery**:
+  - Bundle manifests live in the same places as normal plugins:
+    - Project-local: `.apex/plugins/documentation/plugin.yml`
+    - Global: `~/.config/apex/plugins/documentation/plugin.yml`
+- **Phases and IDs**:
+  - Each child plugin's `id` and `phase` are used when registering and running plugins.
+  - All normal rules apply:
+    - IDs must be unique across all loaded plugins.
+    - Phase must be `pre_parse` or `post_render` (for now).
+- **libyaml requirement**:
+  - The `bundle` syntax relies on full YAML parsing via `libyaml`.
+  - If Apex is built **without** libyaml support, `bundle:` is not recognized as a special structure; in that case, you should fall back to separate manifests for each plugin if you need cross-platform behavior on builds that omit libyaml.
+
+---
+
+## External handler plugins (scripts/commands)
+
+An external handler plugin defines a **command** to run, which receives JSON on stdin and writes the transformed text to stdout.
+
+### Manifest fields
+
+```yaml
+---
+id: kbd
+title: Keyboard Shortcuts
+author: Brett Terpstra
+description: Render {% kbd ... %} key combos to HTML
+homepage: https://github.com/ApexMarkdown/apex-kbd-plugin
+repo: https://github.com/ApexMarkdown/apex-kbd-plugin.git
+phase: pre_parse
+priority: 100
+timeout_ms: 0        # optional
+handler:
+  command: "ruby kbd_plugin.rb"
+---
+```
+
+- **`id`**: unique identifier (no spaces recommended).
+- **`title`**/`author`/`description`/`homepage`/`repo`**: optional metadata used by listing/installation tools and plugin directories.
+- **`phase`**: `pre_parse` or `post_render`.
+- **`priority`**: integer; lower runs first.
+- **`timeout_ms`**: optional; host may use this as a soft cap.
+- **`handler.command`**:
+  - Executed via `sh -c` from the plugin's directory (`APEX_PLUGIN_DIR`).
+  - Must be runnable in your environment (e.g. Ruby installed if you use `ruby`).
+
+### JSON protocol
+
+For text phases (`pre_parse`, `post_render`), Apex sends your command a JSON object on **stdin**:
+
+```json
+{
+  "version": 1,
+  "plugin_id": "kbd",
+  "phase": "pre_parse",
+  "text": "raw or rendered text here"
+}
+```
+
+Your plugin should:
+
+1. Read all of stdin.
+2. Parse the JSON.
+3. Transform the `text` field.
+4. Print the **new text only** to stdout (no extra JSON, headers, or logging).
+
+If your plugin fails, times out, or prints nothing, Apex will treat it as a no-op and continue gracefully.
+
+---
+
+## Declarative regex plugins (no scripting)
+
+For many cases, you don't need a script at all. A **declarative regex plugin** uses `regex.h` inside Apex for fast in-process search/replace.
+
+### Manifest fields
+
+```yaml
+---
+id: emoji-span
+title: Emoji span wrapper
+author: Brett Terpstra
+description: Wrap :emoji: markers in a span for styling
+homepage: https://github.com/ApexMarkdown/apex-emoji-plugin
+repo: https://github.com/ApexMarkdown/apex-emoji-plugin.git
+phase: post_render
+pattern: "(:[a-zA-Z0-9_+-]+:)"
+replacement: "<span class=\"emoji\">$1</span>"
+flags: "i"          # optional: e.g. i, m, s
+priority: 200
+timeout_ms: 0
+---
+```
+
+- **`pattern`**: POSIX regular expression (compiled via `regcomp`).
+- **`replacement`**:
+  - Replacement string with capture groups like `$1`, `$2`, etc.
+  - Runs repeatedly across the text until no more matches.
+- **`flags`** (optional):
+  - Currently supports:
+    - `i` – case-insensitive
+    - `m` – multi-line
+    - `s` – dot matches newline (if supported by underlying regex flavor)
+
+This is ideal when:
+
+- You only need straightforward pattern substitution.
+- Performance matters and you want to avoid `fork/exec`.
+
+---
+
+## Support directory and environment variables
+
+Plugins sometimes need a place to store **cache/data files** or know which file is being processed. To keep plugin code directories clean and give plugins enough context, Apex exposes a **support directory** and several environment variables.
+
+### Support directory (`APEX_SUPPORT_DIR`)
+
+Base path:
+
+- If `$XDG_CONFIG_HOME` is set:
+  - `$XDG_CONFIG_HOME/apex/support/`
+- Otherwise:
+  - `~/.config/apex/support/`
+
+For each plugin, Apex creates:
+
+```text
+APEX_SUPPORT_DIR/<plugin-id>/
+```
+
+You can safely write caches, logs, or temporary files there.
+
+### Environment variables for external plugins
+
+When Apex runs an external handler plugin, it sets:
+
+- **`APEX_PLUGIN_DIR`**
+  - Filesystem path to the plugin's directory (where `plugin.yml` lives).
+  - Useful for loading sidecar files, templates, etc.
+
+- **`APEX_SUPPORT_DIR`**
+  - Base support directory as described above.
+  - You'll usually combine it with your plugin id, e.g. `$APEX_SUPPORT_DIR/kbd`.
+
+- **`APEX_FILE_PATH`**
+  - When Apex is invoked on a file, this is the **original path** that was passed. Plugins can use this to make decisions based on path, directory, or extension.
+  - When Apex reads from stdin, `APEX_FILE_PATH` is set to:
+    - The current `base_directory` (if one was set), or
+    - An empty string (`""`) if no base directory is known.
+  - An empty `APEX_FILE_PATH` is a clear signal that there is no concrete source file path.
+
+All of these variables apply only during the external command's execution and are restored afterward.
+
+---
+
+## Installing plugins from the directory
+
+Apex can install plugins directly from a central directory hosted in the `ApexMarkdown/apex-plugins` GitHub repository. The directory is published as a JSON file:
+
+- `https://github.com/ApexMarkdown/apex-plugins` (repository)
+- `https://raw.githubusercontent.com/ApexMarkdown/apex-plugins/refs/heads/main/apex-plugins.json` (JSON index)
+
+Each entry in `apex-plugins.json` looks like this:
+
+```json
+{
+  "plugins": [
+    {
+      "id": "kbd",
+      "title": "Keyboard Shortcuts",
+      "description": "Renders {% kbd %} tags as <kbd> elements.",
+      "author": "Brett Terpstra",
+      "homepage": "https://github.com/ApexMarkdown/apex-plugin-kbd",
+      "repo": "https://github.com/ApexMarkdown/apex-plugin-kbd"
+    }
+  ]
+}
+```
+
+- **`id`** must match the plugin `id` declared in that repo's `plugin.yml`.
+- **`repo`** is the canonical Git URL that Apex will pass to `git clone`.
+- **`title`**, **`author`**, **`description`**, and **`homepage`** are used for human-readable listings.
+
+### Listing available plugins
+
+Marked lists available plugins in the **Plugins panel** within Processor settings. You can see:
+
+- Installed plugins (with their status)
+- Available plugins from the central directory
+- Plugin descriptions and metadata
+
+### Installing a plugin
+
+In Marked, you can install plugins in several ways:
+
+1. **From the Plugins panel**: Browse available plugins and install them with a single click.
+2. **Using Install Plugins**: Select a plugin directory on your disk, and Marked will automatically install it to `~/.config/apex/plugins`.
+3. **From a Git URL**: If you have a plugin repository URL, you can install it directly.
+
+When installing from the central directory, Apex will:
+
+1. Fetch `apex-plugins.json` from the central directory.
+2. Find the entry whose `id` matches the plugin you want.
+3. Read the `repo` field and clone the repository.
+4. Install into `$XDG_CONFIG_HOME/apex/plugins/<id>` or `~/.config/apex/plugins/<id>`.
+
+When installing from a direct URL or local directory:
+
+1. Clone or copy the repository into a temporary directory.
+2. Read `plugin.yml` (or `plugin.yaml`) from the cloned repo to determine the plugin `id`.
+3. Move the cloned directory to the final location: `~/.config/apex/plugins/<id>/`.
+
+If the target directory already exists, Apex will refuse to overwrite it and show an error. You can remove or rename the existing directory and try again.
+
+After successful installation, look for a `post_install` hook in `plugin.yml` and run it if present.
+
+> **Security note:** Apex plugins execute unverified code. Only install plugins from trusted sources.
+
+Once installed, the plugin is just like any other user-global plugin:
+
+- It will be discovered from `$XDG_CONFIG_HOME/apex/plugins` or `~/.config/apex/plugins`.
+- You still need to enable plugins via **Settings->Processor->Include Plugins** or metadata (`plugins: true`).
+
+If you are authoring a plugin for inclusion in the directory:
+
+- Make sure your `plugin.yml` has at least `id`, `phase`, and either `handler.command` or `pattern`/`replacement`.
+- Add `title`, `author`, `description`, `homepage`, and `repo` to `plugin.yml` so directory tools and installers have complete metadata.
+- Ensure the `plugin.yml` and any scripts live at the **root** of the Git repository referenced by `repo`.
+
+### Uninstalling a plugin
+
+To remove a locally installed plugin, use the Plugins panel in Processor settings. You can remove plugins from there, which will:
+
+- Verify that the plugin directory exists under the user plugin path (`$XDG_CONFIG_HOME/apex/plugins` or `~/.config/apex/plugins`).
+- Prompt for confirmation before deleting the plugin directory.
+- Remove only the plugin's directory; support data under `.../apex/support/<plugin-id>/` is left intact.
+
+This only works for plugins installed in the user plugin directory. Project-local plugins (in `.apex/plugins/`) must be removed manually by deleting the plugin directory.
+
+---
+
+## Share Your Plugin
+
+To request that your plugin be added to the central directory:
+
+1. **Fork** the `ApexMarkdown/apex-plugins` repository on GitHub to your own account or organization.
+2. **Clone** your fork locally and create a new branch for your plugin entry (for example, `add-kbd-plugin`).
+3. Open the `apex-plugins.json` file in the root of your fork and add a new object to the `plugins` array with the fields:
+   - `id` (matching the `id` in your plugin's `plugin.yml`),
+   - `title`,
+   - `description`,
+   - `author`,
+   - `homepage`,
+   - `repo` (canonical Git URL for the plugin repo).
+4. Commit your changes and **push** the branch to your fork on GitHub.
+5. From your fork, open a **pull request** against the `main` branch of `ApexMarkdown/apex-plugins`, briefly describing your plugin and confirming that the `id` and `repo` match your published plugin repository.
+6. Once the pull request is reviewed and merged, your plugin will show up in the Plugins panel and be installable via the interface.
+
+---
+
+## Example: `kbd` liquid tag plugin
+
+This example shows how to support a liquid-style `{% kbd ... %}` syntax, turning key combos into `<kbd>` markup.
+
+### Directory layout
+
+Project-local example:
+
+```text
+.apex/
+  plugins/
+    kbd/
+      plugin.yml
+      kbd_plugin.rb
+```
+
+Global example:
+
+```text
+~/.config/apex/plugins/
+  kbd/
+    plugin.yml
+    kbd_plugin.rb
+```
+
+### `plugin.yml`
+
+```yaml
+---
+id: kbd
+title: Keyboard Shortcuts
+author: Brett Terpstra
+description: Render {% kbd ... %} key combos to HTML <kbd> elements
+homepage: https://github.com/ApexMarkdown/apex-kbd-plugin
+repo: https://github.com/ApexMarkdown/apex-kbd-plugin.git
+phase: pre_parse
+priority: 100
+timeout_ms: 0
+handler:
+  command: "ruby kbd_plugin.rb"
+---
+```
+
+### `kbd_plugin.rb` (simplified shape)
+
+The full script lives in the `examples` directory of the Apex repo as a reference. Conceptually, it:
+
+- Reads JSON from stdin.
+- Extracts `text`.
+- Replaces each `{% kbd ... %}` occurrence with properly formatted `<kbd>` HTML.
+- Prints the full transformed text to stdout.
+
+A very abridged sketch:
+
+```ruby
+#!/usr/bin/env ruby
+require "json"
+
+payload = JSON.parse($stdin.read)
+text = payload["text"] || ""
+
+# ... helper methods for normalizing modifier names, etc. ...
+
+def render_kbd(markup)
+  # convert markup like "^~@r" to HTML
+  # returning something like:
+  #   <kbd>⌃</kbd>+<kbd>⌥</kbd>+<kbd>⌘</kbd>+<kbd>R</kbd>
+end
+
+result = text.gsub(/\{%\s*kbd\s+([^%]+)%\}/) do
+  render_kbd(Regexp.last_match(1))
+end
+
+print result
+```
+
+You can customize this script as you like; the only requirement is that it obey the stdin JSON / stdout contract.
+
+---
+
+## Example: `:emoji:` span plugin (declarative)
+
+This plugin turns `:emoji:` tokens in the final HTML into `<span class="emoji">:emoji:</span>`.
+
+### Directory layout
+
+```text
+~/.config/apex/plugins/
+  emoji/
+    plugin.yml
+```
+
+### `plugin.yml`
+
+```yaml
+---
+id: emoji-span
+title: Emoji span wrapper
+author: Brett Terpstra
+description: Wrap :emoji: markers in a span for styling
+homepage: https://github.com/ApexMarkdown/apex-emoji-plugin
+repo: https://github.com/ApexMarkdown/apex-emoji-plugin.git
+phase: post_render
+pattern: "(:[a-zA-Z0-9_+-]+:)"
+replacement: "<span class=\"emoji\">$1</span>"
+flags: "i"
+priority: 200
+timeout_ms: 0
+---
+```
+
+Because this is a declarative plugin, **no external command is run**. Apex compiles the regex and runs the replacements internally.
+
+---
+
+## Putting it all together
+
+A typical workflow:
+
+1. **Create a plugin directory**
+   - Project-local: `.apex/plugins/my-plugin/`
+   - Or global: `~/.config/apex/plugins/my-plugin/`
+
+2. **Add `plugin.yml`**
+   - Choose `phase` (`pre_parse` or `post_render`).
+   - Choose plugin type:
+     - External: add `handler.command`.
+     - Declarative: add `pattern`, `replacement`, and optional `flags`.
+   - Optionally, add metadata fields (`title`, `author`, `description`, `homepage`, `repo`) so your plugin shows up nicely in directories and can be auto-installed.
+   - For bundles, use `bundle:` to define multiple related child plugins in one manifest.
+
+3. **Add code (if external)**
+   - Put your script alongside `plugin.yml`.
+   - Implement the JSON stdin → text stdout contract.
+
+4. **Enable plugins**
+   - Enable **Settings->Processor->Include Plugins**, **or**
+   - Add `plugins: true` (or `enable-plugins: true`) to your document metadata.
+
+5. **Test**
+   - Open a sample document that exercises your plugin syntax in Marked.
+   - If something goes wrong, log to a file under `$APEX_SUPPORT_DIR/<id>/` rather than printing debugging output to stdout.
+
+Once you're comfortable, you can share the `plugin.yml` plus any scripts with others; they just need to drop the directory into their `.apex/plugins/` or `~/.config/apex/plugins/` and enable plugins as needed.