Configuration

Configuration

Leafmark's primary project config is .leafmark/config.json. The legacy leafmark.json is read only when the modern file is absent.

Complete shape

{
  "order": ["introduction.md", "method.md"],
  "frontmatter": "_frontmatter.md",
  "latexTemplate": "templates/report.latex",
  "htmlTemplate": "templates/report.html",
  "fonts": {
    "pdf": "Aptos",
    "mono": "JetBrains Mono",
    "pdfFiles": {
      "path": "fonts",
      "upright": "Body-Regular.ttf",
      "bold": "Body-Bold.ttf",
      "italic": "Body-Italic.ttf",
      "boldItalic": "Body-BoldItalic.ttf",
      "scale": 1
    },
    "css": ["fonts/web.css"],
    "latexInclude": "fonts/custom-fonts.tex"
  },
  "plugins": [
    "plugins/cleanup.lua",
    {
      "luaFilter": "plugins/format.lua",
      "args": ["--wrap=none"],
      "pdfArgs": [],
      "htmlArgs": ["--section-divs"],
      "docxArgs": []
    }
  ],
  "pandoc": {
    "args": ["--wrap=none"],
    "pdfArgs": [],
    "htmlArgs": [],
    "docxArgs": []
  },
  "metadata": {
    "title": "Example Report",
    "author": ["Alex Morgan"],
    "toc": true
  }
}

Top-level fields

Field	Type	Purpose
order	string[]	Saved chapter order. Unknown or missing files are skipped; unsaved files follow.
frontmatter	string or false	Metadata file path. Defaults to _frontmatter.md; false disables it.
template	string	Legacy/general template path used as a PDF template fallback.
latexTemplate	string	Pandoc LaTeX template for PDF output.
htmlTemplate	string	Reserved HTML template setting. Use pandoc.htmlArgs where template behavior is needed.
fonts	object	PDF font names/files, HTML font CSS, and LaTeX font includes.
plugins	array	Project Pandoc Lua filters and their arguments.
themePlugins	array	Theme-owned filters, normally written by theme use.
pandoc	object	Raw common and format-specific Pandoc arguments.
metadata	object	Document metadata; same keys as YAML frontmatter.

Precedence

Metadata is merged in this order, with later values winning:

1. Theme defaults installed into project config
2. Project metadata
3. External --config-file metadata
4. _frontmatter.md

For an overlay config, metadata, fonts, and pandoc are shallow-merged with their project counterparts; other top-level overlay values replace project values.

When applying a theme, current project metadata and chapter order are preserved. Theme fonts, Pandoc settings, and theme plugins become active; project plugins remain project-owned.

Frontmatter selection

{ "frontmatter": "metadata/report.yml.md" }

Relative paths resolve from the active project. Set false to rely only on config metadata:

{ "frontmatter": false }

Pandoc arguments

pandoc.args applies to PDF, HTML, and DOCX. Format arrays apply only to their target and come later, so they can override common arguments.

{
  "pandoc": {
    "args": ["--wrap=none"],
    "pdfArgs": ["-V", "papersize=letter"],
    "htmlArgs": ["--section-divs"],
    "docxArgs": ["--reference-doc=reference.docx"]
  }
}

These are passed directly to Pandoc. Invalid or conflicting arguments can break a build; inspect --keep-build-files output when debugging.

Reserved metadata

Do not set header-includes. Leafmark generates the LaTeX preamble under dist/ and stops with an explanatory error if this key is present. fonts-include is also owned by the build/templates.

See Frontmatter Reference, Fonts, and Plugins and Pandoc.