Configuration

Configuration

Apex offers a flexible configuration system so you can define defaults once and reuse them across many documents, while still allowing per-document and per-invocation overrides.

This page covers:

• Where configuration comes from
• The global config.yml file (XDG-aware)
• Using --meta-file with reusable config files
• Per-document metadata (front matter)
• Precedence rules between these sources
• Available configuration keys and their possible values

---

Configuration sources

Apex can read configuration from four main places:

1. Global configuration file
   • $XDG_CONFIG_HOME/apex/config.yml when XDG_CONFIG_HOME is set
   • ~/.config/apex/config.yml when XDG_CONFIG_HOME is not set
2. Project configuration file
   • .apex/config.yml in your project
   • Searched in this order:
     • Current working directory: ./.apex/config.yml
     • --base-dir DIR: DIR/.apex/config.yml
     • Git repository root (when inside a work tree): <git-root>/.apex/config.yml
3. External metadata files
   • Any file you pass explicitly with --meta-file FILE
   • Shared configuration for multiple documents
4. Per-document metadata
   • YAML, MultiMarkdown, or Pandoc-style metadata at the top of the document
   • Used for settings that are specific to a single document

On top of all of these, you can always pass command-line flags such as --mode, --pretty, --no-tables, etc.

---

Global config file: config.yml

When you run apex, Apex will check for a global configuration file named config.yml in an XDG-aware location:

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

If the file exists, Apex loads it and merges its metadata with any project config, explicit --meta-file, document metadata, and --meta command-line metadata using the normal precedence rules (see below).

This makes config.yml ideal for defining project‑agnostic defaults, such as:

• Default mode (e.g. unified, gfm, mmd)
• Default language and quoteslanguage
• Common feature flags (pretty, standalone, indices, wikilinks, etc.)
• Default bibliography style for your writing workflow

Example config.yml

---
# Default processor mode and output style
mode: unified
standalone: true
pretty: true

# Locale and quotation style
language: en
quoteslanguage: english

# Common feature flags
autolink: true
includes: true
relaxed-tables: true
sup-sub: true

# Index and bibliography defaults
indices: true
group-index-by-letter: true
bibliography: references.bib
csl: apa.csl

# Syntax highlighting (optional)
code-highlight: pygments
code-line-numbers: true
highlight-language-only: true
---

With this configuration in place, a simple command like:

apex document.md

will automatically use your global defaults. You can then override any of them with per-document metadata or CLI flags when needed.

---

Project config file: .apex/config.yml

For project-level defaults, you can add a .apex/config.yml file to your project. Apex will look for the first existing file in this order:

1. ./.apex/config.yml (current working directory)
2. BASE/.apex/config.yml when you pass --base-dir BASE
3. <git-root>/.apex/config.yml when the current directory is inside a Git work tree

If found, Apex merges the project config on top of the global config, so project keys override global ones while still inheriting unspecified global defaults.

---

Reusable config files with --meta-file

For additional project-specific or task-specific configurations, use --meta-file to point to a reusable metadata file:

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

These files use the same metadata keys as config.yml and document front matter.

Example project config (project-defaults.yml)

---
mode: unified
standalone: true
pretty: true

# Project-specific bibliography
bibliography: project-refs.bib
csl: chicago-note-bibliography.csl

# Enable wiki links and relaxed tables for this project
wikilinks: true
relaxed-tables: true
---

You can reuse the same project-defaults.yml for many documents:

apex chapter1.md --meta-file project-defaults.yml
apex chapter2.md --meta-file project-defaults.yml
apex appendix.md --meta-file project-defaults.yml

If global and/or project config files are also present, the explicit --meta-file is merged on top of them; overall precedence is determined by the rules below.

---

Per-document metadata

Each document can define its own metadata in YAML, MultiMarkdown, or Pandoc formats. Apex extracts this metadata before processing, merges it with any file/config metadata, and then applies it to options.

YAML front matter example

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

# Introduction
...

MultiMarkdown metadata example

Title: My Research Paper
Author: Jane Doe
Mode: unified
Standalone: true
Pretty: true
Indices: false
WikiLinks: true
Bibliography: references.bib
Language: en
Quotes Language: english

# Introduction
...

Apex normalizes keys (case-insensitive, ignores spaces and dashes), so Quotes Language, quoteslanguage, and quotes-language are treated equivalently.

---

Precedence and merging

When Apex builds the final configuration for a run, it merges all sources in this order:

1. File metadata (lowest precedence)
   • Global config.yml (if present)
   • Project .apex/config.yml (if present)
   • Any metadata file provided via --meta-file
2. Document metadata
   • YAML/MultiMarkdown/Pandoc metadata inside the document
3. Command-line metadata
   • Values passed via --meta KEY=VALUE
