Skip to content
Alex Flom edited this page May 4, 2026 · 6 revisions

UOR-Framework wiki — authoring workflow

This repository is the source for https://github.com/UOR-Foundation/UOR-Framework/wiki. The committed .md files at the wiki root are GitHub-rendered output, not hand-edited content. The authoring sources are AsciiDoc (under src/arc42/) and Structurizr DSL (under src/c4/).

The full structural specification is wiki-definition.md in the parent UOR-Framework repository. This README covers the day-to-day workflow.

One-time setup

git clone --recurse-submodules https://github.com/UOR-Foundation/UOR-Framework.wiki.git
cd UOR-Framework.wiki
./scripts/install-tools.sh

install-tools.sh downloads tools/structurizr.war and tools/pandoc.deb (both verified against tools/checksums.txt), extracts pandoc to tools/pandoc-prefix/ and symlinks it at tools/bin/pandoc, builds tools/bin/cmark-gfm from source at the pinned tag, checks out arc42-template at the SHA in tools/arc42-template-pin.txt, runs bundle install into vendor/bundle/, installs Playwright system libraries via apt-get so V3's SVG export can launch headless Chromium, verifies host tool versions match tools/versions.txt, and re-writes tools/versions.txt from observed values. The script needs sudo for the apt step only.

Editing

Edit AsciiDoc chapters under src/arc42/adoc/ or the C4 workspace at src/c4/workspace.dsl. Wiki-frame content lives at src/wiki/{Home,Sidebar,Footer}.adoc.

Validate (fast feedback, no committable output)

./scripts/validate.sh

Runs V1–V5 in dependency order and prints an aggregated report. See wiki-definition.md for what each validator enforces and why.

Build (validate + render + stage to wiki root)

./scripts/build.sh

Runs Stage 1 (pre-flight pin verification), Stage 2 (validate), Stage 3 (render wiki-frame), Stage 4 (stage to wiki root with chapter rename + image-path rewrite), and Stage 5 (idempotence check — re-runs Stage 4 to a scratch dir and cmps every output, failing on any byte-level divergence).

Commit and push

git status                                 # confirm src/ AND rendered .md files changed
git add src/ images/ Home.md _Sidebar.md _Footer.md \
        [0-9][0-9]-*.md
git commit -m "..."
git push

The commit MUST include the source change AND the corresponding rendered output AND any SVG that V3 produced.

Detect drift between source and committed output

./scripts/check-wiki-state.sh

Clones the live wiki repo, re-runs Stage 4 against the committed sources, and cmps each staged file against the wiki root. Detects commits where source and rendered output drifted (e.g., a contributor edited src/... but forgot to re-run build.sh before pushing). Repair: clone, run ./scripts/build.sh, commit the regenerated output, push.

Pin updates

Each external tool is pinned. There are five pin authorities:

Pin Authority
arc42-generator submodule SHA recorded by git add vendor/arc42-generator
arc42-template tools/arc42-template-pin.txt (overrides the generator's transitive pin, which is too old for the current Templates.groovy layout)
structurizr.war version literal + SHA-256 in scripts/install-tools.sh and tools/checksums.txt
pandoc.deb version literal + SHA-256 in scripts/install-tools.sh and tools/checksums.txt
cmark-gfm git tag literal in scripts/install-tools.sh
Ruby gems Gemfile.lock

General update procedure (any pin):

  1. Edit the pin literal in scripts/install-tools.sh (and tools/checksums.txt for structurizr.war / pandoc.deb, or tools/arc42-template-pin.txt for the template).
  2. Run ./scripts/install-tools.sh to download/build at the new pin and rewrite tools/versions.txt.
  3. Run ./scripts/build.sh to confirm the new pin produces equivalent output.
  4. Commit the pin literal change, the new tools/versions.txt, and any rendered output churn in a single commit.

For the arc42-generator submodule specifically, also cd vendor/arc42-generator && git checkout <new-sha> then cd .. && git add vendor/arc42-generator before running install-tools.sh. Reconsider tools/arc42-template-pin.txt at the same time — a newer generator may expect a different template layout.

What lives where

Path Role
src/arc42/adoc/NN_*.adoc Per-chapter AsciiDoc sources
src/arc42/arc42-template.adoc Top-level include (for direct asciidoctor use)
src/arc42/version.properties Spec revision metadata
src/arc42/images/*.svg Output of V3 (Structurizr → SVG)
src/c4/workspace.dsl Single canonical Structurizr workspace
src/wiki/{Home,Sidebar,Footer}.adoc Wiki-frame fragments
vendor/arc42-generator/ Pinned submodule. V1 reads upstream chapter manifest from vendor/arc42-generator/arc42-template/EN/adoc/. arc42-template's SHA is overridden by tools/arc42-template-pin.txt, not by the generator's recorded pin.
tools/arc42-template-pin.txt SHA we want arc42-template checked out at; enforced by install-tools.sh after submodule init
tools/checksums.txt SHA-256 pins for downloaded binaries (structurizr.war, pandoc.deb)
tools/versions.txt Resolved version strings; written by install-tools.sh, read by build.sh Stage 1
scripts/ All build, validate, and helper scripts
Gemfile, Gemfile.lock Ruby gem pins (Asciidoctor for V1, github-markup + commonmarker for V5)
*.md at the root GitHub-rendered output (committed)
images/ at the root SVGs referenced by rendered chapters (committed)

What NOT to do

  • Do not edit *.md at the wiki root by hand. They are regenerated by build.sh. Edit src/... instead.
  • Do not edit pages via the GitHub web UI. Web-UI edits are overwritten by the next push from a build.sh run.
  • Do not skip the build. A commit that updates src/... without updating the corresponding rendered file is detected by scripts/check-wiki-state.sh.
  • Do not pin an arc42-template submodule directly in this repo's .gitmodules. The active pin lives in tools/arc42-template-pin.txt and is applied by install-tools.sh after submodule init. The arc42-generator submodule has its own recorded pin for arc42-template, but that pin is too old for the generator's current Templates.groovy layout expectations — we deliberately override it.

Clone this wiki locally