volumen/README.md

Volumen

Volumen is a lightweight publishing platform for scientists. Posts are Markdown files with a TOML frontmatter block, served as a headless JSON API and edited through a server-rendered admin; the public site is a separate front end that consumes the API. A publication is plain files under version control, and the server is one static binary with no database, no build step and no runtime dependencies. In production it runs behind a reverse proxy: Caddy is the recommended front, with automatic HTTPS and a one-line site block.

Features

• Markdown posts with TOML frontmatter: posts are .md files carrying title, slug, date, lang, tags, draft, publish_at, series, translations, doi, orcid, refs and the author's own fields, safe to commit and editable in any editor.
• Scholarly apparatus: $…$ and $$…$$ mathematics render server-side as MathML with no JavaScript, doi and orcid are validated and surfaced as resolvable identifiers, and a frontmatter refs table renders as a numbered bibliography with every inline citation linked and every DOI, arXiv id and ORCID turned into a resolver link; the admin editor edits the reference list in place.
• Diagrams: fenced mermaid blocks render server-side to inline SVG, flowcharts and sequence diagrams in full, with a diagram the engine does not carry staying the code block the author wrote.
• One static binary: the Go standard library and a handful of small modules, with the admin templates and assets embedded and posts read from the directory you point it at.
• Public JSON API: site metadata, filterable post lists, post details with rendered HTML, tags, series, RSS, Atom, JSON Feed and a sitemap under /api/volumen, with ETag conditional requests.
• Token-authenticated writes: scoped bearer tokens for POST, PUT and DELETE, and If-Match against the served ETag so a blind overwrite is refused with 412.
• Admin UI: a first-run wizard that founds the installation, login with roles and an optional second factor (TOTP with a QR code and one-time recovery codes), dashboard, Markdown editor with live preview, media library, post templates, revision history, backups, self-update and per-account language and colour scheme under /admin.
• Multi-language posts: one file per language, in the content root or a per-language subdirectory, linked by a translations map or shared with the all_langs flag.
• Scheduled publishing: publish_at dates honoured by volumen publish-due from cron or a timer, or by the in-process [scheduler].
• Post revisions: every save archives the previous version and a delete is a move into that archive, so both stay undoable.
• Webhooks: signed JSON events on post create, update, delete and publish let a front end rebuild its cache or static pages.
• Diagnostics: doctor and validate commands, a /healthz endpoint, a per-request id on every line, an append-only audit log and structured JSON logging.

Install

Prebuilt binaries for Linux and FreeBSD are on the releases page, together with checksums.txt. The commented configuration template, config.toml.example, lives at the repository root.

From source:

go install sourcedock.dev/petrbalvin/volumen/cmd/volumen@latest

Quick start

volumen serve

With no configuration file the server runs on per-user paths (~/.local/share/volumen). Open http://localhost:9091/admin/: the first-run wizard creates the administrator account, picks the interface language and the colour scheme, and signs you in. Then, in a second shell, create the first post and read it back:

printf '+++\ntitle = "Hello"\ndate = 2026-09-25\n+++\n\nFirst body.\n' \
  > ~/.local/share/volumen/posts/hello.md
curl -s http://localhost:9091/api/volumen/posts/hello

Usage

volumen serve --config /etc/volumen/config.toml --content /var/lib/volumen/posts
volumen status
volumen doctor
volumen validate
volumen publish-due --dry-run
volumen export --out backup.tar.gz
volumen import backup.tar.gz
volumen check-update
volumen version

Development

just build   # build
just test    # the test suite
just fmt     # format

See docs/DEVELOPMENT.md for the full workflow, and CONTRIBUTING.md for how to contribute.

Documentation

• docs/ARCHITECTURE.md: components and data flow
• docs/API.md: the API reference
• docs/CLI.md: every subcommand and flag
• docs/CONFIGURATION.md: every configuration key
• docs/DEPLOYMENT.md: how it runs in production
• docs/DEVELOPMENT.md: setup, recipes, tests, releases
• docs/BENCHMARKING.md: how performance is measured
• man/volumen.1: the manual page

Licence

PolyForm Noncommercial 1.0.0. See LICENSE.

Copyright © 2026 Petr Balvín