8000 GitHub - the-writer/camus: Camus is a static site generator written in C++23. It converts Markdown posts into static HTML pages with theme support, file watching, catalog generation, and sitemap generation — all bundled into a single self-contained binary. · GitHub
[go: up one dir, main page]

Skip to content
the-writerPublic

About

Camus is a static site generator written in C++23. It converts Markdown posts into static HTML pages with theme support, file watching, catalog generation, and sitemap generation — all bundled into a single self-contained binary.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

Camus

Camus

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.

中文

Install

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

Requirements

  • CMake 3.28+
  • Ninja (recommended) or Make
  • A C++23 toolchain
  • Optional: Chrome/Chromium/Edge for PDF output

Build

git submodule update --init --recursive
make build          # output: build/release/bin/camus

Quick start

The repository ships a complete example in example/:

cd example
../build/release/bin/camus --build

Or 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 # build

camus 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.

Common commands

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)

Configuration

A site uses one main config file plus optional per-directory metadata:

  • camus.yaml — site, output, rendering, friends and transfer configuration
  • SUMMARY.md — optional metadata for a directory (title, subtitle, description, cover, logo)

camus.yaml

# 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 default

All 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.

Directory metadata (SUMMARY.md)

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, cover and logo may be provided in an optional YAML front matter block. The legacy key cover_image is still accepted as an alias for cover.
  • cover in the root SUMMARY.md sets the PDF cover. Relative paths are resolved from the directory containing camus.yaml, then fall back to the source directory and the site assets directory; absolute paths are used as-is.
  • logo sets the image used by HTML themes; when it is unset, HTML falls back to cover (and thus legacy cover_image).
  • If title is missing, the first # Heading in the body is used.
  • If description is missing, the remaining body is used.
  • Unset fields inherit from the root route; the root SUMMARY.md (posts/SUMMARY.md or src/SUMMARY.md) defines the site title/subtitle/description.
  • Newlines in metadata become <br />.

Build rules

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/advanced

Notes:

  • 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 private segment is ignored (with a warning); private directories are excluded from the source tree.

Posts

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 and template helpers

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

Output

dist/
├── html/            # static HTML site (index pages, articles, stats, friends, sitemap)
└── pdf/             # when pdf.engine is configured and not "disable"

About

Camus is a static site generator written in C++23. It converts Markdown posts into static HTML pages with theme support, file watching, catalog generation, and sitemap generation — all bundled into a single self-contained binary.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

0