apex-ruby 1.0.6

data/ext/apex_ext/apex_src/man/apex-config.5.md

@@ -0,0 +1,260 @@
+% APEX-CONFIG(5)
+% Brett Terpstra
+% December 2025
+
+# NAME
+
+apex-config - Apex configuration file format
+
+# DESCRIPTION
+
+Apex supports flexible configuration through metadata files that allow you to define defaults once and reuse them across many documents, while still allowing per-document and per-invocation overrides.
+
+Configuration can come from three main sources:
+
+1. **Global configuration file** - `$XDG_CONFIG_HOME/apex/config.yml` or `~/.config/apex/config.yml`
+2. **External metadata files** - Any file passed via `--meta-file`
+3. **Per-document metadata** - YAML, MultiMarkdown, or Pandoc-style metadata in the document
+
+Command-line flags always override configuration file settings.
+
+# GLOBAL CONFIG FILE
+
+When you run **apex**(1) without an explicit `--meta-file`, Apex automatically checks for a global configuration file:
+
+- If `$XDG_CONFIG_HOME` is set: `$XDG_CONFIG_HOME/apex/config.yml`
+- Otherwise: `~/.config/apex/config.yml`
+
+If the file exists, Apex loads it as if you had passed it via `--meta-file`, and merges its metadata with the document and any `--meta` command-line metadata.
+
+This makes `config.yml` ideal for defining project-agnostic defaults such as:
+
+- Default `mode` (e.g. `unified`, `gfm`, `mmd`)
+- Default `language` and `quoteslanguage`
+- Common feature flags (`pretty`, `standalone`, `indices`, `wikilinks`, etc.)
+- Default bibliography style
+
+## Example `config.yml`
+
+```yaml
+---
+# Default processor mode and output style
+mode: unified
+standalone: true
+pretty: true
+
+# Locale and quotation style
+language: en
+quoteslanguage: english
+
+# Common feature flags
+autolink: true
+includes: true
+relaxed-tables: true
+sup-sub: true
+
+# Index and bibliography defaults
+indices: true
+group-index-by-letter: true
+bibliography: references.bib
+csl: apa.csl
+
+# Syntax highlighting (optional)
+code-highlight: pygments
+code-line-numbers: true
+highlight-language-only: true
+---
+```
+
+# EXTERNAL METADATA FILES
+
+For project-specific or task-specific configurations, use `--meta-file` to point to a reusable metadata file:
+
+    apex document.md --meta-file project-defaults.yml
+
+These files use the same metadata keys as `config.yml` and document front matter.
+
+## Example project config
+
+```yaml
+---
+mode: unified
+standalone: true
+pretty: true
+
+# Project-specific bibliography
+bibliography: project-refs.bib
+csl: chicago-note-bibliography.csl
+
+# Enable wiki links and relaxed tables for this project
+wikilinks: true
+relaxed-tables: true
+---
+```
+
+# PER-DOCUMENT METADATA
+
+Each document can define its own metadata in YAML, MultiMarkdown, or Pandoc formats. Apex extracts this metadata before processing, merges it with any file/config metadata, and then applies it to options.
+
+## YAML front matter example
+
+```markdown
+---
+title: My Research Paper
+author: Jane Doe
+mode: unified
+standalone: true
+pretty: true
+indices: false
+wikilinks: true
+bibliography: references.bib
+language: en
+quoteslanguage: english
+---
+
+# Introduction
+...
+```
+
+## MultiMarkdown metadata example
+
+```markdown
+Title: My Research Paper
+Author: Jane Doe
+Mode: unified
+Standalone: true
+Pretty: true
+Indices: false
+WikiLinks: true
+Bibliography: references.bib
+Language: en
+Quotes Language: english
+
+# Introduction
+...
+```
+
+Apex normalizes keys (case-insensitive, ignores spaces and dashes), so `Quotes Language`, `quoteslanguage`, and `quotes-language` are treated equivalently.
+
+# PRECEDENCE AND MERGING
+
+When Apex builds the final configuration for a run, it merges all sources in this order:
+
+1. **File metadata** (lowest precedence)
+   - Global `config.yml` if present and no explicit `--meta-file` was given
+   - Any metadata file provided via `--meta-file`
+2. **Document metadata**
+   - YAML/MultiMarkdown/Pandoc metadata inside the document
+3. **Command-line metadata**
+   - Values passed via `--meta KEY=VALUE`
+4. **Command-line flags**
+   - Flags like `--mode`, `--pretty`, `--no-tables`, etc.
+
+Later sources override earlier ones. In practice:
+
+- A document can override defaults from `config.yml` or `--meta-file`
+- `--meta` values can override both document and file metadata
+- Explicit CLI flags still behave as final overrides where applicable
+
+**Note:** If `mode` is specified in metadata (file or document), Apex resets options to that mode's defaults before applying other metadata keys, so the mode behaves as if you had passed it on the command line first.
+
+# CONFIGURATION KEYS
+
+Configuration keys correspond closely to Apex command-line options. Most options can be controlled via metadata in `config.yml`, `--meta-file` files, or per-document metadata.
+
+## Boolean options
+
+Boolean keys accept any of the following values (case-insensitive):
+
+- `true` / `false`
+- `yes` / `no`
+- `1` / `0`
+
+**Supported boolean keys include:**
+
+- `indices` - Enable index processing
+- `wikilinks` - Enable wiki link syntax (`[[Page]]`)
+- `wikilink-sanitize` - Sanitize wiki link URLs (lowercase, remove apostrophes, clean non-alphanumeric)
+- `includes` - Enable file inclusion
+- `relaxed-tables` - Enable relaxed table parsing
+- `alpha-lists` - Enable alphabetic list markers
+- `mixed-lists` - Allow mixing list marker types at the same level
+- `sup-sub` - Enable MultiMarkdown-style superscript/subscript
+- `autolink` - Enable automatic URL/email linking
+- `transforms` - Enable metadata transforms (`[%key:transform]`)
+- `unsafe` - Allow raw HTML in output
+- `tables` - Enable/disable table support
+- `footnotes` - Enable/disable footnote support
+- `smart` - Enable/disable smart typography
+- `math` - Enable/disable math support
+- `ids` - Enable/disable automatic header IDs
+- `header-anchors` - Use `<a>` anchors instead of plain `id` attributes
+- `embed-images` - Enable base64 image embedding
+- `link-citations` - Link citations to bibliography entries
+- `show-tooltips` - Add tooltips to citations
+- `suppress-bibliography` - Suppress bibliography output
+- `suppress-index` - Suppress index output while still creating markers
+- `group-index-by-letter` - Group index entries alphabetically
+- `obfuscate-emails` - Hex-encode `mailto:` links and visible email addresses
+- `pretty` - Pretty-print HTML
+- `standalone` - Generate a full HTML document (`<html>`, `<head>`, `<body>`)
+- `hardbreaks` - Treat newlines as `<br>`
+- `plugins` - Enable plugin processing (see **apex-plugins**(7))
+- `code-line-numbers` - Include line numbers in syntax-highlighted code blocks
+- `highlight-language-only` - Only highlight code blocks that have a language specified
+
+## String options
+
+String keys take a free-form string value (sometimes with a constrained set of options):
+
+- `mode`
+  - Values: `commonmark`, `gfm`, `mmd`/`multimarkdown`, `kramdown`, `unified`
+- `id-format`
+  - Values: `gfm`, `mmd`, `kramdown`
+- `title`
+  - Document title (used especially in standalone mode)
+- `style` / `css`
+  - Stylesheet path for standalone documents
+- `base-dir`
+  - Base directory used for resolving relative paths (images, includes, etc.)
+- `bibliography`
+  - Path to a bibliography file (`.bib`, `.json`, `.yml`, `.yaml`)
+- `csl`
+  - Path to a CSL style file
+- `language`
+  - BCP 47 or similar language tag (e.g. `en`, `en-US`, `fr`); sets the HTML `lang` attribute
+- `quoteslanguage` / `Quotes Language`
+  - Human-readable language name used for quote styling (e.g. `english`, `french`, `german`)
+- `code-highlight`
+  - External syntax highlighting tool: `pygments` (or `p`/`pyg`), `skylighting` (or `s`/`sky`), or `false`/`none` to disable
+
+You can also use arbitrary keys for your own templates and transforms; Apex simply passes them through to the metadata system so they can be referenced via `[%key]` and `[%key:transform]`.
+
+# EXAMPLES
+
+A typical setup might look like this:
+
+1. **Global defaults** in `config.yml` for your overall writing style and locale.
+2. **Project config** via `--meta-file project.yml` for bibliography and project-specific settings.
+3. **Per-document metadata** for title, author, and any exceptions to the defaults.
+4. Occasional **CLI overrides** for ad-hoc one-off changes (e.g. `--mode gfm` for a specific run).
+
+Because all three configuration layers use the same metadata keys, you can gradually refine behavior without repeating yourself:
+
+- Put long-lived, cross-project settings in `config.yml`
+- Put project-scoped settings in `--meta-file` configs
+- Put document-specific settings in front matter
+
+# SEE ALSO
+
+**apex**(1), **apex-plugins**(7)
+
+For complete documentation, see the [Apex Wiki](https://github.com/ttscoff/apex/wiki).
+
+# AUTHOR
+
+Brett Terpstra
+
+# COPYRIGHT
+
+Copyright (c) 2025 Brett Terpstra. Licensed under MIT License.

data/ext/apex_ext/apex_src/man/apex-plugins.7

@@ -0,0 +1,456 @@
+.\" Automatically generated by Pandoc 3.8.3
+.\"
+.TH "APEX\-PLUGINS" "7" "December 2025" ""
+.SH NAME
+apex\-plugins \- Apex plugin system for extending Markdown processing
+.SH DESCRIPTION
+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.
+.PP
+Plugins are disabled by default so Apex\(cqs performance and behavior
+are unchanged unless you explicitly opt in.
+.SH ENABLING PLUGINS
+.SS Command\-line flags
+.IP \(bu 2
+\f[B]Enable plugins\f[R]: \f[CR]apex \-\-plugins input.md\f[R]
+.IP \(bu 2
+\f[B]Disable plugins\f[R]: \f[CR]apex \-\-no\-plugins input.md\f[R]
+.SS Metadata keys
+In the document\(cqs front matter, any of these keys are recognized
+(case\-insensitive):
+.IP \(bu 2
+\f[CR]plugins\f[R]
+.IP \(bu 2
+\f[CR]enable\-plugins\f[R]
+.IP \(bu 2
+\f[CR]enable_plugins\f[R]
+.PP
+Example:
+.IP
+.EX
+\-\-\-
+title\f[B]:\f[R] Plugin demo
+plugins\f[B]:\f[R] true
+\-\-\-
+.EE
+.SS Precedence
+If metadata enables or disables plugins, you can still override it from
+the CLI:
+.IP \(bu 2
+\f[CR]\-\-plugins\f[R] forces plugins \f[B]on\f[R]
+.IP \(bu 2
+\f[CR]\-\-no\-plugins\f[R] forces plugins \f[B]off\f[R]
+.PP
+CLI flags always win over metadata.
+.SH PLUGIN LOCATIONS
+Plugins are discovered from two locations, in this order:
+.IP "1." 3
+\f[B]Project\-local plugins\f[R]
+.RS 4
+.IP \(bu 2
+Directory: \f[CR].apex/plugins/\f[R] in the same project as your
+documents
+.IP \(bu 2
+Structure: one subdirectory per plugin, for example:
+.RS 2
+.IP \(bu 2
+\f[CR].apex/plugins/kbd/plugin.yml\f[R]
+.IP \(bu 2
+\f[CR].apex/plugins/kbd/kbd_plugin.rb\f[R]
+.RE
+.RE
+.IP "2." 3
+\f[B]Global (user) plugins\f[R]
+.RS 4
+.IP \(bu 2
+If \f[CR]$XDG_CONFIG_HOME\f[R] is set:
+\f[CR]$XDG_CONFIG_HOME/apex/plugins/\f[R]
+.IP \(bu 2
+Otherwise: \f[CR]\(ti/.config/apex/plugins/\f[R]
+.IP \(bu 2
+Same structure: one subdirectory per plugin
+.RE
+.PP
+\f[B]Plugin IDs must be unique.\f[R] If a project plugin and a global
+plugin share the same \f[CR]id\f[R], the project plugin wins and the
+global one is ignored.
+.SH PROCESSING PHASES
+Apex exposes several phases in its pipeline.
+Plugins can hook into one or more phases:
+.IP \(bu 2
+\f[B]\f[CB]pre_parse\f[B]\f[R]
+.RS 2
+.IP \(bu 2
+Runs on the raw Markdown text before it is parsed.
+.IP \(bu 2
+Good for: custom syntax (e.g.\ \f[CR]{% kbd ... %}\f[R]), textual
+rewrites, adding/removing markup before Apex sees it
+.RE
+.IP \(bu 2
+\f[B]\f[CB]post_render\f[B]\f[R]
+.RS 2
+.IP \(bu 2
+Runs on the final HTML output after Apex finishes rendering.
+.IP \(bu 2
+Good for: wrapping elements in spans/divs, adding CSS classes, simple
+HTML post\-processing (e.g.\ turning \f[CR]:emoji:\f[R] into
+\f[CR]<span>\f[R])
+.RE
+.PP
+Internally, plugins for each phase are run in a deterministic order:
+.IP "1." 3
+Sorted by priority (lower numbers first; default is \f[CR]100\f[R]).
+.IP "2." 3
+Ties broken by plugin \f[CR]id\f[R] (lexicographically).
+.SH PLUGIN MANIFEST
+Each plugin is defined by a manifest file:
+.IP \(bu 2
+\f[B]File name\f[R]: \f[CR]plugin.yml\f[R]
+.IP \(bu 2
+\f[B]Location\f[R]: inside the plugin\(cqs directory
+.PP
+At minimum, a plugin needs:
+.IP
+.EX
+\-\-\-
+id\f[B]:\f[R] my\-plugin
+phase\f[B]:\f[R] pre_parse\f[I]           # or post_render\f[R]
+priority\f[B]:\f[R] 100\f[I]              # optional, lower runs earlier\f[R]
+\-\-\-
+.EE
+.PP
+From there, you choose one of two plugin types:
+.IP \(bu 2
+\f[B]External handler plugin\f[R] \- Runs an external command (Ruby,
+Python, shell, etc.).
+Declared with a \f[CR]handler.command\f[R] field.
+.IP \(bu 2
+\f[B]Declarative regex plugin\f[R] \- No external code; in\-process
+regex search/replace.
+Declared with \f[CR]pattern\f[R] and \f[CR]replacement\f[R] fields.
+.PP
+You can\(cqt mix both styles in a single plugin; if
+\f[CR]handler.command\f[R] is present, the plugin is treated as
+external.
+.SS Metadata fields
+To support plugin directories, automatic installation, and future
+auto\-update tools, Apex understands several optional metadata fields in
+\f[CR]plugin.yml\f[R]:
+.IP \(bu 2
+\f[B]\f[CB]title\f[B]\f[R]: Short, human\-friendly name for the plugin
+.IP \(bu 2
+\f[B]\f[CB]author\f[B]\f[R]: Free\-form author string
+.IP \(bu 2
+\f[B]\f[CB]description\f[B]\f[R]: One\-two sentence description of what
+the plugin does
+.IP \(bu 2
+\f[B]\f[CB]homepage\f[B]\f[R]: Informational URL where users can learn
+more about the plugin
+.IP \(bu 2
+\f[B]\f[CB]repo\f[B]\f[R]: Canonical Git URL for the plugin repository,
+used by Apex when installing plugins
+.IP \(bu 2
+\f[B]\f[CB]post_install\f[B]\f[R]: Optional command that Apex will run
+after cloning the plugin during \f[CR]\-\-install\-plugin\f[R]
+.PP
+Only \f[CR]id\f[R], \f[CR]phase\f[R], and either
+\f[CR]handler.command\f[R] (for external plugins) or
+\f[CR]pattern\f[R]/\f[CR]replacement\f[R] (for declarative plugins) are
+required for execution.
+.SH EXTERNAL HANDLER PLUGINS
+An external handler plugin defines a command to run, which receives JSON
+on stdin and writes the transformed text to stdout.
+.SS Manifest example
+.IP
+.EX
+\-\-\-
+id\f[B]:\f[R] kbd
+title\f[B]:\f[R] Keyboard Shortcuts
+author\f[B]:\f[R] Brett Terpstra
+description\f[B]:\f[R] Render {% kbd ... %} key combos to HTML
+homepage\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-kbd\-plugin
+repo\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-kbd\-plugin.git
+phase\f[B]:\f[R] pre_parse
+priority\f[B]:\f[R] 100
+timeout_ms\f[B]:\f[R] 0\f[I]        # optional\f[R]
+handler\f[B]:\f[R]
+  command\f[B]:\f[R] \(dqruby kbd_plugin.rb\(dq
+\-\-\-
+.EE
+.SS JSON protocol
+For text phases (\f[CR]pre_parse\f[R], \f[CR]post_render\f[R]), Apex
+sends your command a JSON object on stdin:
+.IP
+.EX
+{
+  \(dqversion\(dq: 1,
+  \(dqplugin_id\(dq: \(dqkbd\(dq,
+  \(dqphase\(dq: \(dqpre_parse\(dq,
+  \(dqtext\(dq: \(dqraw or rendered text here\(dq
+}
+.EE
+.PP
+Your plugin should:
+.IP "1." 3
+Read all of stdin.
+.IP "2." 3
+Parse the JSON.
+.IP "3." 3
+Transform the \f[CR]text\f[R] field.
+.IP "4." 3
+Print the new text only to stdout (no extra JSON, headers, or logging).
+.PP
+If your plugin fails, times out, or prints nothing, Apex will treat it
+as a no\-op and continue gracefully.
+.SH DECLARATIVE REGEX PLUGINS
+For many cases, you don\(cqt need a script at all.
+A declarative regex plugin uses \f[CR]regex.h\f[R] inside Apex for fast
+in\-process search/replace.
+.SS Manifest example
+.IP
+.EX
+\-\-\-
+id\f[B]:\f[R] emoji\-span
+title\f[B]:\f[R] Emoji span wrapper
+author\f[B]:\f[R] Brett Terpstra
+description\f[B]:\f[R] Wrap :emoji: markers in a span for styling
+homepage\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-emoji\-plugin
+repo\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-emoji\-plugin.git
+phase\f[B]:\f[R] post_render
+pattern\f[B]:\f[R] \(dq(:[a\-zA\-Z0\-9_+\-]+:)\(dq
+replacement\f[B]:\f[R] \(dq<span class=\(rs\(dqemoji\(rs\(dq>$1</span>\(dq
+flags\f[B]:\f[R] \(dqi\(dq\f[I]          # optional: e.g. i, m, s\f[R]
+priority\f[B]:\f[R] 200
+timeout_ms\f[B]:\f[R] 0
+\-\-\-
+.EE
+.IP \(bu 2
+\f[B]\f[CB]pattern\f[B]\f[R]: POSIX regular expression (compiled via
+\f[CR]regcomp\f[R]).
+.IP \(bu 2
+\f[B]\f[CB]replacement\f[B]\f[R]: Replacement string with capture groups
+like \f[CR]$1\f[R], \f[CR]$2\f[R], etc.
+Runs repeatedly across the text until no more matches.
+.IP \(bu 2
+\f[B]\f[CB]flags\f[B]\f[R] (optional): Currently supports \f[CR]i\f[R]
+(case\-insensitive), \f[CR]m\f[R] (multi\-line), \f[CR]s\f[R] (dot
+matches newline).
+.PP
+This is ideal when you only need straightforward pattern substitution
+and performance matters.
+.SH PLUGIN BUNDLES
+Sometimes it is convenient for a single repository to provide multiple
+related plugins as a bundle.
+Apex supports a bundle syntax in \f[CR]plugin.yml\f[R] when built with
+full YAML (libyaml) support.
+.SS Bundle structure
+A bundle manifest has:
+.IP \(bu 2
+Top\-level metadata that applies to the bundle as a whole.
+.IP \(bu 2
+A \f[CR]bundle:\f[R] key whose value is a YAML sequence (array) of
+per\-plugin configs.
+.PP
+Example:
+.IP
+.EX
+\-\-\-
+id\f[B]:\f[R] documentation
+title\f[B]:\f[R] Documentation helpers
+author\f[B]:\f[R] Brett Terpstra
+description\f[B]:\f[R] A bundle of documentation\-related helpers
+homepage\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-plugin\-documentation
+repo\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-plugin\-documentation.git
+
+bundle\f[B]:\f[R]
+  \f[B]\-\f[R] id\f[B]:\f[R] kbd
+    title\f[B]:\f[R] Keyboard Shortcuts
+    description\f[B]:\f[R] Render {% kbd ... %} key combos to HTML <kbd> elements
+    phase\f[B]:\f[R] pre_parse
+    priority\f[B]:\f[R] 100
+    handler\f[B]:\f[R]
+      command\f[B]:\f[R] \(dqruby kbd_plugin.rb\(dq
+
+  \f[B]\-\f[R] id\f[B]:\f[R] menubar
+    title\f[B]:\f[R] Menubar Paths
+    description\f[B]:\f[R] Render {% menubar File, Open %} to a styled menu path
+    phase\f[B]:\f[R] pre_parse
+    handler\f[B]:\f[R]
+      command\f[B]:\f[R] \(dqruby menubar_plugin.rb\(dq
+\-\-\-
+.EE
+.PP
+Apex will treat this as three distinct plugins: \f[CR]kbd\f[R],
+\f[CR]menubar\f[R], and \f[CR]prefspane\f[R], all sourced from the same
+repository and manifest.
+.SH ENVIRONMENT VARIABLES
+When Apex runs an external handler plugin, it sets:
+.IP \(bu 2
+\f[B]\f[CB]APEX_PLUGIN_DIR\f[B]\f[R]
+.RS 2
+.IP \(bu 2
+Filesystem path to the plugin\(cqs directory (where
+\f[CR]plugin.yml\f[R] lives).
+.IP \(bu 2
+Useful for loading sidecar files, templates, etc.
+.RE
+.IP \(bu 2
+\f[B]\f[CB]APEX_SUPPORT_DIR\f[B]\f[R]
+.RS 2
+.IP \(bu 2
+Base support directory: \f[CR]$XDG_CONFIG_HOME/apex/support/\f[R] or
+\f[CR]\(ti/.config/apex/support/\f[R]
+.IP \(bu 2
+For each plugin, Apex creates: \f[CR]APEX_SUPPORT_DIR/<plugin\-id>/\f[R]
+.IP \(bu 2
+You can safely write caches, logs, or temporary files there.
+.RE
+.IP \(bu 2
+\f[B]\f[CB]APEX_FILE_PATH\f[B]\f[R]
+.RS 2
+.IP \(bu 2
+When Apex is invoked on a file, this is the original path that was
+passed on the command line.
+.IP \(bu 2
+When Apex reads from stdin, \f[CR]APEX_FILE_PATH\f[R] is set to the
+current \f[CR]base_directory\f[R] (if one was set) or an empty string.
+.RE
+.PP
+All of these variables apply only during the external command\(cqs
+execution and are restored afterward.
+.SH INSTALLING PLUGINS
+Apex can install plugins directly from a central directory or from Git
+URLs.
+.SS Listing available plugins
+.IP
+.EX
+apex \-\-list\-plugins
+.EE
+.PP
+This command fetches the plugin directory and prints a listing of
+installed and available plugins.
+.SS Installing a plugin
+The \f[CR]\-\-install\-plugin\f[R] command accepts three types of
+arguments:
+.IP "1." 3
+\f[B]Plugin ID from the directory\f[R] (recommended for curated
+plugins):
+.RS 4
+.IP
+.EX
+apex \-\-install\-plugin kbd
+.EE
+.RE
+.IP "2." 3
+\f[B]Full Git URL\f[R] (for plugins not in the directory):
+.RS 4
+.IP
+.EX
+apex \-\-install\-plugin https://github.com/ttscoff/apex\-plugin\-kbd.git
+.EE
+.RE
+.IP "3." 3
+\f[B]GitHub shorthand\f[R] (\f[CR]user/repo\f[R] format):
+.RS 4
+.IP
+.EX
+apex \-\-install\-plugin ttscoff/apex\-plugin\-kbd
+.EE
+.RE
+.PP
+When installing from a direct Git URL or GitHub shorthand (i.e.,
+anything outside the curated directory), Apex will prompt for
+confirmation since plugins execute unverified code.
+.SS Uninstalling a plugin
+.IP
+.EX
+apex \-\-uninstall\-plugin kbd
+.EE
+.PP
+The \f[CR]\-\-uninstall\-plugin\f[R] command verifies that the plugin
+directory exists, prompts for confirmation, and removes the plugin\(cqs
+directory.
+Support data under \f[CR].../apex/support/<plugin\-id>/\f[R] is left
+intact.
+.PP
+This command only works for plugins installed in the user plugin
+directory.
+Project\-local plugins (in \f[CR].apex/plugins/\f[R]) must be removed
+manually.
+.SH EXAMPLES
+.SS Example: \f[CR]kbd\f[R] liquid tag plugin
+This example shows how to support a liquid\-style
+\f[CR]{% kbd ... %}\f[R] syntax, turning key combos into
+\f[CR]<kbd>\f[R] markup.
+.SS Directory layout
+.IP
+.EX
+\&.apex/
+  plugins/
+    kbd/
+      plugin.yml
+      kbd_plugin.rb
+.EE
+.SS \f[CR]plugin.yml\f[R]
+.IP
+.EX
+\-\-\-
+id\f[B]:\f[R] kbd
+title\f[B]:\f[R] Keyboard Shortcuts
+author\f[B]:\f[R] Brett Terpstra
+description\f[B]:\f[R] Render {% kbd ... %} key combos to HTML <kbd> elements
+homepage\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-kbd\-plugin
+repo\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-kbd\-plugin.git
+phase\f[B]:\f[R] pre_parse
+priority\f[B]:\f[R] 100
+timeout_ms\f[B]:\f[R] 0
+handler\f[B]:\f[R]
+  command\f[B]:\f[R] \(dqruby kbd_plugin.rb\(dq
+\-\-\-
+.EE
+.PP
+The Ruby script reads JSON from stdin, extracts \f[CR]text\f[R],
+replaces each \f[CR]{% kbd ... %}\f[R] occurrence with properly
+formatted \f[CR]<kbd>\f[R] HTML, and prints the full transformed text to
+stdout.
+.SS Example: \f[CR]:emoji:\f[R] span plugin (declarative)
+This plugin turns \f[CR]:emoji:\f[R] tokens in the final HTML into
+\f[CR]<span class=\(dqemoji\(dq>:emoji:</span>\f[R].
+.SS \f[CR]plugin.yml\f[R]
+.IP
+.EX
+\-\-\-
+id\f[B]:\f[R] emoji\-span
+title\f[B]:\f[R] Emoji span wrapper
+author\f[B]:\f[R] Brett Terpstra
+description\f[B]:\f[R] Wrap :emoji: markers in a span for styling
+homepage\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-emoji\-plugin
+repo\f[B]:\f[R] https://github.com/ApexMarkdown/apex\-emoji\-plugin.git
+phase\f[B]:\f[R] post_render
+pattern\f[B]:\f[R] \(dq(:[a\-zA\-Z0\-9_+\-]+:)\(dq
+replacement\f[B]:\f[R] \(dq<span class=\(rs\(dqemoji\(rs\(dq>$1</span>\(dq
+flags\f[B]:\f[R] \(dqi\(dq
+priority\f[B]:\f[R] 200
+timeout_ms\f[B]:\f[R] 0
+\-\-\-
+.EE
+.PP
+Because this is a declarative plugin, no external command is run.
+Apex compiles the regex and runs the replacements internally.
+.SH SEE ALSO
+\f[B]apex\f[R](1), \f[B]apex\-config\f[R](5)
+.PP
+For complete documentation, see the \c
+.UR https://github.com/ttscoff/apex/wiki
+Apex Wiki
+.UE \c
+\&.
+.SH AUTHOR
+Brett Terpstra
+.SH COPYRIGHT
+Copyright (c) 2025 Brett Terpstra.
+Licensed under MIT License.
+.SH AUTHORS
+Brett Terpstra.