Skip to content

Usage

Jump to bottom
Brett Terpstra edited this page Jan 14, 2026 · 3 revisions

Usage

This page covers basic usage patterns for Apex.

Command Line

Basic Conversion

Convert a Markdown file to HTML:

apex input.md > output.html

Reading from stdin

cat document.md | apex > output.html

Or:

echo "# Hello" | apex

Preprocessing with md-fixup

For cleaning up Markdown before processing, you can pipe through md-fixup:

md-fixup input.md | apex > output.html

md-fixup can fix common Markdown issues and apply search-and-replace transformations before Apex processes the document.

Writing to a File

apex input.md -o output.html

Processor Modes

Specify a processor mode with --mode:

# Unified mode (default - all features)
apex document.md

# GFM mode
apex --mode gfm document.md

# Kramdown mode
apex --mode kramdown document.md

# MultiMarkdown mode
apex --mode mmd document.md

# CommonMark mode
apex --mode commonmark document.md

See Modes for details on what each mode supports.

Output Options

Standalone HTML Document

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

apex document.md --standalone

With Custom Title

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

With Stylesheet

apex document.md --standalone --style styles.css --title "My Document"

Pretty-Printed HTML

Format HTML with indentation and whitespace:

apex document.md --pretty

Header IDs

Default Behavior

By default, Apex generates header IDs automatically using GFM rules:

# My Header

Becomes:

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

Different ID Formats

# GFM format (default)
apex document.md --id-format gfm

# MultiMarkdown format
apex document.md --id-format mmd

# Kramdown format
apex document.md --id-format kramdown

Disable Header IDs

apex document.md --no-ids

Use Anchor Tags

Generate <a> anchor tags instead of id attributes:

apex document.md --header-anchors

See Header IDs for complete details.

Tables

Standard Tables

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |

Relaxed Tables

In unified and kramdown modes, relaxed tables are enabled by default:

one | two
1 | 2

No separator row required! To disable:

apex document.md --no-relaxed-tables

Critic Markup

Review Mode (Default)

Show all changes with HTML markup:

apex document.md

Accept All Changes

Apply all additions, remove all deletions:

apex document.md --accept

Reject All Changes

Revert all changes, keep original text:

apex document.md --reject

Feature Flags

Disable specific features:

# Disable tables
apex document.md --no-tables

# Disable footnotes
apex document.md --no-footnotes

# Disable smart typography
apex document.md --no-smart

# Disable math
apex document.md --no-math

Configuration

Apex settings can be controlled from three places:

  • Per-document metadata (YAML/MultiMarkdown/Pandoc front matter in the document itself)
  • External metadata files passed with --meta-file
  • A global configuration file at $XDG_CONFIG_HOME/apex/config.yml (or ~/.config/apex/config.yml when XDG_CONFIG_HOME is not set)

If you do not pass --meta-file, Apex will automatically load config.yml from the XDG or ~/.config path when it exists, as if you had passed it via --meta-file. See Configuration for a complete list of available keys, example config files, and details on precedence between config files, document metadata, and command-line flags.

Examples

Blog Post

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

Documentation

apex document.md --pretty --standalone --title "Documentation" > docs.html

GitHub-Compatible

apex --mode gfm document.md > output.html

Programmatic Usage

For using Apex in your own applications, see the C API documentation.

For Xcode integration, see Xcode Integration.

Copyright 2025 Brett Terpstra, All Rights Reserved | MIT License

Quick Links

Clone this wiki locally