Initial commit

Assisted-by: GLM 5.3

README.md

@@ -0,0 +1,125 @@
+# 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)