Project Structure

Project Structure

Minimal project

report/
├── .leafmark/
│   └── config.json
├── introduction.md
└── findings.md

Every visible .md file in the project root becomes a chapter except _frontmatter.md and _merged.md. Files beginning with . are ignored.

Full example

report/
├── .leafmark/
│   ├── config.json
│   └── theme/
│       ├── templates/
│       ├── includes/
│       ├── css/
│       ├── fonts/
│       └── filters/
├── _frontmatter.md
├── introduction.md
├── method.md
├── findings.md
├── images/
│   └── diagram.png
├── styles/
│   └── components.css
├── plugins/
│   └── cleanup.lua
├── sources.bib
└── dist/
    └── report.pdf

Important files

.leafmark/config.json

Project configuration in JSON. It stores chapter order, metadata, templates, fonts, plugins, themes, and raw Pandoc arguments. See Configuration. A legacy root-level leafmark.json remains supported when the modern file is absent.

_frontmatter.md

Optional YAML metadata between --- markers. It is useful when authors prefer YAML or a theme has structured metadata. Its values override metadata in the JSON config. See Frontmatter Reference.

Chapter files

Chapters are concatenated into one Pandoc document. Their names do not need numeric prefixes. When no saved order exists, numeric prefixes sort first and remaining names use natural filename order.

sources.bib

The default bibliography file when one exists. It uses BibTeX/BibLaTeX syntax and is processed with Pandoc citeproc and Leafmark's bundled APA CSL. See Markdown and Citations.

dist/

Default output for folder builds. Temporary files such as _merged.md, generated LaTeX includes, and rendered HTML block images are removed unless --keep-build-files is set.

Project discovery

A directory is recognized as a Leafmark project when it contains any of:

• .leafmark/config.json
• leafmark.json
• _frontmatter.md

If the selected directory is not itself a project but contains project/ with one of those markers, Leafmark recognizes the older copied-project layout automatically.

Single-file builds

pnpx @skxv/leafmark ./notes/chapter.md

The containing folder becomes the project root, only that chapter is selected, and output defaults to the same folder rather than dist/.

Path resolution

Project configuration paths—styles, fonts, templates, filters, bibliographies, and covers—are resolved from the active project or bundle unless absolute. Pandoc's resource path includes the active project, parent project, input root, and Leafmark's packaged resources.

Bundles

A project can contain self-configured subprojects that build into separate output folders. See Bundles and Chapter Ordering.