4. Command-line flags
   • Flags like --mode, --pretty, --no-tables, etc.

Later sources override earlier ones. In practice:

• A document can override defaults from config.yml or --meta-file
• --meta values can override both document and file metadata
• Explicit CLI flags (--mode gfm, --no-tables, etc.) still behave as final overrides where applicable

Note: if mode is specified in metadata (file or document), Apex resets options to that mode's defaults before applying other metadata keys, so the mode behaves as if you had passed it on the command line first.

---

Available configuration keys

Configuration keys correspond closely to Apex command-line options. Most options can be controlled via metadata in config.yml, --meta-file files, or per-document metadata.

Boolean options

Boolean keys accept any of the following values (case-insensitive):

• true / false
• yes / no
• 1 / 0

Supported boolean keys include:

• indices – Enable index processing
• wikilinks – Enable wiki link syntax ([[Page]])
• includes – Enable file inclusion
• relaxed-tables – Enable relaxed table parsing
• per-cell-alignment – Enable per-cell alignment markers (colons at start/end of cells)
• alpha-lists – Enable alphabetic list markers
• mixed-lists – Allow mixing list marker types at the same level
• sup-sub – Enable MultiMarkdown-style superscript/subscript
• autolink – Enable automatic URL/email linking
• transforms – Enable metadata transforms ([%key:transform])
• unsafe – Allow raw HTML in output
• tables – Enable/disable table support
• footnotes – Enable/disable footnote support
• smart – Enable/disable smart typography
• math – Enable/disable math support
• ids – Enable/disable automatic header IDs
• header-anchors – Use <a> anchors instead of plain id attributes
• embed-images – Enable base64 image embedding
• link-citations – Link citations to bibliography entries
• show-tooltips – Add tooltips to citations
• suppress-bibliography – Suppress bibliography output
• suppress-index – Suppress index output while still creating markers
• group-index-by-letter – Group index entries alphabetically
• obfuscate-emails – Hex-encode mailto: links and visible email addresses
• pretty – Pretty-print HTML
• standalone – Generate a full HTML document (<html>, <head>, <body>)
• hardbreaks – Treat newlines as <br>
• plugins – Enable plugin processing for this document (see Plugins)
• code-line-numbers – Include line numbers in syntax-highlighted code blocks
• highlight-language-only – Only highlight code blocks that have a language specified
• widont – Prevent short widows in headings by inserting non-breaking spaces between trailing words
• code-is-poetry – Treat code blocks without a language as poetry (adds poetry class, implies highlight-language-only)
• markdown-in-html – Enable markdown processing inside HTML blocks with markdown attributes
• random-footnote-ids – Use hash-based footnote IDs to avoid collisions when combining documents
• hashtags – Convert #tags into span-wrapped hashtags
• style-hashtags – Use mkstyledtag class instead of mkhashtag for hashtags
• proofreader – Treat ==highlight== and ~~delete~~ as CriticMarkup syntax
• hr-page-break – Replace <hr> elements with Marked-style page break divs
• title-from-h1 – Use the first H1 as document title when none is specified
• page-break-before-footnotes – Insert a page break before the footnotes section

String options

String keys take a free-form string value (sometimes with a constrained set of options):

• mode
  • Values: commonmark, gfm, mmd/multimarkdown, kramdown, unified
• id-format
  • Values: gfm, mmd, kramdown
• title
  • Document title (used especially in standalone mode)
• style / css
  • Stylesheet path for standalone documents
• base-dir
  • Base directory used for resolving relative paths (images, includes, etc.)
• bibliography
  • Path to a bibliography file (.bib, .json, .yml, .yaml)
• csl
  • Path to a CSL style file
• language
  • BCP 47 or similar language tag (e.g. en, en-US, fr); sets the HTML lang attribute
• quoteslanguage / Quotes Language
  • Human-readable language name used for quote styling (e.g. english, french, german)
• code-highlight
  • External syntax highlighting tool: pygments (or p/pyg), skylighting (or s/sky), or false/none to disable

You can also use arbitrary keys for your own templates and transforms; Apex simply passes them through to the metadata system so they can be referenced via [%key] and [%key:transform].

---

Putting it all together

A typical setup might look like this:

1. Global defaults in config.yml for your overall writing style and locale.
2. Project config via --meta-file project.yml for bibliography and project-specific settings.
3. Per-document metadata for title, author, and any exceptions to the defaults.
4. Occasional CLI overrides for ad-hoc one-off changes (e.g. --mode gfm for a specific run).

Because all three configuration layers use the same metadata keys, you can gradually refine behavior without repeating yourself:

• Put long‑lived, cross‑project settings in config.yml
• Put project‑scoped settings in --meta-file configs
• Put document‑specific settings in front matter

For more examples of metadata usage and transforms, see Metadata Options and Metadata Transforms.