petrbalvin
f8ed33df83
Test / test (push) Successful in 7m5s
Release / gates (push) Successful in 7m28s
Release / build (amd64, freebsd) (push) Successful in 2m52s
Release / build (amd64, linux) (push) Successful in 2m46s
Release / build (arm64, freebsd) (push) Successful in 2m22s
Release / build (arm64, linux) (push) Successful in 2m38s
Release / build (loong64, linux) (push) Successful in 2m7s
Release / build (riscv64, linux) (push) Successful in 2m17s
Release / release (push) Successful in 1m0s
Assisted-by: GLM 5.3
126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# 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)
|