apex-ruby 1.0.7 → 1.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/ext/apex_ext/apex_src/CHANGELOG.md +69 -0
  3. data/ext/apex_ext/apex_src/CMakeLists.txt +2 -1
  4. data/ext/apex_ext/apex_src/Formula/apex.rb +2 -2
  5. data/ext/apex_ext/apex_src/Package.swift +14 -2
  6. data/ext/apex_ext/apex_src/README.md +12 -9
  7. data/ext/apex_ext/apex_src/VERSION +1 -1
  8. data/ext/apex_ext/apex_src/cli/main.c +625 -98
  9. data/ext/apex_ext/apex_src/ial.html +24 -0
  10. data/ext/apex_ext/apex_src/include/apex/apex.h +57 -7
  11. data/ext/apex_ext/apex_src/include/apex/ast_markdown.h +3 -0
  12. data/ext/apex_ext/apex_src/include/apex/module.modulemap +8 -0
  13. data/ext/apex_ext/apex_src/include/apexc.h +6 -0
  14. data/ext/apex_ext/apex_src/include/module.modulemap +4 -0
  15. data/ext/apex_ext/apex_src/man/apex-config.5 +8 -2
  16. data/ext/apex_ext/apex_src/man/apex-plugins.7 +13 -13
  17. data/ext/apex_ext/apex_src/man/apex.1 +150 -442
  18. data/ext/apex_ext/apex_src/man/apex.1.md +13 -0
  19. data/ext/apex_ext/apex_src/src/_README.md +3 -1
  20. data/ext/apex_ext/apex_src/src/apex.c +151 -6
  21. data/ext/apex_ext/apex_src/src/ast_terminal.c +459 -8
  22. data/ext/apex_ext/apex_src/src/extensions/advanced_tables.c +6 -6
  23. data/ext/apex_ext/apex_src/src/extensions/callouts.c +1 -1
  24. data/ext/apex_ext/apex_src/src/extensions/citations.c +24 -12
  25. data/ext/apex_ext/apex_src/src/extensions/critic.c +14 -6
  26. data/ext/apex_ext/apex_src/src/extensions/emoji.c +2 -2
  27. data/ext/apex_ext/apex_src/src/extensions/grid_tables.c +1 -1
  28. data/ext/apex_ext/apex_src/src/extensions/header_ids.c +19 -6
  29. data/ext/apex_ext/apex_src/src/extensions/ial.c +25 -13
  30. data/ext/apex_ext/apex_src/src/extensions/includes.c +7 -7
  31. data/ext/apex_ext/apex_src/src/extensions/index.c +19 -7
  32. data/ext/apex_ext/apex_src/src/extensions/inline_footnotes.c +2 -2
  33. data/ext/apex_ext/apex_src/src/extensions/insert.c +1 -1
  34. data/ext/apex_ext/apex_src/src/extensions/math.c +11 -2
  35. data/ext/apex_ext/apex_src/src/extensions/metadata.c +46 -0
  36. data/ext/apex_ext/apex_src/src/extensions/metadata.h +12 -0
  37. data/ext/apex_ext/apex_src/src/html_renderer.c +2 -2
  38. data/ext/apex_ext/apex_src/src/plugins.c +97 -55
  39. data/ext/apex_ext/apex_src/src/plugins.h +0 -10
  40. data/ext/apex_ext/apex_src/src/pretty_html.c +1 -1
  41. data/ext/apex_ext/apex_src/tests/fixtures/metadata/mmd-metadata.md +5 -0
  42. data/ext/apex_ext/apex_src/tests/fixtures/metadata/pandoc-meta.md +4 -0
  43. data/ext/apex_ext/apex_src/tests/fixtures/metadata/yaml-frontmatter.md +6 -0
  44. data/ext/apex_ext/apex_src/tests/metadata_cli_test.sh +119 -0
  45. data/ext/apex_ext/apex_src/tests/test_custom_plugins.c +78 -0
  46. data/ext/apex_ext/apex_src/tests/test_extensions.c +27 -0
  47. data/ext/apex_ext/apex_src/tests/test_metadata.c +42 -0
  48. data/ext/apex_ext/apex_src/tests/test_output.c +83 -0
  49. data/ext/apex_ext/apex_src/tests/test_runner.c +4 -1
  50. data/lib/apex/version.rb +1 -1
  51. metadata +10 -2
data/ext/apex_ext/apex_src/man/apex.1 CHANGED
@@ -8,21 +8,12 @@ apex \- Unified Markdown processor supporting CommonMark, GFM, MultiMarkdown, an
8
8
  .SH SYNOPSIS
9
9
 
10
10
  .PP
11
- \f[B]apex\f[] [\f[I]options\f[]] [\f[I]file\f[]]
12
-
13
- .PP
14
- \f[B]apex\f[] \-\-combine [\f[I]files\f[]…]
15
-
16
- .PP
17
- \f[B]apex\f[] \-\-mmd\-merge [\f[I]index files\f[]…]
11
+ \f[B]apex\f[] [\f[I]options\f[]] [\f[I]file\f[]] \f[B]apex\f[] \-\-combine [\f[I]files\f[]...] \f[B]apex\f[] \-\-mmd\-merge [\f[I]index files\f[]...]
18
12
 
19
13
  .SH DESCRIPTION
20
14
 
21
15
  .PP
22
- Apex is a unified Markdown processor that combines the best features from CommonMark, GitHub Flavored Markdown (GFM), MultiMarkdown, Kramdown, and Marked. One processor to rule them all.
23
-
24
- .PP
25
- If no file is specified, \f[B]apex\f[] reads from stdin.
16
+ Apex is a unified Markdown processor that combines the best features from CommonMark, GitHub Flavored Markdown (GFM), MultiMarkdown, Kramdown, and Marked. One processor to rule them all. If no file is specified, \f[B]apex\f[] reads from stdin.
26
17
 
27
18
  .SH OPTIONS
28
19
 
