Camus is a static site generator written in C++23. It reads Markdown posts and theme templates and renders them into a static HTML site, aimed at individuals and teams who want a lightweight publishing pipeline.
On macOS (Apple Silicon) or Linux (amd64), install the latest release with one command:
curl -fsSL https://raw.githubusercontent.com/the-writer/camus/main/scripts/install.sh | bash- CMake 3.28+
- Ninja (recommended) or Make
- A C++23 toolchain
- Optional: Chrome/Chromium/Edge for PDF output
git submodule update --init --recursive
make build # output: build/release/bin/camusThe repository ships a complete example in example/:
cd example
../build/release/bin/camus --buildOr create a new site in an empty directory:
mkdir my-site && cd my-site
/path/to/camus -i # install example camus.yaml, posts (with SUMMARY.md, plus posts/private/), .gitignore and Justfile
/path/to/camus --build # buildcamus looks for Markdown sources in src/ first, then posts/. The generated site is written to dist/html/ (and PDF to dist/pdf/ when configured). Building only happens when explicitly requested with --build, -W or --check; running camus without any option prints usage.
| Command | Description |
|---|---|
camus |
Print usage (does not build) |
camus --build |
Build the site |
camus -w <dir> --build |
Build a site in another workdir |
camus -W |
Watch for changes and serve locally (implies build) |
camus -D --build |
Dry run: parse and render without writing files |
camus --check |
Validate configuration, assets, PDF settings and run a dry build |
camus --check-update |
Check the latest GitHub release and print the download link (no download/install) |
camus --update |
Download and install the latest GitHub release |
camus -i |
Install example camus.yaml, posts (with SUMMARY.md, plus posts/private/), .gitignore and Justfile |
camus --new <dir> |
Create a site directory and install example files |
camus --create <path> |
Create an article .md under src/ or posts/ with a starter template (missing directories are created; last segment is the file name) |
camus --repo [url] |
Run git init; set origin when a URL is provided |
camus --new <dir> --repo <url> |
Create, install and initialize git |
camus -c |
Copy minimal editable resources (assets/css/style.css, assets/js/camus.js, empty assets/fonts/) into ./assets |
camus -c --full |
Copy the complete bundled resource tree into ./.camus |
camus -c --theme |
Copy the whole theme/ directory into ./theme, plus minimal assets/ |
camus -c --theme <name> |
Copy only theme/<name>/ into ./theme/<name>, plus minimal assets/ |
camus -c -f |
Force re-copy the selected resources |
camus --open |
Open the workdir in VS Code (does not build) |
camus --open runtime |
Open the data directory in the file manager (does not build) |
A site uses one main config file plus optional per-directory metadata:
camus.yaml— site, output, rendering, friends and transfer configurationSUMMARY.md— optional metadata for a directory (title,subtitle,description,cover,logo)
# Public URL of the site. It is split into protocol/domain_name/path_prefix:
# https://the-writer.github.io/camus/ -> https:// + the-writer.github.io + /camus
public_url: https://the-writer.github.io/camus/
theme: terminal
pdf:
engine: chrome # use "disable" to skip PDF generation
sort: file_first # file_first / dir_first / mixed
build:
- --headless
- --print-to-pdf={{dest_dir}}/index.pdf
page:
size: A4
margin: 20mm 18mm
html:
build: # cmark-gfm options
- DEFAULT
- SMART
- FOOTNOTES
copy_pdf: false # copy the generated PDF into the HTML output root
download_logo: false # make HTML use a downloaded local copy of a URL logo (falls back to cover; PDF always downloads cover)
friends:
- title: Alex
link_url: https://github.com/o8x/camus
image_url: https://the-writer.github.io/camus/logo.png
desc: What's past is prologue.
# Move directory contents to another output path, and define text replacements
build:
sitemap: true # generate sitemap.xml
filename_case: keep # keep | uuid | sha1 | seq (non-keep flattens output)
rss: true # generate feed.xml
transfer:
- path: /introduction
transfers:
- source: .
target: /intro/Well-known
env:
assets_cdn: '' # ${env.ASSETS_CDN}; empty by defaultAll scalar config values can be overridden by a CAMUS_<PATH> environment variable (e.g. pdf.page.size → CAMUS_PDF_PAGE_SIZE, html.copy_pdf → CAMUS_HTML_COPY_PDF, html.download_logo → CAMUS_HTML_DOWNLOAD_LOGO, theme → CAMUS_THEME). Arrays/lists such as html.build, pdf.build, friends and build cannot be injected.
public_url accepts with or without a protocol. Missing protocols default to https://; a trailing slash is normalized away. It drives absolute links, the sitemap, and PDF cover data.
Every directory in the source tree may contain a SUMMARY.md that describes it. SUMMARY.md files are metadata only and are never rendered as articles.
---
title: Well-known musicals
subtitle: Optional short summary
cover: assets/cover.jpg
logo: assets/logo.png
---
Optional description shown on the directory page.Parsing rules:
title,subtitle,description,coverandlogomay be provided in an optional YAML front matter block. The legacy keycover_imageis still accepted as an alias forcover.coverin the rootSUMMARY.mdsets the PDF cover. Relative paths are resolved from the directory containingcamus.yaml, then fall back to the source directory and the siteassetsdirectory; absolute paths are used as-is.logosets the image used by HTML themes; when it is unset, HTML falls back tocover(and thus legacycover_image).- If
titleis missing, the first# Headingin the body is used. - If
descriptionis missing, the remaining body is used. - Unset fields inherit from the root route; the root
SUMMARY.md(posts/SUMMARY.mdorsrc/SUMMARY.md) defines the site title/subtitle/description. - Newlines in metadata become
<br />.
build in camus.yaml maps directory content to a different output location (the legacy key transfer is still accepted). Each item has a path plus a list of transfers:
| Field | Required | Description |
|---|---|---|
path |
yes | Directory path relative to the source directory. |
transfers[].source |
yes | Source path. . or / means the directory itself; anything else is joined under path. |
transfers[].target |
yes | Output directory used as the external path for that directory. |
Examples:
build:
# posts/introduction/** -> /intro/Well-known/**
- path: /introduction
transfers:
- source: .
target: /intro/Well-known
# posts/Don Juan/** -> /M/**
- path: /Don Juan
transfers:
- source: .
target: /M
# Move only a subdirectory:
# posts/guide/advanced/** -> /docs/advanced/**
- path: /guide
transfers:
- source: advanced
target: /docs/advancedNotes:
- Transfers are whole-directory mappings. All files (including nested subdirectories) under the source directory are written below
target. - Without a transfer rule, the directory keeps its original path.
- The root path
/cannot use transfers. - A path that contains a
privatesegment is ignored (with a warning);privatedirectories are excluded from the source tree.
Markdown files live under src/ or posts/. Optional front matter sits between --- markers (the file must start with --- to enable it):
---
title: My article
create-time: 2026-01-01
tags: [ "notes", "cpp" ]
visibility: open
---Supported fields include title, short-path, create-time, visibility (open / hidden / hidden_in_toc) and tags. hidden articles are not rendered; hidden_in_toc articles are rendered but omitted from TOC/navigation lists.
Themes contain home.html, page.html, stats.html and friends.html, loaded from theme/{name}/, then .camus/theme/{name}/, then the platform data directory. All built-in themes reference the shared assets/css/style.css and assets/js/camus.js entries (empty by default, override locally in ./assets). Templates use inja and expose the parsed configuration plus helpers:
| Helper | Description |
|---|---|
{{ with_prefix("/css/site.css") }} |
Prefix a path with path_prefix |
dist/
├── html/ # static HTML site (index pages, articles, stats, friends, sitemap)
└── pdf/ # when pdf.engine is configured and not "disable"