Command Line Options

Complete reference for all Apex command-line flags.

Basic Options

`-h, --help`

Display help message and exit.

apex --help

`-v, --version`

Display version information and exit.

apex --version

`--[no-]progress`

Show progress indicator during processing. Progress is displayed on stderr for operations that take longer than 1 second.

Default behavior:

Enabled when stderr is a TTY (interactive terminal)
Disabled when stderr is not a TTY (pipes, redirects, etc.)

Examples:

# Explicitly enable progress (useful when piping)
apex document.md --progress | less

# Explicitly disable progress
apex document.md --no-progress

# Progress is automatically enabled in interactive terminals
apex document.md

Behavior:

Progress messages appear on stderr (not stdout)
Only shown for operations taking longer than 1 second
Automatically cleared when processing completes
Useful for monitoring long-running operations or when processing large files

Note: Progress can also be controlled via the APEX_PROGRESS environment variable:

export APEX_PROGRESS=1  # Enable
export APEX_PROGRESS=0  # Disable

`--combine`

Concatenate one or more Markdown files into a single Markdown stream, expanding all supported include syntaxes (Marked <<[file], MultiMarkdown {{file}}, iA Writer /file, CSV/TSV includes, etc.).

File arguments are processed in the order given.
Includes inside those files are expanded exactly as in normal processing.
Output is raw Markdown, suitable for piping back into Apex for full rendering (indices, TOCs, citations, etc.).

When a SUMMARY.md file is provided, Apex treats it as a GitBook-style index:

Parses Markdown links in SUMMARY.md (e.g. [Intro](intro.md)).
Resolves linked files relative to the SUMMARY.md location.
Combines the linked files in link order.
Ignores external links containing :// for combination purposes.

`--mmd-merge`

Merge files from one or more MultiMarkdown mmd_merge-style index files into a single Markdown stream.

Behavior:

