feat: render Markdown, mathematics and Mermaid diagrams server-side

scriptorium.go

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+// Package scriptorium renders scientific documents server-side. It renders
+// Markdown to HTML, TeX mathematics to MathML Core, and Mermaid flowchart
+// and sequence diagrams to SVG. The output is deterministic, so the same
+// input always produces byte-identical output.
+//
+// The library is built on the Go standard library alone: it carries no
+// dependency of its own. It renders trusted input and applies no
+// sanitisation; whether the produced HTML may reach a given audience is
+// the consumer's policy, not the renderer's.
+//
+// A construct the renderer refuses to guess at is never dropped or
+// mistranslated: it stays visible as its verbatim source in a marked
+// element, so the author sees exactly what was not understood.
+package scriptorium
+
+import (
+	"sourcedock.dev/petrbalvin/scriptorium/internal/diagram"
+	"sourcedock.dev/petrbalvin/scriptorium/internal/markdown"
+	"sourcedock.dev/petrbalvin/scriptorium/internal/mathml"
+)
+
+// Render renders the Markdown source to HTML. The grammar is the full
+// CommonMark specification with the GitHub Flavored Markdown extensions,
+// footnotes and definition lists. Rendering never fails and never
+// sanitises: the input is trusted, and whether the output may reach an
+// audience is the consumer's policy.
+func Render(source []byte) []byte {
+	return markdown.RenderHTML(source)
+}
+
+// RenderMath renders the TeX mathematics source to a MathML Core math
+// element, in the inline form. A construct outside the mappable surface
+// stays in the output as its verbatim source inside an merror element.
+func RenderMath(source []byte) []byte {
+	return mathml.Render(source, false)
+}
+
+// RenderMathDisplay renders the TeX mathematics source to a MathML Core
+// math element in the display form, with display="block".
+func RenderMathDisplay(source []byte) []byte {
+	return mathml.Render(source, true)
+}
+
+// RenderDiagram renders the Mermaid diagram source to SVG. The diagram
+// type must be one SupportedDiagram reports; every other type is refused
+// with an error naming it.
+func RenderDiagram(source []byte) ([]byte, error) {
+	return diagram.Render(source)
+}
+
+// The Mermaid scope: every diagram type the library accepts. The choice
+// is measured, not aesthetic: across the documentation of this forge the
+// diagrams are 44 flowcharts (including the historical "graph" spelling)
+// and 22 sequence diagrams, with a single outlying state diagram. Every
+// other type is refused with a clear error rather than a guess.
+var supportedDiagrams = map[string]bool{
+	"flowchart":       true,
+	"graph":           true, // the historical alias of flowchart
+	"sequenceDiagram": true,
+}
+
+// SupportedDiagram reports whether the library renders the named
+// Mermaid diagram type.
+func SupportedDiagram(kind string) bool {
+	return supportedDiagrams[kind]
+}