# Scriptorium Scriptorium renders scientific documents server-side in Go: Markdown into HTML, TeX mathematics into MathML Core, and Mermaid flowchart and sequence diagrams into SVG. Three engines, each written from scratch in this repository on the Go standard library alone, producing markup the reader's browser already knows how to draw: no JavaScript runs on the page that reads the result. ## The strengths, each with its proof **Complete Markdown.** The engine renders the full CommonMark 0.31.2 grammar plus the GitHub Flavored Markdown extensions. Measured against the official suites: 649 of 652 CommonMark examples pass, and the three exceptions are bare URLs and email addresses that the GFM extended autolinks turn into links, the same trade GitHub's own reference implementation makes; all 23 extension examples of the GFM specification pass byte for byte. Footnotes and definition lists come on top, rendered in the shapes GitHub and Pandoc established. **Complete mathematics.** Every one of the 391 mathematical symbols in the KaTeX coverage table maps to MathML Core, verified by a systematic diff against KaTeX's own source tables, together with fractions, radicals, scripts with movable limits, stretchy delimiters, the amsmath environments, accents, styles, colours, extensible arrows and bounded macros. Where a KaTeX-compatible renderer needs JavaScript in the reader's browser, scriptorium emits MathML Core that Chromium, Firefox and Safari draw natively. **Deterministic.** The same input produces byte-identical output on every call, in every process, on every machine. Diagram layouts break ties by the order of appearance and never by map iteration; tests assert byte equality across repeated renders in all three engines. Output is safe to cache, to diff and to sign. **Zero dependencies.** The Go standard library alone, direct and transitive. There is no `go.sum`, because there is nothing to sum: no parser to supply-chain, no renderer to version-pin, no JavaScript bundle to ship. Compiles wherever Go compiles. **Honest about its edges.** A construct outside a mappable surface is never dropped and never guessed at: mathematics degrades in place, the unknown command standing as its verbatim source inside a marked element while the rest of the expression still renders, and a diagram type outside the two grammars is refused with an error naming the type and the source line. **Ready for servers.** The engines hold no state between calls, so every function is safe for concurrent use. Rendering never fails on malformed input: Markdown and mathematics always produce output, and a diagram error tells the author the line to fix. **No sanitisation, by contract.** The library renders trusted input and writes the output verbatim; whether the result may reach a given audience is the consumer's policy. A consumer of untrusted input keeps its own sanitiser and applies it to the rendered result. ## A taste ```go package main import ( "os" "sourcedock.dev/petrbalvin/scriptorium" ) func main() { os.Stdout.Write(scriptorium.Render([]byte( "# Measured, not guessed\n\nA *claim* with [a source](/uri) and some `code`.\n"))) os.Stdout.Write(scriptorium.RenderMathDisplay([]byte(`\sum_{i=1}^{n} \frac{1}{i^2}`))) svg, err := scriptorium.RenderDiagram([]byte("flowchart LR\n A[Input] --> B{Model} --> C[Result]\n")) if err != nil { panic(err) } os.Stdout.Write(svg) } ``` The first call prints exactly: ```html

Measured, not guessed

A claim with a source and some code.

``` The second prints a complete MathML Core element, the summation limits above and below the operator the way display mathematics sets them: ```html ∑i=1n1i2 ``` The third returns a self-contained SVG document of the flowchart, every element positioned by the library's own layout in whole pixels: ranks by longest path, ordering by barycentre sweeps. ## The engines ### Markdown CommonMark 0.31.2 in full, with the GFM extensions: tables with per column alignment, strikethrough, task lists and extended autolinks (`www.`, `http(s)://`, `ftp://` and bare email addresses, with the punctuation, parenthesis and entity trimming rules of the specification), plus footnotes and definition lists. Tables render in the exact shape of GitHub's reference implementation. ### Mathematics The standard TeX command surface that maps to MathML Core, measured against the KaTeX coverage list: the Greek letters including the variants, the relation and operator tables including negations and the colon relations, the arrows including the extensible `\x` family, the big operators, the delimiters, and the letter-like symbols; the amsmath environments (`matrix` and every delimited variant, `cases`, `aligned`, `align`, `gather`, `equation`, `array`, `substack`); accents and over and under lines; the font commands; spacing; colours; and bounded `\newcommand`, `\def` and `\DeclareMathOperator` macros with expansion limits that turn a runaway definition into an honest error rather than a hang. ### Diagrams The two Mermaid grammars the forge's documents actually use, a coverage measured across every repository on the forge. Flowchart (including the historical `graph` alias): every node shape, every edge kind with labels, branching, subgraphs with their own direction, classes and styles. SequenceDiagram: participants and actors, all arrow kinds, notes, activations, the `alt`/`opt`/`loop`/`par`/`critical`/`break` blocks, coloured regions, `autonumber` and dividers. Everything else is refused with a clear error naming the type. ## The API | Function | Renders | Fails | |---|---|---| | `Render(source []byte) []byte` | Markdown to HTML | never | | `RenderMath(source []byte) []byte` | TeX to inline MathML Core | never | | `RenderMathDisplay(source []byte) []byte` | TeX to display MathML Core | never | | `RenderDiagram(source []byte) ([]byte, error)` | Mermaid to SVG | on an unsupported type or a malformed statement | | `SupportedDiagram(kind string) bool` | reports the Mermaid scope | | ## Install ```sh go get sourcedock.dev/petrbalvin/scriptorium ``` Requires Go 1.27.1 or newer. ## Documentation - [docs/API.md](docs/API.md): the surface in full, with the exact boundary of the mathematics surface and every command that degrades - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the engines are built - [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md): the workflow and the recipes - [CHANGELOG.md](CHANGELOG.md): the user-visible history - [CONTRIBUTING.md](CONTRIBUTING.md): how to contribute - [SECURITY.md](SECURITY.md): how to report a vulnerability ## Development ```sh just build # compile every package just test # the test suite with the coverage floor, under a memory fence just fmt # format just gates # the definition of done: build, format, vet, tests, race ``` ## Licence MIT. See [LICENSE](LICENSE). Copyright © 2026 [Petr Balvín](https://petrbalvin.org)