apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/man/apex.1

@@ -42,7 +42,17 @@ If \fR$APEX_PAGER\f[] is set and non\-empty, Apex uses its value as the pager.
 Otherwise, if \fR$PAGER\f[] is set and non\-empty, Apex uses that.
 
 .IP \(bu 2
-Otherwise, Apex falls back to \fRless \-R\f[]. Pagination is ignored when the output format is not a terminal format or when \fR\-o/\-\-output\f[] is used to write to a file. You can also enable pagination via metadata or config by setting \fRpaginate: true\f[].
+Otherwise, Apex falls back to \fRless \-R\f[]. Pagination is ignored when the output format is not a terminal format or when \fR\-o/\-\-output\f[] is used to write to a file. You can also enable pagination via metadata or config by setting \fRpaginate: true\f[]. When pagination is enabled and the rendered output contains inline terminal graphics (iTerm \f[B]imgcat\f[] / OSC 1337 sequences or Kitty graphics), Apex automatically skips the pager and writes directly to stdout, because \f[B]\fRless \-R\f[]\f[] and most pagers only support ANSI color, not inline image protocols. A short notice is printed to stderr.
+
+.TP
+\f[B]\-\-paginate\-symbols\f[]
+Page terminal output (same pager selection as \f[B]\-\-paginate\f[]) and render
+Markdown images as \f[B]chafa\f[] ANSI block art (\fRchafa \-f symbols\f[]) so images display correctly in \f[B]\fRless \-R\f[]\f[]. Requires \f[B]chafa\f[] on \f[B]PATH\f[]. With \f[B]\-\-to terminal256\f[], Apex passes \fR\-c 256\f[] to chafa; with \f[B]\-\-to terminal\f[], \fR\-c 16\f[]. Equivalent to metadata \fRpaginate: symbols\f[]. Implies pagination is enabled.
+
+.TP
+\f[B]\-\-no\-paginate\f[]
+Do not page terminal output. Overrides \f[B]\-p\f[] / \f[B]\-\-paginate\f[] and
+\fRpaginate: true\f[] or \fRpaginate: symbols\f[] from metadata or config.
 
 .TP
 \f[B]\-\-theme\f[] NAME
@@ -54,7 +64,20 @@ Disable inline terminal rendering of Markdown images for \f[B]\-\-to terminal\f[
 
 .TP
 \f[B]\-\-terminal\-image\-width\f[] N
-Maximum width in character cells passed to the image viewer (default: 50). The first of \f[B]imgcat\f[], \f[B]chafa\f[], \f[B]viu\f[], \f[B]catimg\f[] found on \f[B]PATH\f[] is used, in that order. For \fRhttp://\f[] and \fRhttps://\f[] image URLs, Apex downloads with \f[B]curl\f[] (60 second timeout, 10 MiB maximum size) to a file under \f[B]$TMPDIR\f[] or \fR/tmp\f[], then displays it. If \f[B]curl\f[] is missing, download fails, no viewer is found, \f[B]stdout\f[] is not a TTY, or \f[B]\-\-no\-terminal\-images\f[] is set, images are emitted as styled link text and URL (like hyperlinks), not as Markdown \fR![alt](url)\f[] syntax.
+Maximum width in character cells passed to the image viewer (default: 50).
+When \f[B]stdout\f[] is a TTY and inline images are enabled, Apex selects a viewer on \f[B]PATH\f[] as follows:
+
+.IP \(bu 2
+\f[B]imgcat\f[] \[em] only when \f[B]TERM_PROGRAM\f[] indicates iTerm2 (iTerm inline\-image protocol).
+
+.IP \(bu 2
+\f[B]chafa\f[] \[em] otherwise, if available (\fR\-f\f[] format depends on terminal: \f[B]iterm\f[] on iTerm/WezTerm, \f[B]kitty\f[] on Kitty, \f[B]symbols\f[] on other terminals).
+
+.IP \(bu 2
+\f[B]catimg\f[] \[em] if chafa is not found.
+
+.IP \(bu 2
+\f[B]viu\f[] \[em] if neither chafa nor catimg is found. For \fRhttp://\f[] and \fRhttps://\f[] image URLs, Apex downloads with \f[B]curl\f[] (60 second timeout, 10 MiB maximum size) to a file under \f[B]$TMPDIR\f[] or \fR/tmp\f[], then displays it. If \f[B]curl\f[] is missing, download fails, no viewer is found, \f[B]stdout\f[] is not a TTY, or \f[B]\-\-no\-terminal\-images\f[] is set, images are emitted as styled link text and URL (like hyperlinks), not as Markdown \fR![alt](url)\f[] syntax. When \f[B]\-\-paginate\-symbols\f[] or \fRpaginate: symbols\f[] is active, Apex always uses \f[B]chafa\f[] with \fR\-f symbols\f[] for images so pager output remains compatible with \f[B]less \-R\f[].
 
 .TP
 \f[B]\-\-code\-highlight\f[] TOOL
@@ -92,14 +115,13 @@ Pretty\-print HTML with indentation and whitespace.
 .TP
 \f[B]\-\-aria\f[]
 Add ARIA labels and accessibility attributes to HTML
-output. When enabled, adds: \fRaria\-label="Table of contents"\f[] to TOC navigation elements (\fR<nav class="toc">\f[]) \- \fRrole="figure"\f[] to \fR<figure>\f[] elements \- \fRrole="table"\f[] to \fR<table>\f[] elements table figures (if missing)
+output. When enabled, adds: \fRaria\-label="Table of contents"\f[] to TOC navigation elements (\fR<nav class="toc">\f[]) \- \fRrole="figure"\f[] to \fR<figure>\f[] elements \- \fRrole="table"\f[] to \fR<table>\f[] elements \- \fRid\f[] attributes to \fR<figcaption>\f[] elements within table figures (if missing)
 
 .PP
 .nf
 \fR
-\- `id` attributes to `<figcaption>` elements within
-  to their captions
 \- `aria\-describedby` attributes to tables linking them
+  to their captions
 
 \f[]
 .fi
@@ -126,6 +148,9 @@ Output format. One of:
 .IP \(bu 2
 \f[B]markdown\f[], \f[B]md\f[], \f[B]mmd\f[], \f[B]commonmark\f[], \f[B]cmark\f[], \f[B]kramdown\f[], \f[B]gfm\f[] \- Markdown variants
 
+.IP \(bu 2
+\f[B]toc\f[] \- Markdown unordered list of heading links only (default depth \f[B]#\f[]\-\-\f[B]###\f[])
+
 .IP \(bu 2
 \f[B]terminal\f[], \f[B]cli\f[], \f[B]terminal256\f[] \- ANSI\-colored output for TTYs and terminal emulators
 
@@ -133,7 +158,15 @@ Output format. One of:
 \f[B]man\f[] \- Man page roff source (.TH, .SH, etc.)
 
 .IP \(bu 2
-\f[B]man\-html\f[] \- Styled HTML man page (use \f[B]\-\-standalone\f[] for full page with nav sidebar) When using a terminal format, Apex emits ANSI\-colored output suitable for TTYs and terminal emulators.
+\f[B]man\-html\f[] \- Styled HTML man page (use \f[B]\-\-standalone\f[] for full page with nav sidebar)
+
+.IP \(bu 2
+\f[B]rtf\f[] \- Rich Text Format (native writer; write to a \fR.rtf\f[] file for best results) When using a terminal format, Apex emits ANSI\-colored output suitable for TTYs and terminal emulators.
+
+.TP
+\f[B]\-\-toc\-min\-max\f[] MIN,MAX
+Inclusive heading depth for \f[B]\-\-to toc\f[] and for HTML TOC markers without an
+explicit range. The default is \f[B]1,3\f[], which includes headings from \f[B]#\f[] through \f[B]###\f[]. Marker syntax with an explicit range, such as \fR{{TOC:2\-5}}\f[], overrides this setting. Values must satisfy \fR1 <= MIN <= MAX <= 6\f[].
 
 .SS Feature Flags
 
@@ -248,10 +281,7 @@ Enable relaxed table parsing (no separator rows required).
 .SS HTML and Links
 
 .PP
-\fRdash\f[] \- Convert spaces to dashes: \fR[[Home Page]]\f[] → \fRhref="Home\-Page"\f[] \fRnone\f[] \- Remove spaces: \fR[[Home Page]]\f[] → \fRhref="HomePage"\f[] \fRunderscore\f[] \- Convert spaces to underscores: \fR[[Home Page]]\f[] → \fRhref="Home_Page"\f[] Default: \fRdash\f[].
-
-.PP
-\fRspace\f[] \- Keep spaces (rendered as \fR%%20\f[] in HTML): \fR[[Home Page]]\f[] → \fRhref="Home%20Page"\f[]
+\fRdash\f[] \- Convert spaces to dashes: \fR[[Home Page]]\f[] → \fRhref="Home\-Page"\f[] \fRnone\f[] \- Remove spaces: \fR[[Home Page]]\f[] → \fRhref="HomePage"\f[] \fRunderscore\f[] \- Convert spaces to underscores: \fR[[Home Page]]\f[] → \fRhref="Home_Page"\f[] \fRspace\f[] \- Keep spaces (rendered as \fR%%20\f[] in HTML): \fR[[Home Page]]\f[] → \fRhref="Home%20Page"\f[] Default: \fRdash\f[].
 
 .TP
 \f[B]\-\-wikilink\-sanitize\f[], \f[B]\-\-no\-wikilink\-sanitize\f[]
@@ -283,15 +313,7 @@ Removes leading and trailing space\-mode characters For example, with \fR\-\-wik
 .SS Path Resolution
 
 .PP
-\f[B]\-\-base\-dir\f[] \f[I]DIR\f[] :   Base directory for resolving relative paths. Used for: \- Image embedding (with \f[B]\-\-embed\-images\f[]) \- File includes/transclusions when the working directory differs from the document location
-
-.PP
-.nf
-\fR
-\- Relative path resolution when reading from stdin or
-
-\f[]
-.fi
+\f[B]\-\-base\-dir\f[] \f[I]DIR\f[] :   Base directory for resolving relative paths. Used for: \- Image embedding (with \f[B]\-\-embed\-images\f[]) \- File includes/transclusions \- Relative path resolution when reading from stdin or when the working directory differs from the document location
 
 .PP
 If not specified and reading from a file, the base directory is automatically set to the input file's directory. When reading from stdin, this flag must be used to resolve relative paths.
@@ -307,7 +329,7 @@ If not specified and reading from a file, the base directory is automatically se
 aside {.sidebar} … :::\fRcreates an\f[]` element instead). Opening fences must have at least 3 colons and attributes; closing fences need at least 3 colons. Fenced divs can be nested, including different block types. Default: enabled in unified mode only.
 
 
-\f[B]\-\-spans\f[], \f[B]\-\-no\-spans\f[] :   Enable or disable Pandoc\-style bracketed spans syntax (\fR[text]{#id .class key="val"}\f[]). Bracketed spans allow you to create HTML \fR<span>\f[] elements with attributes. The text inside the brackets is processed as markdown. If the bracketed text matches a reference link definition, it will be treated as a link instead of a span. Default: enabled in unified mode only.
+\f[B]\-\-py\-callouts\f[], \f[B]\-\-no\-py\-callouts\f[] :   Enable or disable Python\-Markdown callout syntax (\fR!!! note "Optional Title"\f[] followed by indented content) and markdown\-callouts label syntax (\fRNOTE: ...\f[], \fR>? NOTE: ...\f[] for collapsed callouts). Disabled by default to avoid ambiguity with regular markdown prose. \f[B]\-\-quarto\-callouts\f[], \f[B]\-\-no\-quarto\-callouts\f[] :   Enable or disable Quarto callout syntax using fenced div markers (\fR::: {.callout\-note}\f[] ... \fR:::\f[]). When enabled, recognized Quarto callout blocks bypass generic fenced\-div conversion and are rendered as callouts; non\-callout fenced divs continue to be processed as regular Pandoc fenced divs. \f[B]\-\-spans\f[], \f[B]\-\-no\-spans\f[] :   Enable or disable Pandoc\-style bracketed spans syntax (\fR[text]{#id .class key="val"}\f[]). Bracketed spans allow you to create HTML \fR<span>\f[] elements with attributes. The text inside the brackets is processed as markdown. If the bracketed text matches a reference link definition, it will be treated as a link instead of a span. Default: enabled in unified mode only.
 
 .SS Citations and Bibliography
 
@@ -326,13 +348,16 @@ mmark: \fR[@RFC1234]\f[] Bibliography is inserted at the \fR<!\-\- REFERENCES \-
 .SS Indices
 
 .PP
-\f[B]\-\-indices\f[] syntax. Default: enabled in MultiMarkdown and unified modes.
+\f[B]\-\-concordance\f[] \f[I]FILE\f[] : TextIndex concordance file (tab\-separated). Searches the document for each rule's column\-1 pattern and inserts \fR[match]{^col2}\f[] index marks before TextIndex processing. Can be specified multiple times. Enables indices and TextIndex syntax when used. Matches inside existing index marks, \fR{index}\f[] directives, and HTML tags are skipped. See https://mattgemmell.scot/textindex/#concordance\-files (https://mattgemmell.scot/textindex/#concordance\-files) for the concordance file format.
+
+.PP
+\f[B]\-\-indices\f[] : Enable index processing. Supports both mmark and TextIndex syntax. Default: enabled in MultiMarkdown and unified modes.
 
 .PP
-: Enable index processing. Supports both mmark and TextIndex \f[B]\-\-no\-indices\f[] :   Disable index processing. \f[B]\-\-no\-index\f[] Index markers are still created in the document, but the index section is not generated.
+\f[B]\-\-no\-indices\f[] :   Disable index processing. \f[B]\-\-no\-index\f[] : Suppress index generation at the end of the document. Index markers are still created in the document, but the index section is not generated.
 
 .PP
-: Suppress index generation at the end of the document. Index syntax is supported in MultiMarkdown and unified modes:
+Index syntax is supported in MultiMarkdown and unified modes:
 
 .IP \(bu 2
 \f[B]mmark syntax\f[]: \fR(!item)\f[], \fR(!item, subitem)\f[], \fR(!!item, subitem)\f[] for primary entries
@@ -343,126 +368,100 @@ mmark: \fR[@RFC1234]\f[] Bibliography is inserted at the \fR<!\-\- REFERENCES \-
 .SS AST Filters
 
 .PP
-\f[B]\-\-filter\f[] \f[I]NAME\f[] (\fR$XDG_CONFIG_HOME/apex/filters\f[] or \fR~/.config/apex/filters\f[]). \f[I]NAME\f[] is the basename of an executable that reads Pandoc JSON from stdin and writes Pandoc JSON to stdout.
+\f[B]\-\-filter\f[] \f[I]NAME\f[] : Run a single AST filter from the user filters directory (\fR$XDG_CONFIG_HOME/apex/filters\f[] or \fR~/.config/apex/filters\f[]). \f[I]NAME\f[] is the basename of an executable that reads Pandoc JSON from stdin and writes Pandoc JSON to stdout.
 
 .PP
-: Run a single AST filter from the user filters directory \f[B]\-\-filters\f[] filename order. Directory filters run first if \f[B]\-\-filter\f[] is also used.
+\f[B]\-\-filters\f[] : Run all executable files in the user filters directory, in sorted filename order. Directory filters run first if \f[B]\-\-filter\f[] is also used.
 
 .PP
-: Run all executable files in the user filters directory, in sorted \f[B]\-\-lua\-filter\f[] \f[I]FILE\f[] interpreter with \f[I]FILE\f[]. The script reads a Pandoc JSON document from stdin and must write a Pandoc JSON document to stdout. A JSON library (e.g. dkjson) is required; see the Filters documentation for details.
+\f[B]\-\-lua\-filter\f[] \f[I]FILE\f[] : Run a Lua script as an AST filter. Apex invokes the system \f[B]lua\f[] interpreter with \f[I]FILE\f[]. The script reads a Pandoc JSON document from stdin and must write a Pandoc JSON document to stdout. A JSON library (e.g. dkjson) is required; see the Filters documentation for details.
 
 .PP
-: Run a Lua script as an AST filter. Apex invokes the system \f[B]lua\f[] \f[B]\-\-no\-strict\-filters\f[] warning and continue with the previous AST. Default: abort on error.
+\f[B]\-\-no\-strict\-filters\f[] : Do not abort when a filter fails or returns invalid JSON; log a warning and continue with the previous AST. Default: abort on error.
 
 .PP
-: Do not abort when a filter fails or returns invalid JSON; log a \f[B]\-\-list\-filters\f[] apex\-filters directory. Shows filter IDs; available filters show title, author, description, and homepage.
+\f[B]\-\-list\-filters\f[] : List installed filters and available filters from the central apex\-filters directory. Shows filter IDs; available filters show title, author, description, and homepage.
 
 .PP
-: List installed filters and available filters from the central \f[B]\-\-install\-filter\f[] \f[I]ID\-or\-URL\f[] may be a filter ID from the central apex\-filters directory (e.g. \f[B]unwrap\f[]) or a Git URL / GitHub shorthand. When installing from a URL, Apex may prompt for confirmation.
+\f[B]\-\-install\-filter\f[] \f[I]ID\-or\-URL\f[] : Install an AST filter into the user filters directory. \f[I]ID\-or\-URL\f[] may be a filter ID from the central apex\-filters directory (e.g. \f[B]unwrap\f[]) or a Git URL / GitHub shorthand. When installing from a URL, Apex may prompt for confirmation.
 
 .PP
-: Install an AST filter into the user filters directory. \f[I]ID\-or\-URL\f[] \f[B]\-\-uninstall\-filter\f[] \f[I]ID\f[] from the user filters directory. Apex prompts for confirmation.
-
-.PP
-: Uninstall a filter by ID. Removes the filter (file or directory)
+\f[B]\-\-uninstall\-filter\f[] \f[I]ID\f[] : Uninstall a filter by ID. Removes the filter (file or directory) from the user filters directory. Apex prompts for confirmation.
 
 .SS Plugins
 
 .PP
-\f[B]\-\-plugins\f[], \f[B]\-\-no\-plugins\f[] extend Apex with custom processing capabilities.
+\f[B]\-\-plugins\f[], \f[B]\-\-no\-plugins\f[] : Enable or disable external/plugin processing. Plugins extend Apex with custom processing capabilities.
 
 .PP
-: Enable or disable external/plugin processing. Plugins \f[B]\-\-list\-plugins\f[] remote directory. Shows both locally installed plugins and plugins available for installation from the Apex plugin directory.
+\f[B]\-\-list\-plugins\f[] : List installed plugins and available plugins from the remote directory. Shows both locally installed plugins and plugins available for installation from the Apex plugin directory.
 
 .PP
-: List installed plugins and available plugins from the \f[B]\-\-install\-plugin\f[] \f[I]ID\f[] :   Install a plugin by ID from the remote directory, or by Git URL/GitHub shorthand (user/repo). Plugins are installed to \fR$XDG_CONFIG_HOME/apex/plugins\f[] (or \fR<sub>/</sub>.config/apex/plugins\f[] when \fRXDG_CONFIG_HOME\f[] is not set). When installing from a URL or GitHub shorthand, Apex will prompt for confirmation since plugins execute unverified code. \f[B]\-\-uninstall\-plugin\f[] \f[I]ID\f[] from the plugins folder. Apex will prompt for confirmation before removing the plugin.
-
-.PP
-: Uninstall a plugin by ID. Removes the plugin directory
+\f[B]\-\-install\-plugin\f[] \f[I]ID\f[] :   Install a plugin by ID from the remote directory, or by Git URL/GitHub shorthand (user/repo). Plugins are installed to \fR$XDG_CONFIG_HOME/apex/plugins\f[] (or \fR<sub>/</sub>.config/apex/plugins\f[] when \fRXDG_CONFIG_HOME\f[] is not set). When installing from a URL or GitHub shorthand, Apex will prompt for confirmation since plugins execute unverified code. \f[B]\-\-uninstall\-plugin\f[] \f[I]ID\f[] : Uninstall a plugin by ID. Removes the plugin directory from the plugins folder. Apex will prompt for confirmation before removing the plugin.
 
 .SS General Options
 
 .PP
 \f[B]\-h\f[], \f[B]\-\-help\f[] :   Show help message and exit. \f[B]\-v\f[], \f[B]\-\-version\f[] :   Show version information and exit. \f[B]\-\-progress\f[], \f[B]\-\-no\-progress\f[] :   Show progress indicator during processing. Default: enabled when stderr is a TTY.
 
-.PP
-\f[B]\-i\f[], \f[B]\-\-info\f[] :   Print version, merged config metadata (global and project \fRconfig.yml\f[], plus \f[B]\-\-meta\-file\f[] and \f[B]\-\-meta\f[] when given) as YAML, and the plugin IDs that would load when plugins are enabled. Without input files, writes to stdout and exits. With files or \f[B]\-\-combine\f[]/\f[B]\-\-mmd\-merge\f[], writes to stderr first, then continues.
-
-.PP
-\f[B]\-\-extract\-meta\f[] :   Merge document metadata from input files in order (later overrides; respects \f[B]\-\-mode\f[]), print YAML to stdout, and exit. Requires at least one file (\f[B]\-\-combine\f[] file list counts). Incompatible with \f[B]\-\-mmd\-merge\f[].
-
-.PP
-\f[B]\-e\f[], \f[B]\-\-extract\-meta\-value\f[] \f[I]KEY\f[] :   Same merge as \f[B]\-\-extract\-meta\f[] but print only the value for \f[I]KEY\f[]. Exit status is non\-zero if the key is absent.
-
 .SS Multi\-file Utilities
 
 .PP
-\f[B]\-\-combine\f[] \f[I]files...\f[] Markdown stream, expanding all supported include syntaxes. When a \fRSUMMARY.md\f[] file is provided, Apex treats it as a GitBook\-style index and combines the linked files in order. Output is raw Markdown suitable for piping back into Apex.
-
-.PP
-: Concatenate one or more Markdown files into a single \f[B]\-\-mmd\-merge\f[] \f[I]index files...\f[] apex \-\-mmd\-merge index.txt | apex \-\-mode mmd \-\-standalone \-o book.html
+\f[B]\-\-combine\f[] \f[I]files...\f[] : Concatenate one or more Markdown files into a single Markdown stream, expanding all supported include syntaxes. When a \fRSUMMARY.md\f[] file is provided, Apex treats it as a GitBook\-style index and combines the linked files in order. Output is raw Markdown suitable for piping back into Apex.
 
 .PP
-:   Merge files from one or more MultiMarkdown \fRmmd_merge\f[]\-style index files into a  single Markdown stream. Each non\-empty, non\-comment line in an index file specifies a document to include. Lines whose first non\-whitespace character is \fR#\f[] are treated as comments and ignored. Indentation (tabs or groups of four spaces) before the filename increases the header level of the included document (each indent level shifts all Markdown headings in that file down one level). Output is raw Markdown suitable for piping into Apex, for example:
+\f[B]\-\-mmd\-merge\f[] \f[I]index files...\f[] :   Merge files from one or more MultiMarkdown \fRmmd_merge\f[]\-style index files into a  single Markdown stream. Each non\-empty, non\-comment line in an index file specifies a document to include. Lines whose first non\-whitespace character is \fR#\f[] are treated as comments and ignored. Indentation (tabs or groups of four spaces) before the filename increases the header level of the included document (each indent level shifts all Markdown headings in that file down one level). Output is raw Markdown suitable for piping into Apex, for example: apex \-\-mmd\-merge index.txt | apex \-\-mode mmd \-\-standalone \-o book.html
 
 .SH EXAMPLES
 
 .PP
-.nf
-\fR
-apex input.md
-
-\f[]
-.fi
-
-.PP
-Process a markdown file: apex input.md \-o output.html
+Process a markdown file: apex input.md
 
 .PP
-Output to a file: apex input.md \-\-standalone \-\-title "My Document"
+Output to a file: apex input.md \-o output.html
 
 .PP
-Generate standalone HTML document: apex input.md \-\-pretty
+Generate standalone HTML document: apex input.md \-\-standalone \-\-title "My Document"
 
 .PP
-Pretty\-print HTML output: apex input.md \-\-mode gfm
+Pretty\-print HTML output: apex input.md \-\-pretty
 
 .PP
-Use GFM mode: apex document.md \-\-bibliography refs.bib
+Use GFM mode: apex input.md \-\-mode gfm
 
 .PP
-Process document with citations and bibliography: apex document.md
+Process document with citations and bibliography: apex document.md \-\-bibliography refs.bib
 
 .PP
-Use metadata to specify bibliography: (With bibliography specified in YAML front matter) apex input.md \-\-mode kramdown
+Use metadata to specify bibliography: apex document.md
 
 .PP
-Use Kramdown mode with relaxed tables: echo "# Hello" | apex
+(With bibliography specified in YAML front matter) Use Kramdown mode with relaxed tables: apex input.md \-\-mode kramdown
 
 .PP
-Process from stdin:
+Process from stdin: echo "# Hello" | apex
 
 .SH PROCESSING MODES
 
 .PP
-\f[B]commonmark\f[] compatibility.
+\f[B]commonmark\f[] : Pure CommonMark specification. Minimal features, maximum compatibility.
 
 .PP
-: Pure CommonMark specification. Minimal features, maximum \f[B]gfm\f[] task lists, autolinks, and more.
+\f[B]gfm\f[] : GitHub Flavored Markdown. Includes tables, strikethrough, task lists, autolinks, and more.
 
 .PP
-: GitHub Flavored Markdown. Includes tables, strikethrough, \f[B]mmd\f[], \f[B]multimarkdown\f[] lists, footnotes, and more.
+\f[B]mmd\f[], \f[B]multimarkdown\f[] : MultiMarkdown compatibility. Includes metadata, definition lists, footnotes, and more.
 
 .PP
-: MultiMarkdown compatibility. Includes metadata, definition \f[B]kramdown\f[] (Inline Attribute Lists) for adding HTML attributes to elements, and more.
+\f[B]kramdown\f[] : Kramdown compatibility. Includes relaxed tables, IAL (Inline Attribute Lists) for adding HTML attributes to elements, and more.
 
 .PP
-: Kramdown compatibility. Includes relaxed tables, IAL \f[B]unified\f[] (default) :   All features enabled. Combines features from all modes.
+\f[B]unified\f[] (default) :   All features enabled. Combines features from all modes.
 
 .SH METADATA CONTROL OF OPTIONS
 
 .PP
-Most command\-line options can be controlled via document metadata, allowing different files to be processed with different settings when processing batches. This enables per\-document configuration without needing separate command\-line invocations. \f[B]Boolean options\f[] accept \fRtrue\f[]/\fRfalse\f[], \fRyes\f[]/\fRno\f[], or \fR1\f[]/\fR0\f[] (case\-insensitive). \f[B]String options\f[] use the value directly. \f[B]Supported boolean options:\f[] \fRindices\f[], \fRwikilinks\f[], \fRwikilink\-sanitize\f[], \fRincludes\f[], \fRrelaxed\-tables\f[], \fRper\-cell\-alignment\f[], \fRalpha\-lists\f[], \fRmixed\-lists\f[], \fRsup\-sub\f[], \fRstrikethrough\f[], \fRautolink\f[], \fRtransforms\f[], \fRunsafe\f[], \fRtables\f[], \fRfootnotes\f[], \fRsmart\f[], \fRmath\f[], \fRids\f[], \fRheader\-anchors\f[], \fRembed\-images\f[], \fRimage\-captions\f[], \fRlink\-citations\f[], \fRshow\-tooltips\f[], \fRsuppress\-bibliography\f[], \fRsuppress\-index\f[], \fRgroup\-index\-by\-letter\f[], \fRobfuscate\-emails\f[], \fRpretty\f[], \fRstandalone\f[], \fRhardbreaks\f[], \fRplugins\f[], \fRemoji\-autocorrect\f[], \fRcode\-line\-numbers\f[], \fRhighlight\-language\-only\f[], \fRmarkdown\-in\-html\f[] \f[B]Supported string options:\f[] \fRbibliography\f[], \fRcsl\f[], \fRtitle\f[], \fRstyle\f[] (or \fRcss\f[]), \fRid\-format\f[], \fRbase\-dir\f[], \fRmode\f[], \fRwikilink\-space\f[], \fRwikilink\-extension\f[] \f[B]Terminal output metadata\f[] (for \f[B]\-\-to terminal\f[] / \f[B]terminal256\f[]): \fRterminal.theme\f[] (\fRterminal_theme\f[]), \fRterminal.width\f[] (\fRterminal_width\f[], wrap width), \fRterminal.inline_images\f[] (\fRterminal_inline_images\f[], boolean), \fRterminal.image_width\f[] (\fRterminal_image_width\f[], viewer width in character cells), \fRterminal.paginate\f[] (\fRterminal_paginate\f[]), \fRpaginate\f[], \fRcode\-highlight\f[], \fRcode\-highlight\-theme\f[].
+Most command\-line options can be controlled via document metadata, allowing different files to be processed with different settings when processing batches. This enables per\-document configuration without needing separate command\-line invocations. \f[B]Boolean options\f[] accept \fRtrue\f[]/\fRfalse\f[], \fRyes\f[]/\fRno\f[], or \fR1\f[]/\fR0\f[] (case\-insensitive). \f[B]String options\f[] use the value directly. \f[B]Supported boolean options:\f[] \fRindices\f[], \fRwikilinks\f[], \fRwikilink\-sanitize\f[], \fRincludes\f[], \fRrelaxed\-tables\f[], \fRper\-cell\-alignment\f[], \fRalpha\-lists\f[], \fRmixed\-lists\f[], \fRsup\-sub\f[], \fRstrikethrough\f[], \fRautolink\f[], \fRtransforms\f[], \fRunsafe\f[], \fRtables\f[], \fRfootnotes\f[], \fRsmart\f[], \fRmath\f[], \fRcallouts\f[], \fRpy\-callouts\f[], \fRquarto\-callouts\f[], \fRdivs\f[], \fRspans\f[], \fRids\f[], \fRheader\-anchors\f[], \fRembed\-images\f[], \fRimage\-captions\f[], \fRlink\-citations\f[], \fRshow\-tooltips\f[], \fRsuppress\-bibliography\f[], \fRsuppress\-index\f[], \fRgroup\-index\-by\-letter\f[], \fRobfuscate\-emails\f[], \fRpretty\f[], \fRstandalone\f[], \fRhardbreaks\f[], \fRplugins\f[], \fRemoji\-autocorrect\f[], \fRcode\-line\-numbers\f[], \fRhighlight\-language\-only\f[], \fRmarkdown\-in\-html\f[] \f[B]Supported string options:\f[] \fRbibliography\f[], \fRcsl\f[], \fRtitle\f[], \fRstyle\f[] (or \fRcss\f[]), \fRid\-format\f[], \fRtoc\-min\-max\f[], \fRbase\-dir\f[], \fRmode\f[], \fRwikilink\-space\f[], \fRwikilink\-extension\f[] \f[B]Terminal output metadata\f[] (for \f[B]\-\-to terminal\f[] / \f[B]terminal256\f[]): \fRterminal.theme\f[] (\fRterminal_theme\f[]), \fRterminal.width\f[] (\fRterminal_width\f[], wrap width), \fRterminal.inline_images\f[] (\fRterminal_inline_images\f[], boolean), \fRterminal.image_width\f[] (\fRterminal_image_width\f[], viewer width in character cells), \fRterminal.paginate\f[] (\fRterminal_paginate\f[]), \fRpaginate\f[] (\fRtrue\f[], \fRfalse\f[], or \fRsymbols\f[] for pager\-friendly chafa ANSI images), \fRcode\-highlight\f[], \fRcode\-highlight\-theme\f[]. \f[B]Example YAML front matter:\f[]
 
 .PP
 .nf
@@ -480,7 +479,7 @@ standalone: true
 .fi
 
 .PP
-\f[B]Example YAML front matter:\f[]
+\f[B]Example MultiMarkdown metadata:\f[]
 
 .PP
 .nf
@@ -494,7 +493,7 @@ title: My Research Paper
 .fi
 
 .PP
-\f[B]Example MultiMarkdown metadata:\f[] When processing multiple files with \fRapex *.md\f[], each file can use its own configuration via metadata. You can also use \fR\-\-meta\-file\f[] to specify a shared configuration file that applies to all processed files. \f[B]Note:\f[] If \fRmode\f[] is specified in metadata, it resets all options to that mode's defaults before applying other metadata options.
+When processing multiple files with \fRapex *.md\f[], each file can use its own configuration via metadata. You can also use \fR\-\-meta\-file\f[] to specify a shared configuration file that applies to all processed files. \f[B]Note:\f[] If \fRmode\f[] is specified in metadata, it resets all options to that mode's defaults before applying other metadata options.
 
 .SH FEATURES
 
@@ -558,6 +557,11 @@ Apex supports a wide range of Markdown extensions:
 .IP \(bu 2
 \f[B]Inline Attribute Lists (IAL)\f[]: Kramdown\-style syntax for adding HTML attributes (IDs, classes, key\-value pairs) to block\-level and inline elements. Supports Attribute List Definitions (ALDs) for reusable attribute sets. Available in kramdown and unified modes. See Inline Attribute Lists (https://github.com/ttscoff/apex/wiki/Inline\-Attribute\-Lists) for complete documentation
 
+.SH ENVIRONMENT
+
+.PP
+\f[B]APEX_PAGER\f[] : When set and non\-empty, used as the pager command for \f[B]\-p\f[] / \f[B]\-\-paginate\f[] and \f[B]\-\-paginate\-symbols\f[] before \f[B]$PAGER\f[]. \f[B]PAGER\f[] : Fallback pager command when \f[B]APEX_PAGER\f[] is unset. \f[B]APEX_DEBUG_TERMINAL\f[] : When set to any non\-empty value, Apex prints terminal rendering diagnostics to stderr: selected image viewer, full viewer command lines, \f[B]TERM_PROGRAM\f[], pagination mode, and syntax highlighter commands. \f[B]TMPDIR\f[] : Directory for temporary files when downloading remote images for terminal display (falls back to \fR/tmp\f[] when unset).
+
 .SH SEE ALSO
 
 .PP

data/ext/apex_ext/apex_src/man/apex.1.md

@@ -77,6 +77,24 @@ Pagination is ignored when the output format is not a terminal format or when
 `-o/--output` is used to write to a file. You can also enable pagination via
 metadata or config by setting `paginate: true`.
 
+When pagination is enabled and the rendered output contains inline terminal
+graphics (iTerm **imgcat** / OSC 1337 sequences or Kitty graphics), Apex
+automatically skips the pager and writes directly to stdout, because **`less -R`**
+and most pagers only support ANSI color, not inline image protocols. A short
+notice is printed to stderr.
+
+**--paginate-symbols**
+: Page terminal output (same pager selection as **--paginate**) and render
+Markdown images as **chafa** ANSI block art (`chafa -f symbols`) so images
+display correctly in **`less -R`**. Requires **chafa** on **PATH**. With
+**--to terminal256**, Apex passes `-c 256` to chafa; with **--to terminal**,
+`-c 16`. Equivalent to metadata `paginate: symbols`. Implies pagination is
+enabled.
+
+**--no-paginate**
+: Do not page terminal output. Overrides **-p** / **--paginate** and
+`paginate: true` or `paginate: symbols` from metadata or config.
+
 **--theme** *NAME*
 : Terminal theme name for **--to terminal** / **--to terminal256**. Themes are YAML files under `~/.config/apex/terminal/themes/` (see the Apex wiki).
 
@@ -84,7 +102,24 @@ metadata or config by setting `paginate: true`.
 : Disable inline terminal rendering of Markdown images for **--to terminal** / **--to terminal256**. Default is to render when **stdout** is a TTY, a supported viewer exists on **PATH**, and inline images are enabled (see **METADATA CONTROL OF OPTIONS** for `terminal.inline_images`).
 
 **--terminal-image-width** *N*
-: Maximum width in character cells passed to the image viewer (default: 50). The first of **imgcat**, **chafa**, **viu**, **catimg** found on **PATH** is used, in that order. For `http://` and `https://` image URLs, Apex downloads with **curl** (60 second timeout, 10 MiB maximum size) to a file under **$TMPDIR** or `/tmp`, then displays it. If **curl** is missing, download fails, no viewer is found, **stdout** is not a TTY, or **--no-terminal-images** is set, images are emitted as styled link text and URL (like hyperlinks), not as Markdown `![alt](url)` syntax.
+: Maximum width in character cells passed to the image viewer (default: 50).
+When **stdout** is a TTY and inline images are enabled, Apex selects a viewer
+on **PATH** as follows:
+
+- **imgcat** — only when **TERM_PROGRAM** indicates iTerm2 (iTerm inline-image protocol).
+- **chafa** — otherwise, if available (`-f` format depends on terminal: **iterm** on iTerm/WezTerm, **kitty** on Kitty, **symbols** on other terminals).
+- **catimg** — if chafa is not found.
+- **viu** — if neither chafa nor catimg is found.
+
+For `http://` and `https://` image URLs, Apex downloads with **curl** (60 second
+timeout, 10 MiB maximum size) to a file under **$TMPDIR** or `/tmp`, then
+displays it. If **curl** is missing, download fails, no viewer is found,
+**stdout** is not a TTY, or **--no-terminal-images** is set, images are emitted
+as styled link text and URL (like hyperlinks), not as Markdown `![alt](url)` syntax.
+
+When **--paginate-symbols** or `paginate: symbols` is active, Apex always uses
+**chafa** with `-f symbols` for images so pager output remains compatible with
+**less -R**.
 
 **--code-highlight** *TOOL*
 : Use external tool for syntax highlighting of code blocks.
@@ -154,13 +189,21 @@ output more accessible. Default: disabled.
 - **strict-xhtml** - Same as **html** with **`--strict-xhtml`** (polyglot XHTML when used with **--standalone**). Alias; **`--strict-xhtml`** remains valid.
 - **json**, **json-filtered**, **ast-json**, **ast** - JSON output (before or after filters)
 - **markdown**, **md**, **mmd**, **commonmark**, **cmark**, **kramdown**, **gfm** - Markdown variants
+- **toc** - Markdown unordered list of heading links only (default depth **#**–**###**)
 - **terminal**, **cli**, **terminal256** - ANSI-colored output for TTYs and terminal emulators
 - **man** - Man page roff source (.TH, .SH, etc.)
 - **man-html** - Styled HTML man page (use **--standalone** for full page with nav sidebar)
+- **rtf** - Rich Text Format (native writer; write to a `.rtf` file for best results)
 
 When using a terminal format, Apex emits ANSI-colored output suitable for TTYs and
 terminal emulators.
 
+**--toc-min-max** *MIN,MAX*
+:: Inclusive heading depth for **--to toc** and for HTML TOC markers without an
+explicit range. The default is **1,3**, which includes headings from **#**
+through **###**. Marker syntax with an explicit range, such as `{{TOC:2-5}}`,
+overrides this setting. Values must satisfy `1 <= MIN <= MAX <= 6`.
+
 ## Feature Flags
 
 **--accept**
@@ -395,6 +438,12 @@ relative paths.
 **--divs**, **--no-divs**
 :   Enable or disable Pandoc fenced divs syntax (`:::: {#id .class} ... :::::`). Fenced divs allow you to create HTML block elements with attributes using a special fence syntax. By default, fenced divs create `<div>` elements, but you can specify different block types using the `>blocktype` syntax (e.g., `:: >aside {.sidebar} ... :::` creates an `<aside>` element instead). Opening fences must have at least 3 colons and attributes; closing fences need at least 3 colons. Fenced divs can be nested, including different block types. Default: enabled in unified mode only.
 
+**--py-callouts**, **--no-py-callouts**
+:   Enable or disable Python-Markdown callout syntax (`!!! note "Optional Title"` followed by indented content) and markdown-callouts label syntax (`NOTE: ...`, `>? NOTE: ...` for collapsed callouts). Disabled by default to avoid ambiguity with regular markdown prose.
+
+**--quarto-callouts**, **--no-quarto-callouts**
+:   Enable or disable Quarto callout syntax using fenced div markers (`::: {.callout-note}` ... `:::`). When enabled, recognized Quarto callout blocks bypass generic fenced-div conversion and are rendered as callouts; non-callout fenced divs continue to be processed as regular Pandoc fenced divs.
+
 **--spans**, **--no-spans**
 :   Enable or disable Pandoc-style bracketed spans syntax (`[text]{#id .class key="val"}`). Bracketed spans allow you to create HTML `<span>` elements with attributes. The text inside the brackets is processed as markdown. If the bracketed text matches a reference link definition, it will be treated as a link instead of a span. Default: enabled in unified mode only.
 
@@ -439,6 +488,16 @@ found.
 
 ## Indices
 
+**--concordance** *FILE*
+: TextIndex concordance file (tab-separated). Searches the
+    document for each rule's column-1 pattern and inserts
+    `[match]{^col2}` index marks before TextIndex processing.
+    Can be specified multiple times. Enables indices and
+    TextIndex syntax when used. Matches inside existing index
+    marks, `{index}` directives, and HTML tags are skipped.
+    See https://mattgemmell.scot/textindex/#concordance-files
+    for the concordance file format.
+
 **--indices**
 : Enable index processing. Supports both mmark and TextIndex
     syntax. Default: enabled in MultiMarkdown and unified modes.
@@ -620,14 +679,14 @@ command-line invocations.
 directly.
 
 **Supported boolean options:**
-`indices`, `wikilinks`, `wikilink-sanitize`, `includes`, `relaxed-tables`, `per-cell-alignment`, `alpha-lists`, `mixed-lists`, `sup-sub`, `strikethrough`, `autolink`, `transforms`, `unsafe`, `tables`, `footnotes`, `smart`, `math`, `ids`, `header-anchors`, `embed-images`, `image-captions`, `link-citations`, `show-tooltips`, `suppress-bibliography`, `suppress-index`, `group-index-by-letter`, `obfuscate-emails`, `pretty`, `standalone`, `hardbreaks`, `plugins`, `emoji-autocorrect`, `code-line-numbers`, `highlight-language-only`, `markdown-in-html`
+`indices`, `wikilinks`, `wikilink-sanitize`, `includes`, `relaxed-tables`, `per-cell-alignment`, `alpha-lists`, `mixed-lists`, `sup-sub`, `strikethrough`, `autolink`, `transforms`, `unsafe`, `tables`, `footnotes`, `smart`, `math`, `callouts`, `py-callouts`, `quarto-callouts`, `divs`, `spans`, `ids`, `header-anchors`, `embed-images`, `image-captions`, `link-citations`, `show-tooltips`, `suppress-bibliography`, `suppress-index`, `group-index-by-letter`, `obfuscate-emails`, `pretty`, `standalone`, `hardbreaks`, `plugins`, `emoji-autocorrect`, `code-line-numbers`, `highlight-language-only`, `markdown-in-html`
 
 **Supported string options:**
 `bibliography`, `csl`, `title`, `style` (or `css`),
-`id-format`, `base-dir`, `mode`, `wikilink-space`,
+`id-format`, `toc-min-max`, `base-dir`, `mode`, `wikilink-space`,
 `wikilink-extension`
 
-**Terminal output metadata** (for **--to terminal** / **terminal256**): `terminal.theme` (`terminal_theme`), `terminal.width` (`terminal_width`, wrap width), `terminal.inline_images` (`terminal_inline_images`, boolean), `terminal.image_width` (`terminal_image_width`, viewer width in character cells), `terminal.paginate` (`terminal_paginate`), `paginate`, `code-highlight`, `code-highlight-theme`.
+**Terminal output metadata** (for **--to terminal** / **terminal256**): `terminal.theme` (`terminal_theme`), `terminal.width` (`terminal_width`, wrap width), `terminal.inline_images` (`terminal_inline_images`, boolean), `terminal.image_width` (`terminal_image_width`, viewer width in character cells), `terminal.paginate` (`terminal_paginate`), `paginate` (`true`, `false`, or `symbols` for pager-friendly chafa ANSI images), `code-highlight`, `code-highlight-theme`.
 
 **Example YAML front matter:**
 ```
@@ -704,6 +763,24 @@ Apex supports a wide range of Markdown extensions:
   for complete documentation
 
 
+# ENVIRONMENT
+
+**APEX_PAGER**
+: When set and non-empty, used as the pager command for **-p** / **--paginate**
+and **--paginate-symbols** before **$PAGER**.
+
+**PAGER**
+: Fallback pager command when **APEX_PAGER** is unset.
+
+**APEX_DEBUG_TERMINAL**
+: When set to any non-empty value, Apex prints terminal rendering diagnostics
+to stderr: selected image viewer, full viewer command lines, **TERM_PROGRAM**,
+pagination mode, and syntax highlighter commands.
+
+**TMPDIR**
+: Directory for temporary files when downloading remote images for terminal
+display (falls back to `/tmp` when unset).
+
 # SEE ALSO
 
 **apex-config**(5), **apex-plugins**(7), **pandoc**(1), **markdown**(7)

data/ext/apex_ext/apex_src/objc/Apex.swift

@@ -8,6 +8,12 @@ import Foundation
 @_exported import ApexObjC
 @_exported import ApexC
 
+#if canImport(AppKit)
+import AppKit
+#elseif canImport(UIKit)
+import UIKit
+#endif
+
 /// Apex processor mode
 /// Type-safe enum for processor modes
 public enum ApexMode: String, CaseIterable {
@@ -16,6 +22,7 @@ public enum ApexMode: String, CaseIterable {
     case multimarkdown = "multimarkdown"
     case kramdown = "kramdown"
     case unified = "unified"
+    case quarto = "quarto"
 
     /// Convert to NSString for Objective-C API
     internal var nsString: NSString {
@@ -23,6 +30,14 @@ public enum ApexMode: String, CaseIterable {
     }
 }
 
+/// Preferred document type when building NSAttributedString from Markdown.
+public enum ApexAttributedSource: String {
+    /// Use Apex RTF output (NSRTFTextDocumentType). Preferred for AppKit fidelity.
+    case rtf
+    /// Use Apex HTML output (NSHTMLTextDocumentType).
+    case html
+}
+
 /// Apex conversion options
 /// Swift struct for configuring conversion options
 public struct ApexOptions {
@@ -56,6 +71,15 @@ public struct ApexOptions {
     /// Embed local images as base64 data URLs
     public var embedImages: Bool = false
 
+    /// Enable external plugin processing during conversion.
+    public var enablePlugins: Bool = false
+
+    /// Autolink bare URLs and emails. `nil` leaves the mode default unchanged.
+    public var enableAutolink: Bool? = nil
+
+    /// Output format: "html" (default) or "rtf"
+    public var outputFormat: String? = nil
+
     /// Default initializer
     public init() {}
     
@@ -96,6 +120,15 @@ public struct ApexOptions {
         if embedImages {
             dict["embedImages"] = true
         }
+        if enablePlugins {
+            dict["enablePlugins"] = true
+        }
+        if let enableAutolink {
+            dict["enableAutolink"] = enableAutolink
+        }
+        if let outputFormat = outputFormat {
+            dict["outputFormat"] = outputFormat
+        }
 
         return dict
     }
@@ -173,6 +206,32 @@ extension String {
             pretty: pretty
         )
     }
+
+    /**
+     * Convert Markdown to RTF using Apex.
+     */
+    public func apexRTF(mode: ApexMode = .unified, options: ApexOptions = .default) -> String {
+        var opts = options
+        opts.outputFormat = "rtf"
+        return NSString.convert(withApex: self, mode: mode.rawValue, options: opts.toDictionary())
+    }
+
+    #if canImport(AppKit) || canImport(UIKit)
+    /**
+     * Convert Markdown to NSAttributedString.
+     * Defaults to the RTF pipeline; pass source: .html for the HTML importer.
+     */
+    public func apexAttributedString(
+        mode: ApexMode = .unified,
+        options: ApexOptions = .default,
+        source: ApexAttributedSource = .rtf
+    ) -> NSAttributedString? {
+        let dict = options.toDictionary()
+        let useHTML = (source == .html)
+        return (self as NSString).apexAttributedString(
+            withMode: mode.rawValue, options: dict.isEmpty ? nil : dict, usingHTML: useHTML)
+    }
+    #endif
 }
 
 /// Static Apex converter
@@ -206,6 +265,20 @@ public struct Apex {
         return markdown.apexHTML(mode: mode, options: options)
     }
 
+    /**
+     * Convert Markdown to HTML using Apex with source file URL for includes
+     */
+    public static func convert(
+        _ markdown: String, mode: ApexMode = .unified, sourceURL: URL, enableAutolink: Bool = true
+    ) -> String {
+        return NSString.convert(
+            withApex: markdown,
+            mode: mode.rawValue,
+            sourceURL: sourceURL,
+            enableAutolink: enableAutolink
+        )
+    }
+
     /**
      * Convert Markdown to HTML using Apex with standalone document options
      */