# 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](https://caddyserver.com) 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](https://sourcedock.dev/petrbalvin/volumen/releases), together
with `checksums.txt`. The commented configuration template,
`config.toml.example`, lives at the repository root.

From source:

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

## Quick start

```sh
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:

```sh
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

```sh
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

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

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

## Documentation

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

## Licence

PolyForm Noncommercial 1.0.0. See [LICENSE](LICENSE).

Copyright © 2026 [Petr Balvín](https://petrbalvin.org)