@@ -40,59 +31,45 @@ Processor mode: \f[B]commonmark\f[], \f[B]gfm\f[], \f[B]mmd\f[] (or
40
31
  Write output to FILE instead of stdout.
41
32
 
42
33
  .TP
43
- \f[B]\-t\f[] FORMAT, \f[B]\-\-to\f[] FORMAT
44
- Output format: \f[B]html\f[] (default), \f[B]json\f[] (before filters), \f[B]json\-filtered\f[]/\f[B]ast\-json\f[]/\f[B]ast\f[] (after filters), \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[], \f[B]terminal\f[]/\f[B]cli\f[], \f[B]terminal256\f[], \f[B]man\f[], \f[B]man\-html\f[].
45
-
46
- .TP
47
- \f[B]\-s\f[], \f[B]\-\-standalone\f[]
48
- Generate complete HTML document with \fR<html>\f[], \fR<head>\f[],
49
- and \fR<body>\f[] tags.
34
+ \f[B]\-p\f[], \f[B]\-\-paginate\f[]
35
+ When using \f[B]\-\-to terminal\f[], \f[B]\-\-to cli\f[], or \f[B]\-\-to terminal256\f[], send
36
+ the rendered terminal output through a pager instead of writing directly to stdout. The pager command is chosen in this order:
50
37
 
51
- .TP
52
- \f[B]\-\-style\f[] FILE, \f[B]\-\-css\f[] FILE
53
- Link to CSS file(s) in document head (requires
54
- \f[B]\-\-standalone\f[]). Can be used multiple times or accept comma\-separated list (e.g., \fR\-\-css style.css \-\-css syntax.css\f[] or \fR\-\-css style.css,syntax.css\f[]). Overrides CSS metadata if specified.
38
+ .IP \(bu 2
39
+ If \fR$APEX_PAGER\f[] is set and non\-empty, Apex uses its value as the pager.
55
40
 
56
- .TP
57
- \f[B]\-\-embed\-css\f[]
58
- When used with \f[B]\-\-css FILE\f[], read the CSS file(s) and embed
59
- their contents into \fR<style>\f[] tags in the document head instead of emitting \fR<link rel="stylesheet">\f[] tags. All specified stylesheets are embedded.
41
+ .IP \(bu 2
42
+ Otherwise, if \fR$PAGER\f[] is set and non\-empty, Apex uses that.
60
43
 
61
- .TP
62
- \f[B]\-\-width\f[] N
63
- Hard\-wrap terminal/terminal256 output at N visible columns.
44
+ .IP \(bu 2
45
+ 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[].
64
46
 
65
47
  .TP
66
- \f[B]\-p\f[], \f[B]\-\-paginate\f[]
67
- Page terminal/cli/terminal256 output through a pager (\fR$APEX_PAGER\f[], then \fR$PAGER\f[], then \fRless \-R\f[]).
48
+ \f[B]\-\-theme\f[] NAME
49
+ Terminal theme name for \f[B]\-\-to terminal\f[] / \f[B]\-\-to terminal256\f[]. Themes are YAML files under \fR~/.config/apex/terminal/themes/\f[] (see the Apex wiki).
68
50
 
69
51
  .TP
70
- \f[B]\-\-theme\f[] NAME
71
- Terminal theme name for \f[B]\-t terminal\f[]/\f[B]\-t terminal256\f[].
52
+ \f[B]\-\-no\-terminal\-images\f[]
53
+ Disable inline terminal rendering of Markdown images for \f[B]\-\-to terminal\f[] / \f[B]\-\-to terminal256\f[]. Default is to render when \f[B]stdout\f[] is a TTY, a supported viewer exists on \f[B]PATH\f[], and inline images are enabled (see \f[B]METADATA CONTROL OF OPTIONS\f[] for \fRterminal.inline_images\f[]).
72
54
 
73
55
  .TP
56
+ \f[B]\-\-terminal\-image\-width\f[] N
57
+ 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.
74
58
 
75
59
  .TP
76
60
  \f[B]\-\-code\-highlight\f[] TOOL
77
61
  Use external tool for syntax highlighting of code blocks.
78
- \f[I]TOOL\f[] must be \f[B]pygments\f[] (or \f[B]p\f[], \f[B]pyg\f[]) or \f[B]skylighting\f[] (or \f[B]s\f[], \f[B]sky\f[]). Code blocks are sent to the external tool with their language specifier (if present) or with auto\-detection enabled. The highlighted HTML output replaces the original code block in the document.
62
+ \f[I]TOOL\f[] must be \f[B]pygments\f[] (or \f[B]p\f[], \f[B]pyg\f[]), \f[B]skylighting\f[] (or \f[B]s\f[], \f[B]sky\f[]), or \f[B]shiki\f[] (or \f[B]sh\f[]). Code blocks are sent to the external tool with their language specifier (if present) or with auto\-detection enabled. Output format is HTML or ANSI depending on destination (e.g. \f[B]\-\-to terminal\f[]). Shiki requires a language when it cannot auto\-detect; on error, the block is left as plain text.
79
63
 
80
64
  .TP
81
65
  \f[B]\-\-code\-highlight\-theme\f[] THEME
82
- Theme/style name for external syntax highlighters (\f[B]pygments\f[], \f[B]skylighting\f[], \f[B]shiki\f[]).
83
-
84
- .TP
85
- \f[B]\-\-code\-hilight\-theme\f[] THEME
86
- Legacy alias for \f[B]\-\-code\-highlight\-theme\f[].
87
-
88
- .TP
89
- \f[B]\-\-list\-themes\f[]
90
- List available syntax highlighting themes for supported external highlighters.
66
+ Theme/style name for external syntax highlighters.
67
+ When using \f[B]pygments\f[], this maps to the Pygments style name in both HTML and terminal output (e.g. \fRstyle=THEME\f[]). When using \f[B]skylighting\f[], it maps to the Skylighting style name via \fR\-\-style THEME\f[] for both HTML and ANSI terminal output. When using \f[B]shiki\f[], it maps to the Shiki theme via \fR\-\-theme THEME\f[] for both HTML and terminal/ANSI output. See \f[B]\-\-list\-themes\f[] for available theme names for each tool.
91
68
 
92
69
  .TP
93
70
  \f[B]\-\-code\-line\-numbers\f[]
94
71
  Include line numbers in syntax\-highlighted code blocks.
95
- Requires \f[B]\-\-code\-highlight\f[]. When used with Pygments, adds \fRlinenos=1\f[] option. When used with Skylighting, adds \fR\-n\f[] flag.
72
+ Requires \f[B]\-\-code\-highlight\f[]. When used with Pygments, adds \fRlinenos=1\f[] option. When used with Skylighting, adds \fR\-n\f[] flag. Shiki does not support line numbers in CLI mode.
96
73
 
97
74
  .TP
98
75
  \f[B]\-\-highlight\-language\-only\f[]
@@ -115,20 +92,14 @@ Pretty\-print HTML with indentation and whitespace.
115
92
  .TP
116
93
  \f[B]\-\-aria\f[]
117
94
  Add ARIA labels and accessibility attributes to HTML
118
- output. When enabled, adds:
119
-
120
- .PP
121
- \fRaria\-label="Table of contents"\f[] to TOC navigation elements (\fR<nav class="toc">\f[])
95
+ 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)
122
96
 
123
97
  .PP
124
98
  .nf
125
99
  \fR
126
- \- `role="figure"` to `<figure>` elements
127
- \- `role="table"` to `<table>` elements
128
100
  \- `id` attributes to `<figcaption>` elements within
129
- table figures (if missing)
130
- \- `aria\-describedby` attributes to tables linking them
131
101
  to their captions
102
+ \- `aria\-describedby` attributes to tables linking them
132
103
 
133
104
  \f[]
134
105
  .fi
@@ -137,6 +108,32 @@ output. When enabled, adds:
137
108
  This enhances screen reader support and makes the HTML output more accessible. Default: disabled.
138
109
 
139
110
  .TP
111
+ \f[B]\-t\f[] FORMAT, \f[B]\-\-to\f[] FORMAT
112
+ Output format. One of:
113
+
114
+ .IP \(bu 2
115
+ \f[B]html\f[] (default) \- Rendered HTML
116
+
117
+ .IP \(bu 2
118
+ \f[B]xhtml\f[] \- Same as \f[B]html\f[] with \f[B]\fR\-\-xhtml\f[]\f[] (self\-closing void tags). Alias; \f[B]\fR\-\-xhtml\f[]\f[] remains valid.
119
+
120
+ .IP \(bu 2
121
+ \f[B]strict\-xhtml\f[] \- Same as \f[B]html\f[] with \f[B]\fR\-\-strict\-xhtml\f[]\f[] (polyglot XHTML when used with \f[B]\-\-standalone\f[]). Alias; \f[B]\fR\-\-strict\-xhtml\f[]\f[] remains valid.
122
+
123
+ .IP \(bu 2
124
+ \f[B]json\f[], \f[B]json\-filtered\f[], \f[B]ast\-json\f[], \f[B]ast\f[] \- JSON output (before or after filters)
125
+
126
+ .IP \(bu 2
127
+ \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
128
+
129
+ .IP \(bu 2
130
+ \f[B]terminal\f[], \f[B]cli\f[], \f[B]terminal256\f[] \- ANSI\-colored output for TTYs and terminal emulators
131
+
132
+ .IP \(bu 2
133
+ \f[B]man\f[] \- Man page roff source (.TH, .SH, etc.)
134
+
135
+ .IP \(bu 2
136
+ \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.
140
137
 
141
138
  .SS Feature Flags
142
139
 
@@ -151,12 +148,12 @@ Reject all Critic Markup changes (revert edits).
151
148
  .TP
152
149
  \f[B]\-\-code\-highlight\f[] TOOL
153
150
  Use external tool for syntax highlighting of code blocks.
154
- \f[I]TOOL\f[] must be \f[B]pygments\f[] (or abbreviations \f[B]p\f[], \f[B]pyg\f[]) or \f[B]skylighting\f[] (or abbreviations \f[B]s\f[], \f[B]sky\f[]). Code blocks are sent to the external tool with their language specifier (if present) or with auto\-detection enabled. The highlighted HTML output replaces the original code block in the document.
151
+ \f[I]TOOL\f[] must be \f[B]pygments\f[] (or \f[B]p\f[], \f[B]pyg\f[]), \f[B]skylighting\f[] (or \f[B]s\f[], \f[B]sky\f[]), or \f[B]shiki\f[] (or \f[B]sh\f[]). Code blocks are sent to the external tool with their language specifier (if present) or with auto\-detection enabled. Output format is HTML or ANSI depending on destination. Shiki falls back to plain text when language cannot be determined.
155
152
 
156
153
  .TP
157
154
  \f[B]\-\-code\-line\-numbers\f[]
158
155
  Include line numbers in syntax\-highlighted code blocks.
159
- Requires \f[B]\-\-code\-highlight\f[]. When used with Pygments, adds \fRlinenos=1\f[] option. When used with Skylighting, adds \fR\-n\f[] flag.
156
+ Requires \f[B]\-\-code\-highlight\f[]. When used with Pygments, adds \fRlinenos=1\f[] option. When used with Skylighting, adds \fR\-n\f[] flag. Shiki does not support line numbers in CLI mode.
160
157
 
161
158
  .TP
162
159
  \f[B]\-\-highlight\-language\-only\f[]
@@ -165,18 +162,12 @@ specified (via \fR```language\f[] or IAL). Code blocks without a language will b
165
162
 
166
163
  .TP
167
164
  \f[B]\-\-includes\f[], \f[B]\-\-no\-includes\f[]
168
- Enable or disable file inclusion. Enabled by default in
169
- unified mode.
165
+ Enable or disable file inclusion. Enabled by default in unified mode.
170
166
 
171
167
  .TP
172
168
  \f[B]\-\-transforms\f[], \f[B]\-\-no\-transforms\f[]
173
- Enable or disable metadata variable transforms (\fR[%key:transform]\f[]).
174
-
175
- .TP
176
- \f[B]\-\-one\-line\-definitions\f[], \f[B]\-\-no\-one\-line\-definitions\f[]
177
- Enable or disable one\-line definition list syntax (\fRTerm :: Definition\f[]).
178
-
179
- .TP
169
+ Enable or disable metadata variable transforms
170
+ (\fR[%key:transform]\f[]). When enabled, metadata values can be transformed (case conversion, string manipulation, regex replacement, date formatting, etc.) when inserted into the document. Enabled by default in unified mode.
180
171
 
181
172
  .TP
182
173
  \f[B]\-\-meta\-file\f[] FILE
@@ -190,57 +181,14 @@ Set a metadata key\-value pair. Can be used multiple times. Supports comma\-sepa
190
181
  \f[B]\-\-hardbreaks\f[]
191
182
  Treat newlines as hard breaks.
192
183
 
193
- .TP
194
- \f[B]\-\-widont\f[]
195
- Prevent short widows in headings by inserting non\-breaking spaces
196
- (`&nbsp;`) between trailing words when their combined length is 10
197
- characters or less. Applies to h1\-h6 headings.
198
-
199
-
200
- .TP
201
- \f[B]\-\-code\-is\-poetry\f[]
202
- Treat code blocks without a language as poetry by adding the \fRpoetry\f[]
203
- class. Automatically enables **\-\-highlight\-language\-only**.
204
-
205
-
206
- .TP
207
- \f[B]\-\-markdown\-in\-html\f[], \f[B]\-\-no\-markdown\-in\-html\f[]
208
- Enable or disable markdown processing inside HTML blocks with
209
- `markdown` attributes. Enabled by default in unified mode.
210
-
211
-
212
- .TP
213
- \f[B]\-\-random\-footnote\-ids\f[]
214
- Use hash\-based footnote IDs (e.g., \fRfn\-a7b3c9d2\-1\f[]) instead of
215
- sequential IDs to avoid collisions when combining multiple documents.
216
-
217
-
218
184
  .TP
219
185
  \f[B]\-\-hashtags\f[]
220
186
  Convert \fR#tags\f[] into span\-wrapped hashtags with the \fRmkhashtag\f[] class.
221
187
 
222
- .TP
223
- \f[B]\-\-style\-hashtags\f[]
224
- Use the \fRmkstyledtag\f[] class instead of \fRmkhashtag\f[] for hashtags.
225
- Requires **\-\-hashtags**.
226
-
227
-
228
- .TP
229
- \f[B]\-\-proofreader\f[]
230
- Treat \fR==highlight==\f[] and \fR~~delete~~\f[] as CriticMarkup highlight and
231
- deletion syntax. Automatically enables CriticMarkup processing.
232
-
233
-
234
188
  .TP
235
189
  \f[B]\-\-hr\-page\-break\f[]
236
190
  Replace \fR<hr>\f[] elements with Marked\-style page break divs.
237
191
 
238
- .TP
239
- \f[B]\-\-title\-from\-h1\f[]
240
- Use the first H1 heading as the document title when no title is
241
- specified via **\-\-title** or metadata. Requires **\-\-standalone**.
242
-
243
-
244
192
  .TP
245
193
  \f[B]\-\-page\-break\-before\-footnotes\f[]
246
194
  Insert a page break before the footnotes section.
@@ -297,61 +245,14 @@ first item).
297
245
  \f[B]\-\-relaxed\-tables\f[], \f[B]\-\-no\-relaxed\-tables\f[]
298
246
  Enable relaxed table parsing (no separator rows required).
299
247
 
300
- .TP
301
- \f[B]\-\-per\-cell\-alignment\f[], \f[B]\-\-no\-per\-cell\-alignment\f[]
302
- Enable per\-cell alignment markers in tables. When enabled, cells
303
- starting with a colon (\fR:\f[]) are left\-aligned, ending with a colon (\fR:\f[]) are right\-aligned, or both (\fR:tent:\f[]) are center\-aligned. The colons are stripped from the output and replaced with \fRstyle="text\-align: ..."\f[] attributes. Default: enabled in unified mode, disabled in commonmark, gfm, mmd, and kramdown modes.
304
-
305
- .TP
306
- \f[B]\-\-captions\f[] POSITION
307
- Table caption position: \f[B]above\f[] or \f[B]below\f[] (default:
308
- \f[B]below\f[]). Controls where table captions appear relative to the table.
309
-
310
248
  .SS HTML and Links
311
249
 
312
- .TP
313
- \f[B]\-\-unsafe\f[], \f[B]\-\-no\-unsafe\f[]
314
- Allow raw HTML in output. Default: true for
315
- unified/mmd/kramdown modes, false for commonmark/gfm modes.
316
-
317
- .TP
318
- \f[B]\-\-autolink\f[], \f[B]\-\-no\-autolink\f[]
319
- Enable autolinking of URLs and email addresses. Default:
320
- enabled in GFM, MultiMarkdown, Kramdown, and unified modes; disabled in CommonMark mode.
321
-
322
- .TP
323
- \f[B]\-\-obfuscate\-emails\f[]
324
- Obfuscate email links and text using HTML entities
325
- (hex\-encoded).
326
-
327
- .TP
328
- \f[B]\-\-wikilink\-space\f[] MODE
329
- Space replacement mode for wiki links:
330
-
331
- .PP
332
- \fRdash\f[] \- Convert spaces to dashes: \fR[[Home Page]]\f[] → \fRhref="Home\-Page"\f[]
333
-
334
- .PP
335
- \fRnone\f[] \- Remove spaces: \fR[[Home Page]]\f[] → \fRhref="HomePage"\f[]
336
-
337
250
  .PP
338
- \fRunderscore\f[] \- Convert spaces to underscores: \fR[[Home Page]]\f[] → \fRhref="Home_Page"\f[]
251
+ \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[].
339
252
 
340
253
  .PP
341
254
  \fRspace\f[] \- Keep spaces (rendered as \fR%%20\f[] in HTML): \fR[[Home Page]]\f[] → \fRhref="Home%20Page"\f[]
342
255
 
343
- .PP
344
- .nf
345
- \fR
346
- Default: `dash`.
347
-
348
- \f[]
349
- .fi
350
-
351
- .TP
352
- \f[B]\-\-wikilink\-extension\f[] EXT
353
- File extension to append to wiki link URLs (e.g. \fRhtml\f[], \fRmd\f[]).
354
-
355
256
  .TP
356
257
  \f[B]\-\-wikilink\-sanitize\f[], \f[B]\-\-no\-wikilink\-sanitize\f[]
357
258
  Sanitize wiki link URLs for cleaner, more compatible links. When enabled:
@@ -372,104 +273,46 @@ Replaces non\-ascii and any non\-alphanumeric ascii characters with the space\-m
372
273
  Removes duplicate space\-mode characters
373
274
 
374
275
  .IP \(bu 2
375
- Removes leading and trailing space\-mode characters
276
+ Removes leading and trailing space\-mode characters For example, with \fR\-\-wikilink\-sanitize \-\-wikilink\-space dash\f[]: \fR[[O'Brien's Page]]\f[] → \fRhref="obriens\-page"\f[] \fR[[Hello World!!!]]\f[] → \fRhref="hello\-world"\f[] \fR[[path/to/FILE.MD]]\f[] → \fRhref="path/to/file.md"\f[] Default: disabled.
376
277
 
377
- .PP
378
- For example, with \fR\-\-wikilink\-sanitize \-\-wikilink\-space dash\f[]:
278
+ .SS Image Embedding
379
279
 
380
280
  .PP
381
- \fR[[O'Brien's Page]]\f[] → \fRhref="obriens\-page"\f[]
281
+ \f[B]\-\-embed\-images\f[] : Embed local images as base64 data URLs in HTML output. Only local images (file paths) are embedded; remote images (http://, https://) are not processed. Images are read from the filesystem and encoded as base64 data URLs (e.g., \fRdata:image/png;base64,...\f[]). Relative paths are resolved using the base directory (see \f[B]\-\-base\-dir\f[]). \f[B]\-\-image\-captions\f[], \f[B]\-\-no\-image\-captions\f[] : Wrap images with title or alt text in \fR<figure>\f[] elements with \fR<figcaption>\f[]. Default: enabled in unified and MultiMarkdown modes; disabled in commonmark, gfm, and kramdown modes. \f[B]\-\-emoji\-autocorrect\f[], \f[B]\-\-no\-emoji\-autocorrect\f[] : Convert emoji names (e.g., \fR:rocket:\f[]) to Unicode emoji characters. Default: enabled in unified mode; disabled in other modes.
382
282
 
383
- .PP
384
- \fR[[Hello World!!!]]\f[] → \fRhref="hello\-world"\f[]
283
+ .SS Path Resolution
385
284
 
386
285
  .PP
387
- \fR[[path/to/FILE.MD]]\f[] → \fRhref="path/to/file.md"\f[]
286
+ \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
388
287
 
389
288
  .PP
390
- Default: disabled.
391
-
392
- .SS Image Embedding
393
-
394
- .TP
395
- \f[B]\-\-embed\-images\f[]
396
- Embed local images as base64 data URLs in HTML output. Only local images (file paths) are embedded; remote images (http://, https://) are not processed. Images are read from the filesystem and encoded as base64 data URLs (e.g., \fRdata:image/png;base64,...\f[]). Relative paths are resolved using the base directory (see \f[B]\-\-base\-dir\f[]).
397
-
398
- .TP
399
- \f[B]\-\-image\-captions\f[], \f[B]\-\-no\-image\-captions\f[]
400
- Wrap images with title or alt text in \fR<figure>\f[] elements with \fR<figcaption>\f[]. Default: enabled in unified and MultiMarkdown modes; disabled in commonmark, gfm, and kramdown modes.
401
-
402
- .TP
403
- \f[B]\-\-title\-captions\-only\f[], \f[B]\-\-no\-title\-captions\-only\f[]
404
- Only add image captions when a title attribute is present (do not use alt text as caption fallback).
405
-
406
- .TP
407
- \f[B]\-\-emoji\-autocorrect\f[], \f[B]\-\-no\-emoji\-autocorrect\f[]
408
- Convert emoji names (e.g., \fR:rocket:\f[]) to Unicode emoji characters. Default: enabled in unified mode; disabled in other modes.
409
-
410
- .SS Path Resolution
411
-
412
- .TP
413
- \f[B]\-\-base\-dir\f[] DIR
414
- Base directory for resolving relative paths. Used for:
415
- \- Image embedding (with **\-\-embed\-images**)
416
- \- File includes/transclusions
289
+ .nf
290
+ \fR
417
291
  \- Relative path resolution when reading from stdin or
418
292
 
419
- when the working directory differs from the document
420
- location
421
-
293
+ \f[]
294
+ .fi
422
295
 
423
296
  .PP
424
- 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.
297
+ 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.
425
298
 
426
299
  .SS Superscript/Subscript
427
300
 
428
- .TP
429
- \f[B]\-\-sup\-sub\f[], \f[B]\-\-no\-sup\-sub\f[]
430
- Enable MultiMarkdown\-style superscript and subscript syntax. The \fR<sup>\f[] character creates superscript for the text immediately following it (stops at space or punctuation). The \fR~\f[] character creates subscript when used within a word/identifier (e.g., \fRH~2~O\f[] creates H₂O). When tildes are at word boundaries (e.g., \fR~text~\f[]), they create underline instead. Default: enabled in unified and MultiMarkdown modes.
431
-
432
- .TP
433
- \f[B]\-\-strikethrough\f[], \f[B]\-\-no\-strikethrough\f[]
434
- Enable or disable GFM\-style strikethrough processing (\fR~~text~~\f[]). When enabled, \fR~~text~~\f[] renders as \fR<del>text</del>\f[]. Default: enabled in GFM and unified modes; disabled in commonmark, mmd, and kramdown modes.
435
-
436
- .TP
437
- \f[B]\-\-divs\f[], \f[B]\-\-no\-divs\f[]
438
- Enable or disable Pandoc fenced divs syntax (\fR::::: {#id .class} ... :::::\f[]). Fenced divs allow you to create HTML block elements with attributes using a special fence syntax. By default, fenced divs create \fR<div>\f[] elements, but you can specify different block types using the \fR>blocktype\f[] syntax (e.g., \fR::: >aside {.sidebar} ... :::\f[] creates an \fR<aside>\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.
439
-
440
- .TP
441
- \f[B]\-\-spans\f[], \f[B]\-\-no\-spans\f[]
442
- 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.
443
-
444
- .SS Citations and Bibliography
301
+ .PP
302
+ \f[B]\-\-sup\-sub\f[], \f[B]\-\-no\-sup\-sub\f[] : Enable MultiMarkdown\-style superscript and subscript syntax. The \fR^\f[] character creates superscript for the text immediately following it (stops at space or punctuation). The \fR~\f[] character creates subscript when used within a word/identifier (e.g., \fRH~2~O\f[] creates H₂O). When tildes are at word boundaries (e.g., \fR~text~\f[]), they create underline instead. Default: enabled in unified and MultiMarkdown modes. \f[B]\-\-strikethrough\f[], \f[B]\-\-no\-strikethrough\f[] : Enable or disable GFM\-style strikethrough processing (\fR~~text~~\f[]). When enabled, \fR~~text~~\f[] renders as \fR<del>text</del>\f[]. Default: enabled in GFM and unified modes; disabled in commonmark, mmd, and kramdown modes. \f[B]\-\-divs\f[], \f[B]\-\-no\-divs\f[]
445
303
 
446
304
  .TP
447
- \f[B]\-\-bibliography\f[] FILE
448
- Bibliography file in BibTeX, CSL JSON, or CSL YAML format.
449
- Can be specified multiple times to load multiple bibliography files. Citations are automatically enabled when this option is used. Bibliography can also be specified in document metadata.
305
+ : Enable or disable Pandoc fenced divs syntax (\fR:::: {#id .class} ... :::::\f[]). Fenced divs allow you to create HTML block elements with attributes using a special fence syntax. By default, fenced divs create \fR<div>\f[] elements, but you can specify different block types using the \fR>blocktype\f[] syntax (e.g., `
450
306
 
451
- .TP
452
- \f[B]\-\-csl\f[] FILE
453
- Citation Style Language (CSL) file for formatting
454
- citations and bibliography. Citations are automatically enabled when this option is used. CSL file can also be specified in document metadata.
307
+ 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.
455
308
 
456
- .TP
457
- \f[B]\-\-no\-bibliography\f[]
458
- Suppress bibliography output even when citations are
459
- present.
460
309
 
461
- .TP
462
- \f[B]\-\-link\-citations\f[]
463
- Link citations to their corresponding bibliography
464
- entries. Citations will include \fRhref\f[] attributes pointing to the bibliography entry.
310
+ \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.
465
311
 
466
- .TP
467
- \f[B]\-\-show\-tooltips\f[]
468
- Show tooltips on citations when hovering (requires CSS
469
- support).
312
+ .SS Citations and Bibliography
470
313
 
471
314
  .PP
472
- Citation syntax is supported in MultiMarkdown and unified modes:
315
+ \f[B]\-\-bibliography\f[] \f[I]FILE\f[] : Bibliography file in BibTeX, CSL JSON, or CSL YAML format. Can be specified multiple times to load multiple bibliography files. Citations are automatically enabled when this option is used. Bibliography can also be specified in document metadata. \f[B]\-\-csl\f[] \f[I]FILE\f[] : Citation Style Language (CSL) file for formatting citations and bibliography. Citations are automatically enabled when this option is used. CSL file can also be specified in document metadata. \f[B]\-\-no\-bibliography\f[] : Suppress bibliography output even when citations are present. \f[B]\-\-link\-citations\f[] : Link citations to their corresponding bibliography entries. Citations will include \fRhref\f[] attributes pointing to the bibliography entry. \f[B]\-\-show\-tooltips\f[] : Show tooltips on citations when hovering (requires CSS support). Citation syntax is supported in MultiMarkdown and unified modes:
473
316
 
474
317
  .IP \(bu 2
475
318
  Pandoc: \fR[@key]\f[], \fR[@key1; @key2]\f[], \fR@key\f[]
@@ -478,267 +321,148 @@ Pandoc: \fR[@key]\f[], \fR[@key1; @key2]\f[], \fR@key\f[]
478
321
  MultiMarkdown: \fR[#key]\f[]
479
322
 
480
323
  .IP \(bu 2
481
- mmark: \fR[@RFC1234]\f[]
482
-
483
- .PP
484
- Bibliography is inserted at the \fR<!\-\- REFERENCES \-\->\f[] marker or appended to the end of the document if no marker is found.
324
+ mmark: \fR[@RFC1234]\f[] Bibliography is inserted at the \fR<!\-\- REFERENCES \-\->\f[] marker or appended to the end of the document if no marker is found.
485
325
 
486
326
  .SS Indices
487
327
 
488
- .TP
489
- \f[B]\-\-indices\f[]
490
- Enable index processing. Supports both mmark and TextIndex
491
- syntax. Default: enabled in MultiMarkdown and unified modes.
492
-
493
- .TP
494
- \f[B]\-\-no\-indices\f[]
495
- Disable index processing.
328
+ .PP
329
+ \f[B]\-\-indices\f[] syntax. Default: enabled in MultiMarkdown and unified modes.
496
330
 
497
- .TP
498
- \f[B]\-\-no\-index\f[]
499
- Suppress index generation at the end of the document.
500
- Index markers are still created in the document, but the index section is not generated.
331
+ .PP
332
+ : 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.
501
333
 
502
334
  .PP
503
- Index syntax is supported in MultiMarkdown and unified modes:
335
+ : Suppress index generation at the end of the document. Index syntax is supported in MultiMarkdown and unified modes:
504
336
 
505
337
  .IP \(bu 2
506
- \f[B]mmark syntax\f[]: \fR(!item)\f[], \fR(!item, subitem)\f[], `(!!item,
507
- subitem)` for primary entries
338
+ \f[B]mmark syntax\f[]: \fR(!item)\f[], \fR(!item, subitem)\f[], \fR(!!item, subitem)\f[] for primary entries
508
339
 
509
340
  .IP \(bu 2
510
- \f[B]TextIndex syntax\f[]: \fRword{^}\f[], \fR[term]{^}\f[], \fR{^params}\f[]
511
-
512
- .PP
513
- The index is automatically generated at the end of the document or at the \fR<!\-\-INDEX\-\->\f[] marker if present. Entries are sorted alphabetically and can be grouped by first letter.
341
+ \f[B]TextIndex syntax\f[]: \fRword{^}\f[], \fR[term]{^}\f[], \fR{^params}\f[] The index is automatically generated at the end of the document or at the \fR<!\-\-INDEX\-\->\f[] marker if present. Entries are sorted alphabetically and can be grouped by first letter.
514
342
 
515
343
  .SS AST Filters
516
344
 
517
- .TP
518
- \f[B]\-\-filter\f[] NAME
519
- Run a single AST filter from the user filters directory
520
- (\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.
521
-
522
- .TP
523
- \f[B]\-\-filters\f[]
524
- Run all executable files in the user filters directory, in sorted
525
- filename order. Directory filters run first if \f[B]\-\-filter\f[] is also used.
526
-
527
- .TP
528
- \f[B]\-\-lua\-filter\f[] FILE
529
- Run a Lua script as an AST filter. Apex invokes the system \f[B]lua\f[]
530
- 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.
531
-
532
- .TP
533
- \f[B]\-\-no\-strict\-filters\f[]
534
- Do not abort when a filter fails or returns invalid JSON; log a
535
- warning and continue with the previous AST. Default: abort on error.
536
-
537
- .TP
538
- \f[B]\-\-list\-filters\f[]
539
- List installed filters and available filters from the central
540
- apex\-filters directory. Shows filter IDs; available filters show title, author, description, and homepage.
541
-
542
- .TP
543
- \f[B]\-\-install\-filter\f[] ID\-or\-URL
544
- Install an AST filter into the user filters directory. ID\-or\-URL
545
- 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.
546
-
547
- .TP
548
- \f[B]\-\-uninstall\-filter\f[] ID
549
- Uninstall a filter by ID. Removes the filter (file or directory)
550
- from the user filters directory. Apex prompts for confirmation.
551
-
552
- .SS Plugins
553
-
554
- .TP
555
- \f[B]\-\-plugins\f[], \f[B]\-\-no\-plugins\f[]
556
- Enable or disable external/plugin processing. Plugins
557
- extend Apex with custom processing capabilities.
558
-
559
- .TP
560
- \f[B]\-\-list\-plugins\f[]
561
- List installed plugins and available plugins from the
562
- remote directory. Shows both locally installed plugins and plugins available for installation from the Apex plugin directory.
563
-
564
- .TP
565
- \f[B]\-\-install\-plugin\f[] ID
566
- 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~/.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.
567
-
568
- .TP
569
- \f[B]\-\-uninstall\-plugin\f[] ID
570
- Uninstall a plugin by ID. Removes the plugin directory
571
- from the plugins folder. Apex will prompt for confirmation before removing the plugin.
345
+ .PP
346
+ \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.
572
347
 
573
- .SS General Options
348
+ .PP
349
+ : 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.
574
350
 
575
- .TP
576
- \f[B]\-h\f[], \f[B]\-\-help\f[]
577
- Show help message and exit.
351
+ .PP
352
+ : 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.
578
353
 
579
- .TP
580
- \f[B]\-v\f[], \f[B]\-\-version\f[]
581
- Show version information and exit.
354
+ .PP
355
+ : 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.
582
356
 
583
- .TP
584
- \f[B]\-\-progress\f[], \f[B]\-\-no\-progress\f[]
585
- Show progress indicator during processing. Default: enabled when stderr is a TTY.
357
+ .PP
358
+ : 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.
586
359
 
587
- .SS Multi\-file Utilities
360
+ .PP
361
+ : 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.
588
362
 
589
- .TP
590
- \f[B]\-\-combine\f[] files…
591
- Concatenate one or more Markdown files into a single
592
- 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.
363
+ .PP
364
+ : 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.
593
365
 
594
- .TP
595
- \f[B]\-\-mmd\-merge\f[] index files…
596
- 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:
597
- apex \-\-mmd\-merge index.txt | apex \-\-mode mmd \-\-standalone \-o book.html
366
+ .PP
367
+ : Uninstall a filter by ID. Removes the filter (file or directory)
598
368
 
599
- .SH EXAMPLES
369
+ .SS Plugins
600
370
 
601
371
  .PP
602
- Process a markdown file:
372
+ \f[B]\-\-plugins\f[], \f[B]\-\-no\-plugins\f[] extend Apex with custom processing capabilities.
603
373
 
604
374
  .PP
605
- .nf
606
- \fR
607
- apex input.md
608
-
609
- \f[]
610
- .fi
375
+ : 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.
611
376
 
612
377
  .PP
613
- Output to a file:
378
+ : 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.
614
379
 
615
380
  .PP
616
- .nf
617
- \fR
618
- apex input.md \-o output.html
381
+ : Uninstall a plugin by ID. Removes the plugin directory
619
382
 
620
- \f[]
621
- .fi
383
+ .SS General Options
622
384
 
623
385
  .PP
624
- Generate standalone HTML document:
386
+ \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.
625
387
 
626
388
  .PP
627
- .nf
628
- \fR
629
- apex input.md \-\-standalone \-\-title "My Document"
630
-
631
- \f[]
632
- .fi
389
+ \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.
633
390
 
634
391
  .PP
635
- Pretty\-print HTML output:
392
+ \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[].
636
393
 
637
394
  .PP
638
- .nf
639
- \fR
640
- apex input.md \-\-pretty
395
+ \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.
641
396
 
642
- \f[]
643
- .fi
397
+ .SS Multi\-file Utilities
644
398
 
645
399
  .PP
646
- Use GFM mode:
400
+ \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.
647
401
 
648
402
  .PP
649
- .nf
650
- \fR
651
- apex input.md \-\-mode gfm
652
-
653
- \f[]
654
- .fi
403
+ : 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
655
404
 
656
405
  .PP
657
- Process document with citations and bibliography:
406
+ : 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:
407
+
408
+ .SH EXAMPLES
658
409
 
659
410
  .PP
660
411
  .nf
661
412
  \fR
662
- apex document.md \-\-bibliography refs.bib
413
+ apex input.md
663
414
 
664
415
  \f[]
665
416
  .fi
666
417
 
667
418
  .PP
668
- Use metadata to specify bibliography:
419
+ Process a markdown file: apex input.md \-o output.html
669
420
 
670
421
  .PP
671
- .nf
672
- \fR
673
- apex document.md
674
-
675
- \f[]
676
- .fi
422
+ Output to a file: apex input.md \-\-standalone \-\-title "My Document"
677
423
 
678
424
  .PP
679
- (With bibliography specified in YAML front matter)
425
+ Generate standalone HTML document: apex input.md \-\-pretty
680
426
 
681
427
  .PP
682
- Use Kramdown mode with relaxed tables:
428
+ Pretty\-print HTML output: apex input.md \-\-mode gfm
683
429
 
684
430
  .PP
685
- .nf
686
- \fR
687
- apex input.md \-\-mode kramdown
431
+ Use GFM mode: apex document.md \-\-bibliography refs.bib
688
432
 
689
- \f[]
690
- .fi
433
+ .PP
434
+ Process document with citations and bibliography: apex document.md
691
435
 
692
436
  .PP
693
- Process from stdin:
437
+ Use metadata to specify bibliography: (With bibliography specified in YAML front matter) apex input.md \-\-mode kramdown
694
438
 
695
439
  .PP
696
- .nf
697
- \fR
698
- echo "# Hello" | apex
440
+ Use Kramdown mode with relaxed tables: echo "# Hello" | apex
699
441
 
700
- \f[]
701
- .fi
442
+ .PP
443
+ Process from stdin:
702
444
 
703
445
  .SH PROCESSING MODES
704
446
 
705
- .TP
706
- \f[B]commonmark\f[]
707
- Pure CommonMark specification. Minimal features, maximum
708
- compatibility.
709
-
710
- .TP
711
- \f[B]gfm\f[]
712
- GitHub Flavored Markdown. Includes tables, strikethrough,
713
- task lists, autolinks, and more.
714
-
715
- .TP
716
- \f[B]mmd\f[], \f[B]multimarkdown\f[]
717
- MultiMarkdown compatibility. Includes metadata, definition
718
- lists, footnotes, and more.
719
-
720
- .TP
721
- \f[B]kramdown\f[]
722
- Kramdown compatibility. Includes relaxed tables, IAL
723
- (Inline Attribute Lists) for adding HTML attributes to elements, and more.
724
-
725
- .TP
726
- \f[B]unified\f[] (default)
727
- All features enabled. Combines features from all modes.
447
+ .PP
448
+ \f[B]commonmark\f[] compatibility.
728
449
 
729
- .SH METADATA CONTROL OF OPTIONS
450
+ .PP
451
+ : Pure CommonMark specification. Minimal features, maximum \f[B]gfm\f[] task lists, autolinks, and more.
730
452
 
731
453
  .PP
732
- 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.
454
+ : GitHub Flavored Markdown. Includes tables, strikethrough, \f[B]mmd\f[], \f[B]multimarkdown\f[] lists, footnotes, and more.
733
455
 
734
456
  .PP
735
- \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.
457
+ : MultiMarkdown compatibility. Includes metadata, definition \f[B]kramdown\f[] (Inline Attribute Lists) for adding HTML attributes to elements, and more.
736
458
 
737
459
  .PP
738
- \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[]
460
+ : Kramdown compatibility. Includes relaxed tables, IAL \f[B]unified\f[] (default) : All features enabled. Combines features from all modes.
461
+
462
+ .SH METADATA CONTROL OF OPTIONS
739
463
 
740
464
  .PP
741
- \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[]
465
+ 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[].
742
466
 
743
467
  .PP
744
468
  .nf
@@ -755,6 +479,9 @@ standalone: true
755
479
  \f[]
756
480
  .fi
757
481
 
482
+ .PP
483
+ \f[B]Example YAML front matter:\f[]
484
+
758
485
  .PP
759
486
  .nf
760
487
  \fR
@@ -767,10 +494,7 @@ title: My Research Paper
767
494
  .fi
768
495
 
769
496
  .PP
770
- 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.
771
-
772
- .PP
773
- \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.
497
+ \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.
774
498
 
775
499
  .SH FEATURES
776
500
 
@@ -787,16 +511,13 @@ Apex supports a wide range of Markdown extensions:
787
511
  \f[B]Footnotes\f[]: Reference\-style footnotes
788
512
 
789
513
  .IP \(bu 2
790
- \f[B]Math\f[]: Inline (\fR$...$\f[]) and display (\fR$$...$$\f[]) math
791
- with LaTeX
514
+ \f[B]Math\f[]: Inline (\fR$...$\f[]) and display (\fR$$...$$\f[]) math with LaTeX
792
515
 
793
516
  .IP \(bu 2
794
- \f[B]Wiki Links\f[]: \fR[[Page]]\f[], \fR[[Page|Display]]\f[],
795
- \fR[[Page#Section]]\f[]
517
+ \f[B]Wiki Links\f[]: \fR[[Page]]\f[], \fR[[Page|Display]]\f[], \fR[[Page#Section]]\f[]
796
518
 
797
519
  .IP \(bu 2
798
- \f[B]Critic Markup\f[]: All 5 types (add, del,
799
- sub, mark, comment)
520
+ \f[B]Critic Markup\f[]: All 5 types (add, del, sub, mark, comment)
800
521
 
801
522
  .IP \(bu 2
802
523
  \f[B]Smart Typography\f[]: Smart quotes, dashes, ellipsis
@@ -808,52 +529,39 @@ sub, mark, comment)
808
529
  \f[B]Task Lists\f[]: GFM\-style task lists
809
530
 
810
531
  .IP \(bu 2
811
- \f[B]Metadata\f[]: YAML front matter, MultiMarkdown metadata,
812
- Pandoc title blocks
532
+ \f[B]Metadata\f[]: YAML front matter, MultiMarkdown metadata, Pandoc title blocks
813
533
 
814
534
  .IP \(bu 2
815
- \f[B]Metadata Transforms\f[]: Transform metadata values with
816
- \fR[%key:transform]\f[] syntax (case conversion, string manipulation, regex replacement, date formatting, etc.)
535
+ \f[B]Metadata Transforms\f[]: Transform metadata values with \fR[%key:transform]\f[] syntax (case conversion, string manipulation, regex replacement, date formatting, etc.)
817
536
 
818
537
  .IP \(bu 2
819
- \f[B]Metadata Control of Options\f[]: Control command\-line
820
- options via metadata for per\-document configuration
538
+ \f[B]Metadata Control of Options\f[]: Control command\-line options via metadata for per\-document configuration
821
539
 
822
540
  .IP \(bu 2
823
- \f[B]Header IDs\f[]: Automatic or manual header IDs with
824
- multiple format options
541
+ \f[B]Header IDs\f[]: Automatic or manual header IDs with multiple format options
825
542
 
826
543
  .IP \(bu 2
827
544
  \f[B]Relaxed Tables\f[]: Support for tables without separator rows (Kramdown\-style). Enabled by default in unified and Kramdown modes.
828
545
 
829
546
  .IP \(bu 2
830
547
  \f[B]Per\-Cell Alignment\f[]: Support for alignment markers using colons at the start and/or end of table cells. Enabled by default in unified mode only.
831
- rows (Kramdown\-style)
832
548
 
833
549
  .IP \(bu 2
834
- \f[B]Inline Tables from CSV/TSV\f[]: Convert inline CSV/TSV
835
- text to tables using ```table fences or \fR<!\-\-TABLE\-\->\f[] markers
550
+ \f[B]Inline Tables from CSV/TSV\f[]: Convert inline CSV/TSV text to tables using ```table fences or \fR<!\-\-TABLE\-\->\f[] markers
836
551
 
837
- .PP
552
+ .IP \(bu 2
838
553
  \f[B]Superscript/Subscript\f[]: MultiMarkdown\-style superscript (\fR^text\f[]) and subscript (\fR~text~\f[] within words) syntax. Subscript uses paired tildes within word boundaries (e.g., \fRH~2~O\f[]), while tildes at word boundaries create underline
839
554
 
840
555
  .IP \(bu 2
841
- \f[B]Image Embedding\f[]: Embed local images as base64 data
842
- URLs with \fR\-\-embed\-images\f[] flag
556
+ \f[B]Image Embedding\f[]: Embed local images as base64 data URLs with \fR\-\-embed\-images\f[] flag
843
557
 
844
- .PP
558
+ .IP \(bu 2
845
559
  \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
846
560
 
847
561
  .SH SEE ALSO
848
562
 
849
563
  .PP
850
- \f[B]apex\-config\f[](5), \f[B]apex\-plugins\f[](7), \f[B]pandoc\f[](1), \f[B]markdown\f[](7)
851
-
852
- .PP
853
- For complete documentation, see the Apex Wiki (https://github.com/ttscoff/apex/wiki).
854
-
855
- .PP
856
- Project homepage: https://github.com/ApexMarkdown/apex (https://github.com/ApexMarkdown/apex)
564
+ \f[B]apex\-config\f[](5), \f[B]apex\-plugins\f[](7), \f[B]pandoc\f[](1), \f[B]markdown\f[](7) For complete documentation, see the Apex Wiki (https://github.com/ttscoff/apex/wiki). Project homepage: https://github.com/ApexMarkdown/apex (https://github.com/ApexMarkdown/apex)
857
565
 
858
566
  .SH AUTHOR
859
567