Each non-empty, non-comment line in an index file specifies a document to include
Lines whose first non-whitespace character is # are treated as comments and ignored
Indentation (tabs or groups of four spaces) before the filename controls header level shifting
Each indent level shifts all Markdown headings in that file down one level (adds one #)
Output is raw Markdown suitable for piping into Apex

Example index file (index.txt):

chapter1.md
    section1.md
    section2.md
chapter2.md
    section1.md

Usage:

# Merge and process in one step
apex --mmd-merge index.txt | apex --mode mmd --standalone -o book.html

# Merge multiple index files
apex --mmd-merge index1.txt index2.txt | apex --standalone -o combined.html

`-m, --mode MODE`

Set processor mode. See Modes for details.

Values:

commonmark - Pure CommonMark specification
gfm - GitHub Flavored Markdown
mmd or multimarkdown - MultiMarkdown compatibility
kramdown - Kramdown compatibility
unified - All features enabled (default)

Example:

apex --mode gfm document.md

`-o, --output FILE`

Write output to a file instead of stdout.

apex document.md -o output.html

Output Options

`-s, --standalone`

Generate a complete HTML document with <html>, <head>, and <body> tags.

apex document.md --standalone

`--xhtml`

HTML5 output with XML-style self-closing void tags (e.g. <br />, <meta charset="UTF-8" />, <link ... />). Does not add application/xhtml+xml metadata by default. Applied after pretty-printing when --pretty is used.

apex document.md --xhtml
apex document.md --standalone --xhtml -o out.html

`--strict-xhtml`

Polyglot XHTML/XML-oriented output for application/xhtml+xml consumers. Implies the same void-element serialization as --xhtml. With --standalone, emits an XML declaration, xmlns on <html>, and <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> (and not a separate <meta charset>). Cannot be combined with --xhtml (use --strict-xhtml alone).

apex document.md --standalone --strict-xhtml -o polyglot.xhtml

Strict mode in snippet mode (without --standalone): void/empty elements are still written in XML form, but Apex does not validate or repair the entire fragment as XML. Raw HTML (including from Markdown HTML blocks when allowed) may still be ill-formed—unbalanced tags, unescaped & / < / > in text, etc.—so output may not be well-formed XML. For full document-level polyglot headers, use --standalone.

`--style FILE`, `--css FILE`

Link to CSS file(s) in the document head. Requires --standalone. --css is an alias for --style. Overrides CSS metadata if present.

Multiple stylesheets:

Can be used multiple times: --css style.css --css syntax.css
Or use comma-separated list: --css style.css,syntax.css
Each stylesheet creates its own <link> tag

apex document.md --standalone --style styles.css apex document.md --standalone --css styles.css apex document.md --standalone --css style.css --css syntax.css apex document.md --standalone --css style.css,syntax.css

`--embed-css`

Embed the CSS file contents into <style> tags in the document head instead of using <link rel="stylesheet"> tags. When used with multiple stylesheets, all specified stylesheets are embedded as separate <style> blocks. Intended to be used together with --css.

apex document.md --standalone --css styles.css --embed-css
apex document.md --standalone --css style.css --css syntax.css --embed-css

`--width N`

When using -t terminal or -t terminal256, hard-wrap ANSI-colored output at N visible columns. This is especially useful in file manager preview panes (such as lf or yazi) where Apex cannot detect the pane width automatically. ANSI escape sequences are preserved and are not counted toward the column limit. If not specified, Apex does not add extra wrapping and the terminal itself controls line wrapping.

apex document.md -t terminal --width 80

You can also set a default terminal width via configuration:

terminal:
  width: 80

`-p, --paginate`

When using -t terminal, -t cli, or -t terminal256, send the rendered terminal output through a pager instead of writing directly to stdout.

Pager selection order:

If $APEX_PAGER is set and non-empty, Apex uses its value as the pager
Otherwise, if $PAGER is set and non-empty, Apex uses that
Otherwise, Apex falls back to less -R

Pagination is ignored when the output format is not a terminal format or when -o/--output is used to write to a file.

# Simple pagination using your default pager
apex README.md -t terminal --paginate

# Override pager just for this command
APEX_PAGER="less -RFX" apex README.md -t cli -p

Configuration:

You can also enable pagination via metadata or config:

paginate: true

`--code-highlight TOOL`

Use an external tool for syntax highlighting of code blocks. Code blocks are sent to the external tool with their language specifier (if present) or with auto-detection enabled. The highlighted HTML or ANSI output replaces the original code block in the document.

Supported tools:

pygments (or p, pyg) - Python-based syntax highlighter
skylighting (or s, sky) - Haskell-based syntax highlighter
shiki (or sh) - Shiki CLI (@shikijs/cli) for HTML or ANSI output

Behavior:

Only fenced code blocks are highlighted (indented code blocks are not processed)
Language is extracted from the code block's language specifier when present
If no language is specified, the tool attempts auto-detection where supported
When used with --standalone, GitHub-style syntax highlighting CSS is automatically embedded
The <body> tag receives a code-highlighted class when this option is used
For -t terminal / -t terminal256, Apex uses the external tool's ANSI output (when available) instead of HTML

Examples:

# Use Pygments for syntax highlighting
apex document.md --code-highlight pygments

# Use Skylighting (abbreviation)
apex document.md --code-highlight s

# Use Shiki (ANSI or HTML depending on -t/--to)
apex document.md --code-highlight shiki

# With standalone mode (includes automatic CSS)
apex document.md --standalone --code-highlight pygments

# Combine with multiple stylesheets
apex document.md --standalone --code-highlight pygments --css style.css --css syntax.css

Note: The external tool must be installed and available in your PATH. If the tool is not found, Apex will print a warning and code blocks will not be highlighted.

Configuration:

Syntax highlighting can also be configured via metadata in config.yml, --meta-file, or document front matter:

---
code-highlight: pygments
code-line-numbers: true
highlight-language-only: true
---

`--code-line-numbers`

Include line numbers in syntax-highlighted code blocks. Requires --code-highlight.

Behavior:

With Pygments: Adds linenos=1 option to generate numbered lines
With Skylighting: Adds -n flag to generate numbered lines
Shiki CLI does not support line numbers
Line numbers are included in the HTML output from the external tool

Examples:

# Syntax highlighting with line numbers
apex document.md --code-highlight pygments --code-line-numbers

# Standalone with line numbers
apex document.md --standalone --code-highlight skylighting --code-line-numbers

`--highlight-language-only`

Only apply syntax highlighting to code blocks that have a language specified. Requires --code-highlight.

Behavior:

Code blocks with a language (e.g., ```python or with IAL) are highlighted
Code blocks without a language are left as plain <pre><code> blocks
Useful when you want syntax highlighting for code examples but want to preserve plain text blocks

Examples:

# Only highlight code blocks with a language
apex document.md --code-highlight pygments --highlight-language-only

# Combine with line numbers
apex document.md --code-highlight skylighting --code-line-numbers --highlight-language-only

Input:

```python
def hello():
    print("Hello!")
```

```
This is a plain code block without a language.
It will not be highlighted.
```

Output with --highlight-language-only:

The Python block is syntax-highlighted
The plain block remains as a simple <pre><code> element

Configuration:

This option can also be set via metadata:

---
code-highlight: pygments
highlight-language-only: true
---

`--code-highlight-theme THEME`

Theme/style name for external syntax highlighters. The value maps to:

Pygments: style=THEME (HTML) and style=THEME for terminal/terminal256 ANSI output
Skylighting: --style THEME for both HTML and ANSI output (with -f html or -f ansi)
Shiki: --theme THEME for both HTML and ANSI output

Use apex --list-themes to see built-in themes for Pygments and Skylighting and a pointer to bundled Shiki themes.

`--list-themes`

List available syntax highlighting themes for Pygments, Skylighting, and Shiki. Output is arranged in multiple columns that adapt to the current terminal width (up to four columns on wide screens).

apex --list-themes

`--script VALUE`

Inject <script> tags either before </body> in standalone mode or at the end of the HTML fragment in snippet mode.

VALUE: A path, URL, or one of the following shorthands: mermaid, mathjax, katex, highlightjs, highlight.js, prism, prismjs, htmx, alpine, alpinejs.
Multiple values: Use the flag multiple times or provide a comma-separated list.

apex document.md --standalone --script mermaid,mathjax
apex document.md --script /assets/app.js --script https://cdn.example.com/widget.js

`--title TITLE`

Set the document title. Requires --standalone. Default is "Document".

apex document.md --standalone --title "My Document"

`--pretty`

Pretty-print HTML with indentation and whitespace.

apex document.md --pretty

`--aria`

Add ARIA labels and accessibility attributes to HTML output for better screen reader support.

When enabled, adds:

aria-label="Table of contents" to TOC navigation elements (<nav class="toc">)
role="figure" to <figure> elements
role="table" to <table> elements
id attributes to <figcaption> elements within table figures (generated if missing, e.g., table-caption-1, table-caption-2)
aria-describedby attributes to tables linking them to their captions

Default: Disabled (backward compatibility)

Examples:

# Generate accessible HTML output
apex document.md --aria

# Combine with other options
apex document.md --aria --standalone --pretty

Output examples:

With --aria enabled, a table of contents generates:

<nav class="toc" aria-label="Table of contents">
  <ul>
    <li><a href="#section">Section</a></li>
  </ul>
</nav>

Tables with captions get proper ARIA attributes:

<figure class="table-figure" role="figure">
  <figcaption id="table-caption-1">Table Title</figcaption>
  <table role="table" aria-describedby="table-caption-1">
    ...
  </table>
</figure>

Note: This option enhances accessibility without changing the visual appearance of the HTML. It's particularly useful for documents that will be read by screen readers or other assistive technologies.

AST Filters

AST filters operate on a Pandoc-style JSON representation of the document between parse and render. See Filters for the full protocol and examples.

`--filter NAME`

Run a single AST filter from your user filters directory. Apex looks for an executable named NAME in:

$XDG_CONFIG_HOME/apex/filters/NAME, or
~/.config/apex/filters/NAME (on macOS/Linux when XDG is not set).

NAME is the basename of the filter (e.g. title, delink). The filter must read a Pandoc JSON document from stdin and write a Pandoc JSON document to stdout.

apex --filter title input.md > output.html
apex --filter delink --filter title input.md > output.html

`--filters`

Run all executable files in the user filters directory, in sorted filename order. Useful for a standard pipeline (e.g. 01-title, 10-delink). Directory filters run first if you also pass one or more --filter options.

apex --filters input.md > output.html

`--lua-filter FILE`

Run a Lua script as an AST filter. Apex invokes the system lua interpreter with FILE; the script receives a Pandoc JSON document on stdin and must write a (possibly transformed) Pandoc JSON document to stdout. No Pandoc Lua runtime is required, but the script needs a JSON library (e.g. dkjson via luarocks install dkjson). See Filters for requirements and a minimal example.

apex --lua-filter unwrap.lua input.md > output.html

`--no-strict-filters`

By default, if a filter exits with a non-zero status or produces invalid JSON, Apex aborts with an error. With --no-strict-filters, Apex logs a warning, skips the failing filter, and continues with the previous AST.

apex --no-strict-filters --filter optional-filter input.md > output.html

`--list-filters`

List installed filters (from your user filters directory) and available filters from the central apex-filters directory. Shows filter IDs; available filters also show title, author, description, and homepage.

apex --list-filters

`--install-filter ID-or-URL`

Install an AST filter into your user filters directory. ID-or-URL can be:

A filter ID from the central apex-filters directory (e.g. unwrap, uppercase). Apex fetches the filter list and clones the matching repository into ~/.config/apex/filters/ID (or $XDG_CONFIG_HOME/apex/filters/ID).
A Git URL (e.g. https://github.com/user/apex-filter-example.git) or GitHub shorthand (user/apex-filter-example). When installing from a URL, Apex may prompt for confirmation since the code is not verified.

After installation, run the filter by name with --filter ID.

apex --install-filter unwrap
apex --install-filter https://github.com/user/apex-filter-example.git
apex --filter unwrap input.md > output.html

`--uninstall-filter ID`

Uninstall a filter by ID. Removes the filter (file or directory) from your user filters directory. Apex will prompt for confirmation before removing.

apex --uninstall-filter unwrap

Plugin Management

`--plugins`, `--no-plugins`

Enable or disable external/plugin processing. Plugins are disabled by default; enable them per run or via metadata (plugins: true / enable-plugins: true).

apex document.md --plugins
apex document.md --no-plugins

`--list-plugins`

List installed plugins and available plugins from the remote directory. Shows IDs, titles, authors, and descriptions when available.

apex --list-plugins

`--install-plugin ID-or-URL`

Install a plugin either:

By ID from the central plugin directory (e.g. kbd), or
Directly from a Git URL or GitHub shorthand (user/repo).

When installing from a URL, Apex prints a security warning before cloning, since plugins execute unverified code.

apex --install-plugin kbd
apex --install-plugin https://github.com/user/apex-plugin-example.git
apex --install-plugin user/apex-plugin-example

`--uninstall-plugin ID`

Uninstall a locally installed plugin by ID. This removes the plugin’s directory from the user plugin location, but does not delete any external support data the plugin may have created.

apex --uninstall-plugin kbd

Header ID Options

`--id-format FORMAT`

Set header ID generation format. See Header IDs for details.

Values:

gfm - GitHub Flavored Markdown format (default)
mmd - MultiMarkdown format
kramdown - Kramdown format

Note: Modes automatically set the format. This option is useful to override in unified mode.

GFM Format Features:

In GFM format, emojis in headers are automatically converted to their textual names in IDs (e.g., # 😄 Support → id="smile-support"), matching Pandoc's GFM behavior.

apex document.md --id-format mmd

`--no-ids`

Disable automatic header ID generation.

apex document.md --no-ids

`--header-anchors`

Generate <a> anchor tags instead of id attributes on headers.

apex document.md --header-anchors

Output:

<!-- Default -->
<h1 id="my-header">My Header</h1>

<!-- With --header-anchors -->
<h1><a id="my-header" href="#my-header">My Header</a></h1>

Table Options

`--relaxed-tables`

Enable relaxed table parsing (tables without separator rows). Default in unified and kramdown modes.

apex document.md --relaxed-tables

`--no-relaxed-tables`

Disable relaxed table parsing.

apex document.md --no-relaxed-tables

`--per-cell-alignment`

Enable per-cell alignment markers in tables. When enabled, cells starting with a colon (:) are left-aligned, ending with a colon (:) are right-aligned, or both (:content:) are center-aligned. The colons are stripped from the output and replaced with style="text-align: ..." attributes.

Default: Enabled in unified mode, disabled in other modes.

apex document.md --per-cell-alignment

`--no-per-cell-alignment`

Disable per-cell alignment markers in tables.

apex document.md --no-per-cell-alignment

`--captions POSITION`

Control the position of table captions. Captions are rendered as <figcaption> elements within <figure class="table-figure"> wrappers.

Values:

above - Place captions above the table
below - Place captions below the table (default)

Default: below

# Place captions above tables
apex document.md --captions above

# Place captions below tables (default)
apex document.md --captions below

Note: In standalone HTML output, table figures are styled with default CSS that centers and formats captions appropriately. The figure element shrinks to fit the table width, ensuring captions are properly aligned with the table.

`--no-tables`

Disable table support entirely.

apex document.md --no-tables

List Options

`--[no-]alpha-lists`

Control support for alphabetic list markers (a., b., c. and A., B., C.).

Default behavior by mode:

Enabled in: unified
Disabled in: commonmark, gfm, mmd, kramdown

Alpha lists are automatically converted to HTML with style="list-style-type: lower-alpha" or style="list-style-type: upper-alpha".

Examples:

# Enable alpha lists in GFM mode
apex document.md --mode gfm --alpha-lists

# Disable alpha lists in unified mode
apex document.md --mode unified --no-alpha-lists

Input:

a. First item
b. Second item
c. Third item

A. Uppercase item
B. Another uppercase

Output:

<ol style="list-style-type: lower-alpha">
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
</ol>

<ol style="list-style-type: upper-alpha">
  <li>Uppercase item</li>
  <li>Another uppercase</li>
</ol>

`--[no-]mixed-lists`

Control whether different list marker types can be mixed at the same indentation level.

Default behavior by mode:

Enabled in: unified, multimarkdown
Disabled in: commonmark, gfm, kramdown

When enabled, mixed markers inherit the type from the first item in the list.

Examples:

# Enable mixed lists in GFM mode
apex document.md --mode gfm --mixed-lists

# Disable mixed lists in unified mode
apex document.md --mode unified --no-mixed-lists

Input with mixed-lists enabled:

1. First numbered item
* Second item (becomes numbered)
* Third item (becomes numbered)

Output:

<ol>
  <li>First numbered item</li>
  <li>Second item (becomes numbered)</li>
  <li>Third item (becomes numbered)</li>
</ol>

Feature Flags

`--no-footnotes`

Disable footnote support.

apex document.md --no-footnotes

`--no-smart`

Disable smart typography (smart quotes, dashes, ellipsis).

apex document.md --no-smart

`--no-math`

Disable math support.

apex document.md --no-math

`--[no-]autolink`

Control automatic linking of URLs and email addresses.

Default behavior by mode:

Enabled in: GFM, MultiMarkdown, Kramdown, unified
Disabled in: CommonMark

What gets autolinked:

Angle-bracket URLs: <https://example.com>, <http://example.com>, <mailto:user@example.com>
Bare URLs: https://example.com, http://example.com
Email addresses: user@example.com

Important: Autolinks are not processed inside code spans (`code`) or code blocks ( ```).

Examples:

# Enable autolinking in CommonMark mode
apex document.md --mode commonmark --autolink

# Disable autolinking in unified mode
apex document.md --mode unified --no-autolink

Input:

Visit https://example.com or contact me@example.com.
See `<https://example.com>` in code.

Output with autolink enabled:

<p>Visit <a href="https://example.com">https://example.com</a> or contact <a href="me@example.com">me@example.com</a>.</p>
<p>See <code>&lt;https://example.com&gt;</code> in code.</p>

Output with autolink disabled:

<p>Visit https://example.com or contact me@example.com.</p>
<p>See <code>&lt;https://example.com&gt;</code> in code.</p>

`--obfuscate-emails`

Obfuscate email links (including autolinked emails) by hex-encoding both the mailto: href and the visible address. Useful to deter scraping.

Default: Off (emails are plain mailto: links)

# Encode all mailto links in the output
apex document.md --obfuscate-emails

Output:

<a href="&#x6D;&#x61;&#x69;&#x6C;&#x74;&#x6F;&#x3A;&#x6D;&#x65;&#x40;&#x65;&#x78;&#x61;&#x6D;&#x70;&#x6C;&#x65;&#x2E;&#x63;&#x6F;&#x6D;">
&#x6D;&#x65;&#x40;&#x65;&#x78;&#x61;&#x6D;&#x70;&#x6C;&#x65;&#x2E;&#x63;&#x6F;&#x6D;
</a>

`--includes`, `--no-includes`

Enable or disable file inclusion features. Enabled by default in unified mode.

apex document.md --includes
apex document.md --no-includes

CSV/TSV include delimiter overrides:

Marked includes: <<[data.csv{;}], <<[data.csv{delimiter=;}]
MultiMarkdown transclusion: {{data.csv{;}}}, {{data.csv{delimiter=;}}}
iA Writer includes (space optional): /data.csv{;}, /data.csv {;}, /data.csv{delimiter=;}, /data.csv {delimiter=;}
Defaults remain comma for CSV and tab for TSV when no override is provided.

Image Embedding

`--embed-images`

Embed local images as base64 data URLs in HTML output.

Behavior:

Only local images (file paths) are embedded
Remote images (http://, https://, //) are not processed and remain as URLs
Images are read from the filesystem and encoded as base64
Relative paths are resolved using the base directory (see --base-dir)
Images that are already data URLs are not processed again
If an image file doesn't exist, the original path is preserved

Supported image formats:

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
WebP (.webp)
SVG (.svg)
BMP (.bmp)
ICO (.ico)

Examples:

# Embed local images
apex document.md --embed-images

# Embed images with custom base directory
apex document.md --embed-images --base-dir /path/to/images

Input:

![Local Image](images/photo.png)
![Remote Image](https://example.com/image.jpg)
![Already Embedded](data:image/png;base64,iVBORw0KGgo...)

Output with --embed-images:

<img src="data:image/png;base64,iVBORw0KGgo..." alt="Local Image">
<img src="https://example.com/image.jpg" alt="Remote Image">
<img src="data:image/png;base64,iVBORw0KGgo..." alt="Already Embedded">

`--[no-]image-captions`

Automatically convert images with captions into semantic <figure> elements.

Behavior:

When enabled, any image with a title or alt text is wrapped in a <figure> containing a <figcaption>:
- Caption text prefers the image title attribute if present.
- If there is no title, the caption falls back to the alt text.
Images without title and alt text are left as plain <img> tags (no <figure> or <figcaption>).
Only the caption text is taken from the attribute value; any HTML escaping (such as &) is preserved as in the rendered HTML.

Defaults by mode:

Enabled by default in MultiMarkdown (--mode mmd / --mode multimarkdown) and unified modes.
Disabled by default in commonmark, gfm, and kramdown modes.

Examples:

Input:

![Alt only](images/photo.png)
![With title](images/figure.png "Figure caption")
![](images/plain.png)

Output (with image captions enabled in unified/MultiMarkdown modes):

<figure><img src="images/photo.png" alt="Alt only"><figcaption>Alt only</figcaption></figure>
<figure><img src="images/figure.png" alt="With title" title="Figure caption"><figcaption>Figure caption</figcaption></figure>
<img src="images/plain.png" alt="">

Controlling per document:

CLI:
- Enable in any mode: --image-captions
- Disable in unified/MultiMarkdown: --no-image-captions
Metadata (YAML or MMD metadata):
- image-captions: true / image-captions: false
- or image_captions: true / image_captions: false

Path Resolution

`--base-dir DIR`

Set the base directory for resolving relative paths.

Used for:

Image embedding (with --embed-images)
File includes/transclusions
Resolving relative paths when reading from stdin
Resolving relative paths when the working directory differs from the document location

Behavior:

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
Absolute paths are not affected by this setting
Relative paths are resolved by combining the base directory with the relative path

Examples:

# Read from file (base directory auto-set to file's directory)
apex document.md --embed-images

# Read from stdin with base directory
cat document.md | apex --base-dir /path/to/document --embed-images

# Override auto-detected base directory
apex document.md --base-dir /custom/path --embed-images

# Use for includes
apex document.md --base-dir /path/to/project --includes

Input (reading from stdin):

![Image](images/photo.png)

Without --base-dir:

<!-- Image not found, path preserved -->
<img src="images/photo.png" alt="Image">

With --base-dir /path/to/document:

<!-- Image found at /path/to/document/images/photo.png and embedded -->
<img src="data:image/png;base64,..." alt="Image">

`--[no-]transforms`

Control metadata variable transforms. Enables [%key:transform] syntax for transforming metadata values.

Default behavior by mode:

Enabled in: unified (default)
Disabled in: commonmark, gfm, mmd, kramdown

Examples:

# Enable transforms in GFM mode
apex document.md --mode gfm --transforms

# Disable transforms in unified mode
apex document.md --mode unified --no-transforms

Input:

---
title: hello world
---

# [%title:upper]

Output with transforms enabled:

<h1>HELLO WORLD</h1>

Output with transforms disabled:

<h1>[%title:upper]</h1>

For complete documentation of available transforms, see Metadata Transforms.

Metadata Options

`--meta-file FILE`

Load metadata from an external file. The file format is auto-detected (YAML, MultiMarkdown, or Pandoc format).

Supported formats:

YAML (.yml, .yaml, or --- delimited blocks)
MultiMarkdown (key: value pairs)
Pandoc (% lines)

Metadata precedence (highest to lowest):

Command-line metadata (--meta)
Document metadata (in the document itself)
File metadata (--meta-file)

Example:

apex document.md --meta-file defaults.yml

Reusable Metadata Files:

You can create reusable metadata files for common settings like language and quotes language. This is especially useful for maintaining consistent settings across multiple documents.

Example metadata file (lang-fr.yml):

---
language: fr
quoteslanguage: french
---

Note: In YAML, keys with spaces must be quoted (e.g., "Quotes Language": french). Since Apex normalizes metadata keys (removes spaces, case-insensitive), you can use keys without spaces for cleaner YAML syntax. Both quoteslanguage and "Quotes Language" will work.

Example metadata file (lang-de.mmd):

Language: de
Quotes Language: german

Note: MultiMarkdown format allows spaces in keys, so Quotes Language works without quotes.

Usage:

# Use French language settings for all documents
apex document1.md --meta-file lang-fr.yml
apex document2.md --meta-file lang-fr.yml

# Use German language settings
apex document.md --meta-file lang-de.mmd

Global configuration file:

If you do not provide --meta-file, Apex will automatically look for a global configuration file named config.yml and load it as if it had been passed via --meta-file when it exists:

If $XDG_CONFIG_HOME is set: $XDG_CONFIG_HOME/apex/config.yml
Otherwise: ~/.config/apex/config.yml

This makes it easy to define defaults (mode, language, feature flags, etc.) that apply to all documents unless overridden by document metadata or command-line options. See Configuration for example config.yml files and a complete list of available keys.

Benefits:

Consistency: Ensure all documents use the same language and feature defaults
Reusability: Define configuration once and reuse across many documents
Maintainability: Update defaults in one place
Flexibility: Override with document-specific metadata or command-line flags when needed

Note: The language metadata sets the HTML lang attribute in standalone documents, and if Quotes Language is not specified, it will automatically use the language value for quote styling.

`--meta KEY=VALUE`

Set metadata from the command line. Can be used multiple times or with comma-separated pairs.

Examples:

# Single metadata value
apex document.md --meta title="My Document"

# Multiple metadata values
apex document.md --meta title="My Document" --meta author="John Doe"

# Comma-separated pairs
apex document.md --meta title="My Document",author="John Doe"

# Quoted values with spaces
apex document.md --meta title="My Document Title"

Precedence: Command-line metadata overrides both document metadata and file metadata.

Controlling Options via Metadata

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.

Boolean options accept true/false, yes/no, or 1/0 (case-insensitive, downcased). String options use the value 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 (see Plugins for details on per-document plugin control)
emoji-autocorrect, markdown-in-html
code-line-numbers, highlight-language-only (for syntax highlighting)

Supported string options:

bibliography, csl, title, style (or css), id-format, base-dir, mode
language, quoteslanguage (or Quotes Language), for locale and quote-style control
code-highlight (values: pygments/p/pyg, skylighting/s/sky, shiki/sh, or false/none)
code-highlight-theme / code_highlight_theme (theme/style name for external syntax highlighters)

Example YAML front matter:

---
indices: false
wikilinks: true
bibliography: references.bib
title: My Research Paper
pretty: true
standalone: true
language: en
quoteslanguage: english
---

Example MultiMarkdown metadata:

indices: false
wikilinks: true
bibliography: references.bib
title: My Research Paper

Batch Processing: When processing multiple files with apex *.md, each file can use its own configuration via metadata. You can also use --meta-file or a global config.yml to specify shared configuration that applies to all processed files.

# Process all markdown files, each with its own configuration
apex *.md

# Process all files with a shared configuration file
apex *.md --meta-file defaults.yml

Note: If mode is specified in metadata, it resets all options to that mode's defaults before applying other metadata options. This ensures mode-specific defaults are applied first.

Citations and Bibliography

`--bibliography FILE`

Specify a bibliography file in BibTeX, CSL JSON, or CSL YAML format. Can be used multiple times to load multiple bibliography files.

Supported formats:

BibTeX (.bib) - Standard bibliography format
CSL JSON (.json) - Citation Style Language JSON format
CSL YAML (.yml, .yaml) - Citation Style Language YAML format

Behavior:

Citations are automatically enabled when this option is used
Bibliography can also be specified in document metadata (see Citations)
Multiple bibliography files are merged together
Relative paths are resolved using the base directory (see --base-dir)

Examples:

# Single bibliography file
apex document.md --bibliography refs.bib

# Multiple bibliography files
apex document.md --bibliography refs1.bib --bibliography refs2.bib

# With base directory for relative paths
apex document.md --bibliography references.bib --base-dir /path/to/docs

Input:

See [@doe99] for details.

<!-- REFERENCES -->

Output:

<p>See <span class="citation" data-cites="doe99">(Doe, John 1999)</span> for details.</p>
<div id="refs" class="references csl-bib-body">
<div id="ref-doe99" class="csl-entry">Doe, John 1999. <em>Article Title</em>. <em>Journal Name</em> 1: 1--10</div>
</div>

`--csl FILE`

Specify a Citation Style Language (CSL) file for formatting citations and bibliography.

Behavior:

Citations are automatically enabled when this option is used
CSL file can also be specified in document metadata
If no CSL file is specified, a default author-date style is used

Example:

apex document.md --bibliography refs.bib --csl apa.csl

`--no-bibliography`

Suppress bibliography output even when citations are present in the document.

Example:

apex document.md --bibliography refs.bib --no-bibliography

Note: Citations will still be processed and formatted, but the bibliography section will not be generated.

`--link-citations`

Link citations to their corresponding bibliography entries. Citations will include href attributes pointing to the bibliography entry.

Example:

apex document.md --bibliography refs.bib --link-citations

Output with --link-citations:

<p>See <a href="#ref-doe99" class="citation" data-cites="doe99">(Doe, John 1999)</a> for details.</p>

Output without --link-citations:

<p>See <span class="citation" data-cites="doe99">(Doe, John 1999)</span> for details.</p>

`--show-tooltips`

Enable tooltips on citations when hovering (requires CSS support).

Example:

apex document.md --bibliography refs.bib --show-tooltips

Note: This adds title attributes to citation links. CSS is required to style the tooltips.

For complete documentation of citation syntax and bibliography features, see Citations.

Indices

Note: Indices are supported in MultiMarkdown and unified modes. Enabled by default in these modes.

`--indices`

Enable index processing with mmark, TextIndex, and Leanpub syntax support.

Default: Enabled in MultiMarkdown and unified modes

Behavior:

Enables mmark syntax ((!item), (!item, subitem), (!!item, subitem)), TextIndex syntax ({^}, [term]{^}), and Leanpub syntax ({i: term}, {i: "Main!sub"})
Index entries are collected during parsing
Index is automatically generated at the end of the document or at  marker
Entries are sorted alphabetically and can be grouped by first letter

Example:

apex document.md --indices

Input:

This is about protocols (!Protocol).

And implementations (!Implementation).

Output:

<p>This is about protocols <span class="index" id="idxref-0"></span>.</p>
<p>And implementations <span class="index" id="idxref-1"></span>.</p>
<h1 id="index-section">Index</h1>
<div class="index">
...
</div>

`--no-indices`

Disable index processing entirely.

Example:

apex document.md --no-indices

Note: When disabled, index syntax is treated as plain text and no index markers or index section are generated.

`--no-index`

Suppress index generation while still creating index markers in the document.

Example:

apex document.md --no-index

Behavior:

Index markers (<span class="index">) are still created in the document
Index section is not generated at the end
Useful when you want to mark terms but generate the index separately

For complete documentation of index syntax, see Syntax.

`--hardbreaks`

Treat newlines as hard breaks (GFM style). Newlines become <br> tags.

apex document.md --hardbreaks

`--widont`

Prevent short widows in headings by inserting non-breaking spaces ( ) between trailing words when their combined length (including spaces) is 10 characters or less. Applies to h1-h6 headings.

Behavior:

Works backwards from the end of heading text
Combines trailing words until total length exceeds 10 characters
Replaces spaces with   between those words
Preserves HTML tags within headings

Examples:

# Enable widont for headings
apex document.md --widont

Input:

# woe is me
# hello world
# introduction to the topic

Output with --widont:

<h1>woe&nbsp;is&nbsp;me</h1>
<h1>hello&nbsp;world</h1>
<h1>introduction to&nbsp;the&nbsp;topic</h1>

The algorithm works backwards from the end of the heading, combining trailing words until the combined length (including spaces) exceeds 10 characters. This ensures that if the heading wraps, the trailing portion will be more than 10 characters, preventing a short widow. In the last example, "the topic" (9 characters) would create a short widow, so the algorithm includes "to" as well, making "to the topic" (12 characters), which becomes to the topic.

Configuration:

---
widont: true
---

`--code-is-poetry`

Treat code blocks without a language as poetry by adding the poetry class. Automatically enables --highlight-language-only.

Behavior:

Applies to both fenced code blocks (```) and indented code blocks (4 spaces/tab)
Only affects code blocks that don't have a language specified
Adds class="poetry" to the <code> element
Automatically enables --highlight-language-only to prevent highlighting of unlanguaged blocks

Examples:

# Treat unlanguaged code blocks as poetry
apex document.md --code-is-poetry

Input:

This is a plain code block without a language.


```python
def hello():
    print("Hello!")


**Output with `--code-is-poetry`:**
```html
<pre><code class="poetry">This is a plain code block
without a language.
</code></pre>

<pre><code class="language-python">def hello():
    print("Hello!")
</code></pre>

Configuration:

---
code-is-poetry: true
---

`--markdown-in-html`, `--no-markdown-in-html`

Enable or disable markdown processing inside HTML blocks with markdown attributes (e.g., <div markdown="1">).

Default behavior:

Enabled in unified mode
Disabled in commonmark, gfm, mmd, kramdown modes

Behavior:

When enabled, processes markdown content inside HTML elements with markdown attributes
For block-level HTML elements, blank lines inside are typically required for markdown parsing (maintains compatibility with other processors)
When disabled, markdown inside HTML blocks is not processed

Examples:

# Enable markdown in HTML (unified mode default)
apex document.md --markdown-in-html

# Disable markdown in HTML
apex document.md --no-markdown-in-html

Input:

<div markdown="1">
This is **bold** text.
</div>

Output with --markdown-in-html:

<div>
<p>This is <strong>bold</strong> text.</p>
</div>

Output with --no-markdown-in-html:

<div markdown="1">
This is **bold** text.
</div>

Configuration:

---
markdown-in-html: true
---

`--random-footnote-ids`

Use hash-based footnote IDs instead of sequential IDs to avoid collisions when combining multiple documents.

Behavior:

Generates an 8-character hexadecimal hash from document content
Prefixes footnote IDs with the hash (e.g., fn-a7b3c9d2-1, fnref-a7b3c9d2-1)
Updates both id attributes and href attributes in footnote references
Different documents will have different hash prefixes, preventing ID collisions

Examples:

# Use hash-based footnote IDs
apex document.md --random-footnote-ids

Output:

<p>See footnote<a href="#fn-a7b3c9d2-1" id="fnref-a7b3c9d2-1" class="footnote-ref">1</a>.</p>

<section class="footnotes">
<ol>
<li id="fn-a7b3c9d2-1">Footnote content. <a href="#fnref-a7b3c9d2-1" class="footnote-backref">↩</a></li>
</ol>
</section>

Configuration:

---
random-footnote-ids: true
---

`--hashtags`

Convert #tags into span-wrapped hashtags with the mkhashtag class.

Behavior:

Matches # followed by alphanumeric characters
Skips hashtag processing inside code blocks (fenced and indented)
Skips hashtag processing inside HTML attributes
Wraps matched hashtags in <span class="mkhashtag">#tag</span>

Examples:

# Enable hashtag processing
apex document.md --hashtags

Input:

This is a #hashtag in text.
This is not: `#code` in code.

Output with --hashtags:

<p>This is a <span class="mkhashtag">#hashtag</span> in text.</p>
<p>This is not: <code>#code</code> in code.</p>

Configuration:

---
hashtags: true
---

`--style-hashtags`

Use the mkstyledtag class instead of mkhashtag for hashtags. Requires --hashtags.

Behavior:

Changes the class name from mkhashtag to mkstyledtag
Only has effect when --hashtags is also enabled

Examples:

# Use styled hashtag class
apex document.md --hashtags --style-hashtags

Output:

<p>This is a <span class="mkstyledtag">#hashtag</span> in text.</p>

Configuration:

---
hashtags: true
style-hashtags: true
---

`--proofreader`

Treat ==highlight== and ~~delete~~ as CriticMarkup highlight and deletion syntax. Automatically enables CriticMarkup processing.

Behavior:

Converts ==text== to {==text==} (CriticMarkup highlight)
Converts ~~text~~ to {--text--} (CriticMarkup deletion)
Automatically enables enable_critic_markup and sets critic_mode to 2 (markup mode)
Skips processing inside code blocks
This is a preprocessing step that runs before CriticMarkup processing

Examples:

# Enable proofreader mode
apex document.md --proofreader

Input:

This is ==highlighted== text.
This is ~~deleted~~ text.

Output with --proofreader:

<p>This is <mark class="critic">highlighted</mark> text.</p>
<p>This is <del class="critic">deleted</del> text.</p>

Configuration:

---
proofreader: true
---

`--hr-page-break`

Replace <hr> elements with Marked-style page break divs.

Behavior:

Finds all <hr> and <hr /> tags in the HTML output
Replaces them with a specific div structure for page breaks
The replacement includes class="mkpagebreak manualbreak", title="Page break created from HR", data-description="PAGE (HR)", and style="page-break-after:always"

Examples:

# Replace HR with page breaks
apex document.md --hr-page-break

Input:

First section.

---

Second section.

Output with --hr-page-break:

<p>First section.</p>

<div class="mkpagebreak manualbreak" title="Page break created from HR" data-description="PAGE (HR)" style="page-break-after:always">
<span style="display:none">&nbsp;</span></div>

<p>Second section.</p>

Configuration:

---
hr-page-break: true
---

`--title-from-h1`

Use the first H1 heading as the document title when no title is specified via --title or metadata. Requires --standalone.

Behavior:

Extracts the text content from the first <h1> element in the rendered HTML
Strips HTML tags from the heading text
Uses this as the document title in standalone mode
Only applies when document_title is NULL or empty
The H1 heading itself remains in the document body

Examples:

# Use first H1 as title
apex document.md --standalone --title-from-h1

Input:

# My Document Title

Content here.

Output with --title-from-h1:

<html>
<head>
<title>My Document Title</title>
...
</head>
<body>
<h1>My Document Title</h1>
<p>Content here.</p>
</body>
</html>

Configuration:

---
title-from-h1: true
standalone: true
---

`--page-break-before-footnotes`

Insert a Marked-style page break before the footnotes section.

Behavior:

Finds the <section class="footnotes"> element
Inserts a page break div immediately before it
The page break includes title="Page break created before footnotes" and data-description="PAGE (Footnotes)"

Examples:

# Insert page break before footnotes
apex document.md --page-break-before-footnotes

Output:

<div class="mkpagebreak manualbreak" title="Page break created before footnotes" data-description="PAGE (Footnotes)" style="page-break-after:always">
<span style="display:none">&nbsp;</span></div>

<section class="footnotes">
...
</section>

Configuration:

---
page-break-before-footnotes: true
---

`--[no-]sup-sub`

Control MultiMarkdown-style superscript and subscript syntax.

Syntax:

The ^ character creates superscript for the text immediately following it. The superscript stops at the first space, punctuation, or newline.
The ~ character creates subscript when used within a word/identifier with paired tildes (e.g., H~2~O creates H₂O). When tildes are at word boundaries (e.g., ~text~), they create underline instead.

Important: Subscript uses paired tildes within word boundaries. The tildes must be part of a word/identifier (alphanumeric characters) to create subscript. Tildes at word boundaries create underline.

Default behavior by mode:

Enabled in: unified, multimarkdown
Disabled in: commonmark, gfm, kramdown

Examples:

# Enable sup/sub in GFM mode
apex document.md --mode gfm --sup-sub

# Disable sup/sub in unified mode
apex document.md --mode unified --no-sup-sub

Input:

Water: H~2~O          # Subscript (tildes within word)
Area: m^2              # Superscript
Formula: E = mc^2      # Superscript
Chemical: H~2~SO~4~    # Multiple subscripts within word
~h2o~                  # Underline (tildes at word boundaries)

`--[no-]strikethrough`

Control GFM-style strikethrough processing (~~text~~).

Default behavior by mode:

Enabled in: gfm, unified
Disabled in: commonmark, mmd, kramdown

Examples:

# Enable strikethrough in CommonMark or other modes that don't have it by default
apex document.md --mode commonmark --strikethrough

# Disable strikethrough in GFM or unified mode
apex document.md --mode gfm --no-strikethrough

Input:

This is ~~strikethrough~~ text.

Output with strikethrough enabled:

<p>This is <del>strikethrough</del> text.</p>

Note: When using --proofreader, ~~text~~ is converted to CriticMarkup deletion syntax ({--text--}) before strikethrough processing. The strikethrough flag controls GFM-style ~~...~~ processing only.

`--[no-]divs`

Control Pandoc fenced divs syntax processing. Fenced divs allow you to create HTML <div> elements with attributes using a special fence syntax (::::: {#id .class} ... :::::).

Default behavior:

Enabled in: unified mode
Disabled in: all other modes

Examples:

# Enable fenced divs in unified mode (default)
apex document.md --mode unified --divs

# Disable fenced divs in unified mode
apex document.md --mode unified --no-divs

Input:

::::: {#special .sidebar}
Here is a paragraph.

And another.
:::::

Output:

<div id="special" class="sidebar">
<p>Here is a paragraph.</p>
<p>And another.</p>
</div>

Features:

Opening fences require at least 3 colons and must have attributes
Closing fences need at least 3 colons (no attributes)
Supports nested divs
Attributes can include ID ({#id}), classes ({.class}), and custom attributes (key="value")
Single unbraced word is treated as a class name
Attributes can optionally be followed by trailing colons
Supports different HTML block elements using >blocktype syntax (e.g., ::: >aside {.sidebar} ... ::: creates <aside> instead of <div>)

See Syntax for complete documentation, including block types like >aside, >article, >section, >details, and >summary.

`--[no-]spans`

Control Pandoc-style bracketed spans syntax ([text]{IAL}). Bracketed spans convert to HTML <span> elements with attributes.

Default behavior:

Enabled in: unified mode
Disabled in: all other modes

Examples:

# Enable bracketed spans in unified mode (default)
apex document.md --mode unified --spans

# Disable bracketed spans in unified mode
apex document.md --mode unified --no-spans

Input:

This is [highlighted text]{.highlight} in a sentence.
[Custom span]{#id .class key="value"}

Output:

<p>This is <span class="highlight">highlighted text</span> in a sentence.</p>
<p><span id="id" class="class" key="value">Custom span</span></p>

Features:

Supports IAL syntax for attributes (ID, classes, custom attributes)
Works with both Kramdown-style {: #id .class} and Pandoc-style {#id .class} attribute formats
Can be nested within other inline elements

See Syntax for complete documentation.

`--[no-]emoji-autocorrect`

Control emoji name autocorrect. When enabled, emoji names like :rocket: are automatically converted to Unicode emoji characters.

Default behavior:

Enabled in: unified mode
Disabled in: all other modes

Examples:

# Enable emoji autocorrect in unified mode (default)
apex document.md --mode unified --emoji-autocorrect

# Disable emoji autocorrect in unified mode
apex document.md --mode unified --no-emoji-autocorrect

# Enable emoji autocorrect in GFM mode
apex document.md --mode gfm --emoji-autocorrect

Input:

Success! :rocket: :tada: :sparkles:
I :heart: Markdown!

Output with emoji-autocorrect enabled:

<p>Success! 🚀 🎉 ✨</p>
<p>I ❤️ Markdown!</p>

Output with emoji-autocorrect disabled:

<p>Success! :rocket: :tada: :sparkles:</p>
<p>I :heart: Markdown!</p>

Note: Apex supports 350+ GitHub emoji names. See Syntax for more information.

Output:

<p>Water: H<sub>2</sub>O</p>
<p>Area: m<sup>2</sup></p>
<p>Formula: E = mc<sup>2</sup></p>
<p>Chemical: H<sub>2</sub>SO<sub>4</sub></p>
<p><u>h2o</u></p>

`--[no-]unsafe`

Control whether raw HTML is allowed in output.

Default behavior by mode:

Enabled in: unified, multimarkdown, kramdown
Disabled in: commonmark, gfm

When disabled, HTML tags are escaped or removed for security (GFM tag filter).

Examples:

# Enable raw HTML in GFM mode
apex document.md --mode gfm --unsafe

# Disable raw HTML in unified mode
apex document.md --mode unified --no-unsafe

Input:

<div class="custom">Custom HTML</div>

Output with unsafe enabled:

<div class="custom">Custom HTML</div>

Output with unsafe disabled (GFM mode):

<p>&lt;div class="custom"&gt;Custom HTML&lt;/div&gt;</p>

`--[no-]wikilinks`

Control wiki link syntax ([[PageName]]).

Default: Disabled in all modes

Wiki links must be explicitly enabled with --wikilinks to process [[PageName]], [[Page|Display]], and [[Page#Section]] syntax.

Examples:

# Enable wiki links in unified mode
apex document.md --mode unified --wikilinks

# Enable wiki links in any mode
apex document.md --mode gfm --wikilinks

# Disable wiki links (explicit)
apex document.md --no-wikilinks

Input:

Check out [[Main Page]] for details.
Or see [[Main Page|the main page]] with custom text.
Link to [[Main Page#Section]] for a specific section.

Output with wikilinks enabled (default - spaces converted to dashes):

<p>Check out <a href="Main-Page">Main Page</a> for details.</p>
<p>Or see <a href="Main-Page">the main page</a> with custom text.</p>
<p>Link to <a href="Main-Page#Section">Main Page</a> for a specific section.</p>

Output with wikilinks disabled:

<p>Check out [[Main Page]] for details.</p>
<p>Or see [[Main Page|the main page]] for custom text.</p>
<p>Link to [[Main Page#Section]] for a specific section.</p>

`--wikilink-space MODE`

Control how spaces in wiki link page names are handled in the generated URL.

Default: dash (spaces converted to dashes)

Options:

dash - Convert spaces to dashes: [[Home Page]] → href="Home-Page"
none - Remove spaces: [[Home Page]] → href="HomePage"
underscore - Convert spaces to underscores: [[Home Page]] → href="Home_Page"
space - Keep spaces (rendered as %20 in HTML): [[Home Page]] → href="Home%20Page"

Examples:

# Use dashes (default)
apex document.md --wikilinks --wikilink-space dash

# Remove spaces
apex document.md --wikilinks --wikilink-space none

# Use underscores
apex document.md --wikilinks --wikilink-space underscore

# Keep spaces (not recommended for URLs)
apex document.md --wikilinks --wikilink-space space

`--wikilink-extension EXT`

Add a file extension to wiki link URLs.

Default: No extension

The extension is automatically prefixed with a dot if not provided. For example, --wikilink-extension html creates href="Page.html" and --wikilink-extension .html also creates href="Page.html".

Examples:

# Add .html extension
apex document.md --wikilinks --wikilink-extension html

# Add .md extension
apex document.md --wikilinks --wikilink-extension md

# Combine with space mode
apex document.md --wikilinks --wikilink-space dash --wikilink-extension html

Input:

See [[Home Page]] for details.

Output with --wikilink-space dash --wikilink-extension html:

<p>See <a href="Home-Page.html">Home Page</a> for details.</p>

`--[no-]wikilink-sanitize`

Sanitize wiki link URLs for cleaner, more compatible links.

Default: Disabled

When enabled, sanitization performs:

Removes apostrophes and quotation marks (', ", `, ´, ', ', ", ")
Converts select Latin-1 characters to ASCII (e.g., é → e)
Converts uppercase to lowercase
Replaces non-ASCII and any non-alphanumeric ASCII characters with the space-mode character (except / and . which are preserved)
Removes duplicate space-mode characters
Removes leading and trailing space-mode characters

Examples:

# Enable sanitization with dash mode
apex document.md --wikilinks --wikilink-sanitize --wikilink-space dash

# Disable sanitization
apex document.md --wikilinks --no-wikilink-sanitize

Input:

See [[O'Brien's Page]] for details.
Check out [[Hello   World!!!]].
Link to [[path/to/FILE.MD]].

Output with --wikilink-sanitize --wikilink-space dash:

<p>See <a href="obriens-page">O'Brien's Page</a> for details.</p>
<p>Check out <a href="hello-world">Hello   World!!!</a>.</p>
<p>Link to <a href="path/to/file.md">path/to/FILE.MD</a>.</p>

Output without sanitization:

<p>See <a href="O'Brien's-Page">O'Brien's Page</a> for details.</p>
<p>Check out <a href="Hello---World!!!">Hello   World!!!</a>.</p>
<p>Link to <a href="path/to/FILE.MD">path/to/FILE.MD</a>.</p>

Note: Sanitization preserves / (forward slashes) and . (periods) in paths, making it suitable for hierarchical wiki link structures while cleaning up special characters and ensuring lowercase URLs.

Configuration:

---
wikilink-sanitize: true
wikilink-space: dash
---

Critic Markup Options

`--accept`

Accept all Critic Markup changes. Applies all additions, removes all deletions, keeps substitutions.

apex document.md --accept

Behavior:

{++add++} → add (kept)
{--del--} → (removed)
{~~old~>new~~} → new (kept)
{==mark==} → mark (markup removed)
{>>comment<<} → (removed)

`--reject`

Reject all Critic Markup changes. Reverts all changes, keeps original text.

apex document.md --reject

Behavior:

{++add++} → (removed)
{--del--} → del (kept)
{~~old~>new~~} → old (kept)
{==mark==} → mark (markup removed)
{>>comment<<} → (removed)

Input/Output

Reading from stdin

If no file is specified, Apex reads from stdin:

echo "# Hello" | apex
cat document.md | apex > output.html

Writing to stdout

By default, Apex writes to stdout. Use -o or > to redirect:

apex document.md > output.html
apex document.md -o output.html

Combining Options

You can combine multiple options:

# Standalone document with custom title and stylesheet, pretty-printed
apex document.md --standalone --title "Report" --style report.css --pretty

# GFM mode with no header IDs
apex --mode gfm --no-ids document.md

# Unified mode with MMD-style header IDs
apex --mode unified --id-format mmd document.md

Option Precedence

Options are processed in order. Later options override earlier ones:

# This will use GFM mode (unified is default, but --mode gfm overrides)
apex document.md --mode unified --mode gfm

Examples

Blog Post

apex post.md --standalone --title "My Blog Post" --style blog.css --pretty -o post.html

GitHub-Compatible Output

apex README.md --mode gfm --pretty > README.html

Documentation with Custom IDs

apex docs.md --standalone --title "Documentation" --id-format mmd --pretty

Review Document with Critic Markup

# Show all changes
apex draft.md

# Apply all changes (final version)
apex draft.md --accept

# Revert all changes (original version)
apex draft.md --reject

Academic Document with Citations

# Process document with bibliography
apex paper.md --bibliography refs.bib

# With citation style and linked citations
apex paper.md --bibliography refs.bib --csl apa.csl --link-citations

# Multiple bibliography files
apex paper.md --bibliography refs1.bib --bibliography refs2.bib

Plugin Options

`--[no-]plugins`

Enable or disable plugin processing.

Default: Plugins are disabled unless you explicitly enable them.
Enable: --plugins
Disable: --no-plugins

Plugins can also be enabled per document using metadata (e.g. plugins: true). See Plugins for details.

apex --plugins document.md

`--list-plugins`

List installed plugins and available plugins from the central directory.

Prints a ## Installed Plugins section for plugins found in your user plugin directory.
Prints a --- separator and a ## Available Plugins section with plugins from the remote JSON directory that are not already installed.

apex --list-plugins

`--install-plugin ID`

Install a plugin from the central directory by its id.

Fetches apex-plugins.json from the ApexMarkdown/apex-plugins repository.
Locates the plugin entry with matching id.
Clones the plugin repository into your user plugin directory (e.g. ~/.config/apex/plugins/ID).
If the plugin’s plugin.yml defines a post_install command, Apex runs it from the plugin directory after cloning.

apex --install-plugin kbd

`--uninstall-plugin ID`

Uninstall a locally installed plugin by its id.

Verifies that the plugin directory exists under the user plugin path.
Prompts for confirmation before deleting the plugin directory.
Removes only the plugin’s directory; support data under .../apex/support is left intact.

apex --uninstall-plugin kbd

Quick Links

Getting Started - Your first steps with Apex
Installation - How to build and install Apex
Usage - Basic usage examples
Syntax - Complete syntax reference for unified mode
Tables - Complete table syntax reference including rowspan, colspan, alignment, and captions
Inline Attribute Lists - IALs and ALDs guide with examples
Modes - Understanding processor modes
Command Line Options - All CLI flags explained
Rendering Markdown in the Terminal - Terminal output formats (-t terminal, -t terminal256), --width, --theme, and theming
Generating Man Pages - Generate man pages from Markdown using apex -t man
Multi-file Documents - Combining multiple files with --combine, --mmd-merge, and includes
Citations - Citations and bibliography guide
Indices - Index generation with mmark and TextIndex syntax
Metadata Transforms - Transform metadata values with [%key:transform]
Integrating with Pandoc - Use Apex with Pandoc for DOCX, PDF, and more
Using Apex with Jekyll - Use the apex-ruby gem as Jekyll’s Markdown converter (untested; feedback welcome)
Header IDs - How header IDs are generated
C API - Programmatic API documentation
Writing Tests - How to add tests for new features
Xcode Integration - Using Apex in Xcode projects
Examples - Practical usage examples
Plugins - Plugin system, examples, and recipes
Filters - AST filters (Pandoc-style JSON), examples, and usage
Troubleshooting - Common issues and solutions
Credits - Acknowledgments and links to related projects

Uh oh!

Command Line Options

Command Line Options

Basic Options

-h, --help

-v, --version

--[no-]progress

--combine

--mmd-merge

-m, --mode MODE

-o, --output FILE

Output Options

-s, --standalone

--xhtml

--strict-xhtml

--style FILE, --css FILE

--embed-css

--width N

-p, --paginate

--code-highlight TOOL

--code-line-numbers

--highlight-language-only

--code-highlight-theme THEME

--list-themes

--script VALUE

--title TITLE

--pretty

--aria

AST Filters

--filter NAME

--filters

--lua-filter FILE

--no-strict-filters

--list-filters

--install-filter ID-or-URL

--uninstall-filter ID

Plugin Management

--plugins, --no-plugins

--list-plugins

--install-plugin ID-or-URL

--uninstall-plugin ID

Header ID Options

--id-format FORMAT

--no-ids

--header-anchors

Table Options

--relaxed-tables

--no-relaxed-tables

--per-cell-alignment

--no-per-cell-alignment

--captions POSITION

--no-tables

List Options

--[no-]alpha-lists

--[no-]mixed-lists

Feature Flags

--no-footnotes

--no-smart

--no-math

--[no-]autolink

--obfuscate-emails

--includes, --no-includes

Image Embedding

--embed-images

--[no-]image-captions

Path Resolution

--base-dir DIR

--[no-]transforms

Metadata Options

--meta-file FILE

--meta KEY=VALUE

Controlling Options via Metadata

Citations and Bibliography

--bibliography FILE

--csl FILE

--no-bibliography

--link-citations

--show-tooltips

Indices

--indices

`-h, --help`

`-v, --version`

`--[no-]progress`

`--combine`

`--mmd-merge`

`-m, --mode MODE`

`-o, --output FILE`

`-s, --standalone`

`--xhtml`

`--strict-xhtml`

`--style FILE`, `--css FILE`

`--embed-css`

`--width N`

`-p, --paginate`

`--code-highlight TOOL`

`--code-line-numbers`

`--highlight-language-only`

`--code-highlight-theme THEME`

`--list-themes`

`--script VALUE`

`--title TITLE`

`--pretty`

`--aria`

`--filter NAME`

`--filters`

`--lua-filter FILE`

`--no-strict-filters`

`--list-filters`

`--install-filter ID-or-URL`

`--uninstall-filter ID`

`--plugins`, `--no-plugins`

`--list-plugins`

`--install-plugin ID-or-URL`

`--uninstall-plugin ID`

`--id-format FORMAT`

`--no-ids`

`--header-anchors`

`--relaxed-tables`

`--no-relaxed-tables`

`--per-cell-alignment`

`--no-per-cell-alignment`

`--captions POSITION`

`--no-tables`

`--[no-]alpha-lists`

`--[no-]mixed-lists`

`--no-footnotes`

`--no-smart`

`--no-math`

`--[no-]autolink`

`--obfuscate-emails`

`--includes`, `--no-includes`

`--embed-images`

`--[no-]image-captions`

`--base-dir DIR`

`--[no-]transforms`

`--meta-file FILE`

`--meta KEY=VALUE`

`--bibliography FILE`

`--csl FILE`

`--no-bibliography`

`--link-citations`

`--show-tooltips`

`--indices`

`--no-indices`

`--no-index`

`--hardbreaks`

`--widont`

`--code-is-poetry`

`--markdown-in-html`, `--no-markdown-in-html`

`--random-footnote-ids`

`--hashtags`

`--style-hashtags`

`--proofreader`

`--hr-page-break`

`--title-from-h1`

`--page-break-before-footnotes`

`--[no-]sup-sub`

`--[no-]strikethrough`

`--[no-]divs`

`--[no-]spans`