In progress01 · Tool wall7 min read

Building OpenFolia

I built the documentation system I wanted to buy. OpenFolia stores operating manuals as small modules in plain files that the manufacturer owns, then builds a correct manual for every product variant and every language. It is free and open source.

Built inCommitsTest filesLicence
5 days (17 to 21 Nov 2026)2,230701AGPL-3.0

The problem

A machine maker rarely sells one machine. It sells a large and a small model, for several markets, with options and software versions that change every year. Each combination needs an operating manual, usually in a dozen languages.

Most teams handle this by copying. A correction lands in one copy and not in the other ten. Every small edit sends the whole manual back to the translator. In safety documentation, a warning that is wrong for one variant is a liability, not a typo.

Software that solves this exists: a component content management system, or CCMS. In my experience it was expensive, closed, slow to work with, and hard to leave once your content was inside it. After one bad round with a vendor I decided to build the tool I had wanted to buy.

OpenFolia is for technical writers and documentation managers at manufacturers: machinery, devices, anything that ships with a manual and a safety leaflet.

The idea: write once, assemble everything

Content is written as small modules: one procedure, one safety notice, one chapter on charging. A manual is an outline that references modules. A build is one manual for one variant in one language. A release is an immutable snapshot of all of it.

The decision everything else follows from: the modules live as AsciiDoc files in a Git repository the customer owns. The database holds only what is about people and process: users, roles, locks, comments, workflow, the audit log, and a search index that can be rebuilt from the files at any time. If you leave, you take plain text with you. There is nothing to export.

Architecture diagram titled 'Every output reads from the content repository through one API'. On the left, the content repository (AsciiDoc modules, manuals, terms and ccms.yaml in Git, highlighted) and Postgres (people, workflow, locks and a rebuildable index) both feed the JSON:API in the middle (any branch, tag or commit; OpenAPI generated from code). The API serves four outputs on the right: the web editor (one client of the API), PDF/UA-1 and HTML (Typst, every variant), portals and systems (iiRDS export, webhooks) and the MCP server (AI assistants, read-only).
architecture · one source, one API, four outputs

The files are the source of truth; Postgres only holds what is about people and process.

OpenFolia is headless from the first commit. The editor has no private back door: everything it does goes through the documented JSON:API. The OpenAPI description is generated from the code, and the end-to-end tests check every response against it, so the API documentation cannot drift from the API.

Stack: TypeScript throughout. A NestJS API in a hexagonal layout, an Angular editor on ProseMirror, Typst for PDF, Postgres, S3-compatible storage. An Nx monorepo with Vitest and Playwright.

Three problems worth solving properly

Variants without copies

What differs between variants is marked with a condition in a small, typed expression language. Version attributes compare as numbers, so software >= 2.10 is true for 2.10 and false for 2.9, which plain text comparison gets wrong.

[variant#lift-limit,when="model in (large) && software >= 2.3"]
====
The lift stops at {max-height}. Do not override the limit.
====

Writers never type that. In the editor a picker builds the rule, reads it back as a sentence, and shows live how many shipped builds it hits ("Appears in 6 builds"). The preview names what the current variant hides. Before a release, every shipped variant is resolved in every language, and an unknown attribute or a missing value blocks the release.

One deliberate limit: conditions work on whole blocks, not inside a sentence. Words that change per model, like a maximum height, are text attributes. That keeps every sentence whole, which matters for translation.

Translate only what changed

Each translated block remembers a SHA-256 hash of the source text it was translated from. The hash ignores reformatting, so moving a line break does nothing, while changing a word marks exactly that block as outdated. The state of every block in every language is derived from the files on each request, never kept by hand.

The export to a translation agency is a delta in XLIFF 2.0, the OASIS standard: only outdated or missing units, with word counts before you send it. A unit can be in one open job only, so nothing is paid for twice. On the way back every unit is checked, and the import becomes a draft that goes through the normal review. A translator cannot change a link target, and the XML parser refuses DTDs and entities, so a hostile file cannot read the server.

Print-quality output in about a second

Manuals render to tagged, accessible PDF/UA-1 through Typst, with no desktop publishing step and no separate rendering server licence. Safety notices follow ISO 3864 and ANSI Z535: signal word, colour and symbol.

Templates are plain text in the same repository as the content, so a layout change is reviewed and versioned like any other change. Rendering is fast enough to preview while writing, which changes how people write.

Speed is a test, not a hope

Speed targets run in the build on every change: a module preview under 1 second, a search under 300 milliseconds, a manual's PDF under 3 seconds cold and under 1 second for another variant. A change that breaks them fails.

The first measurement at scale used a generated repository of 5,542 modules, 300 manuals and 8 languages:

WhatColdWarm or next variant
PDF of a 400-module manual1.2 s514 ms
PDF of a typical manual765 ms202 ms
Module preview128 ms48 ms
Full-text search4.8 s (first query after a restart)118 ms
XLIFF export dry run145 ms
Server start-up1.24 s (median)

Measured on a 16-core laptop, in quiet runs.

AI access, carefully

An MCP server gives AI assistants access to the documentation, so a service technician can ask a chat assistant how to change a filter on one model and get the released answer. It is read-only and serves released content only. Drafts never leak into an answer, and an assistant can never change a manual. For teams building their own retrieval, the API serves ready-made chunks.

There is also an optional style review that checks a module against the house style with any chat model, including a self-hosted one. It is off by default and sends only the module's text.

How one person built it in five days

The first commit is from 17 November 2026. By the 21st the repository had 2,230 commits and over 900 merged branches. I did not type all of that. I worked as the architect and reviewer for a team of AI coding agents running in parallel.

  • Specs as issues. Requirements became a backlog of GitHub issues. The issue and its comments are the spec, and decisions recorded there are binding.
  • One slot per agent. A small tool gives each agent its own worktree, branch, port and database, so several work at once without getting in each other's way.
  • Rules that hold. The written rules are enforced where possible: a lint rule keeps the domain core free of HTTP and database code, the API contract is checked in every end-to-end test, and the speed budgets run in the build.
  • Review that learns. Every agent reports its review findings in a fixed format. A kind of mistake that keeps coming back becomes a rule, a check or a line in the prompt.

My job moved from writing code to deciding what to build, writing precise specs, and saying no. The hard part was not speed. It was keeping 2,000 commits coherent.

Open source, and what that means here

The core is AGPL-3.0 and complete. Every documentation feature is in it: variants, translations, reviews and releases, PDF and HTML, the API and the MCP server. Paid plans, when they come, may only add hosting, support and IT controls such as single sign-on.

It runs on your own infrastructure: four containers and Postgres from one Compose file. Each image runs as an unprivileged user on a read-only file system, with encrypted and verified backups.

ShippedNext
Variants, picker and preview per variantOpenID Connect sign-in in the core
XLIFF 2.0 delta export and checked importA hosted offering
Review, approval and Git-tagged releasesSSO, SCIM and audit log export for larger teams
PDF/UA-1 and HTML outputImage callouts per variant
JSON:API, webhooks and the MCP serverCOTI for translation systems
Container images and a self-hosting guide

What I took away

Owning the format is the feature. Most of what makes OpenFolia pleasant follows from keeping content as plain text in Git: history for free, review for free, no lock-in, and outputs that are just functions of a commit.

Constraints make a product. Saying no to inline conditions, to a private editor API and to vendor-specific importers in the core kept the system small enough to stay fast and correct.

Building with agents is a management problem more than a coding one. The quality came from specs, rules and checks, not from any single clever prompt.

Links: openfolia.com · docs.openfolia.com · Source on GitHub

All notes