Repository navigation
README
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.
git clone --recurse-submodules https://github.com/UOR-Foundation/UOR-Framework.wiki.git
cd UOR-Framework.wiki
./scripts/install-tools.shinstall-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.
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.
./scripts/validate.shRuns V1–V5 in dependency order and prints an aggregated report. See wiki-definition.md for what each validator enforces and why.
./scripts/build.shRuns 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).
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 pushThe commit MUST include the source change AND the corresponding rendered output AND any SVG that V3 produced.
./scripts/check-wiki-state.shClones 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.
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):
- Edit the pin literal in
scripts/install-tools.sh(andtools/checksums.txtforstructurizr.war/pandoc.deb, ortools/arc42-template-pin.txtfor the template). - Run
./scripts/install-tools.shto download/build at the new pin and rewritetools/versions.txt. - Run
./scripts/build.shto confirm the new pin produces equivalent output. - 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.
| 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) |
-
Do not edit
*.mdat the wiki root by hand. They are regenerated bybuild.sh. Editsrc/...instead. -
Do not edit pages via the GitHub web UI. Web-UI edits are overwritten by the next push from a
build.shrun. -
Do not skip the build. A commit that updates
src/...without updating the corresponding rendered file is detected byscripts/check-wiki-state.sh. -
Do not pin an
arc42-templatesubmodule directly in this repo's.gitmodules. The active pin lives intools/arc42-template-pin.txtand is applied byinstall-tools.shafter submodule init. Thearc42-generatorsubmodule has its own recorded pin forarc42-template, but that pin is too old for the generator's currentTemplates.groovylayout expectations — we deliberately override it.
Generated from sources at UOR-Framework.wiki. Do not edit pages directly via the GitHub web UI — edits are overwritten by the next build. See README for the authoring workflow.