From 7b7bebe328686c73979ea984580f8622e5be0321 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ralf=20D=2E=20M=C3=BCller?= Date: Mon, 14 Sep 2026 21:38:41 +0000 Subject: [PATCH] feat(docs): project landing page for the microsite The site opened with the docToolchain placeholder page, which said nothing about this project. Replace it with an overview: what the generator does, the four build phases, one card per document, and how to build the templates and the site. It reuses the theme's own CSS classes, so it does not drift from the rest of the site. The page lives in site/doc/landingpage.gsp. microsite.siteFolder resolves relative to docs/, so '../site' keeps the template outside the published output - inside docs/ the .gsp would be copied along as a stray asset. Harden the workflow check while here. generateSite reports success even when the landing page template fails to parse; it then writes an index.html without any landing content. That happened during development: a '$/' in the text was read as the start of a GSP expression, the include failed, and the build still went green. The check now looks for landing content, not just for a non-empty file. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_014S4btgSH36ViayKLqGLd6G --- .github/workflows/documentation.yml | 14 ++- docToolchainConfig.groovy | 6 +- site/doc/landingpage.gsp | 138 ++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+), 3 deletions(-) create mode 100644 site/doc/landingpage.gsp diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 5fd3b8b..5b033fd 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -58,8 +58,18 @@ jobs: - name: Generate site run: ./dtcw4 local generateSite - - name: Fail if the landing page is missing - run: test -s build/docs/microsite/output/index.html + # generateSite reports success even when the landing page template fails + # to parse - it then writes an index.html without any landing content. + # Check for the content, not just for the file. + - name: Fail if the landing page is missing or empty + run: | + index=build/docs/microsite/output/index.html + test -s "$index" + grep -q 'dtc-landing' "$index" || { + echo "::error::index.html carries no landing page content -" \ + "the template in docs/site/doc/ probably failed to parse." + exit 1 + } - name: Upload site as build artifact uses: actions/upload-artifact@v4 diff --git a/docToolchainConfig.groovy b/docToolchainConfig.groovy index a93c2ab..df6b74d 100644 --- a/docToolchainConfig.groovy +++ b/docToolchainConfig.groovy @@ -23,7 +23,11 @@ microsite = [:] // title in the upper left corner and fallback page title microsite.title = 'arc42-generator' -// the landing page ships with the internal theme +// project landing page: site/ overlays the internal theme, so +// site/doc/landingpage.gsp replaces the theme's placeholder page. The path is +// relative to docs/, and pointing outside it keeps the template out of the +// published site - inside docs/ it would be copied along as a stray asset. +microsite.siteFolder = '../site' microsite.landingPage = 'landingpage.gsp' // footer and edit links diff --git a/site/doc/landingpage.gsp b/site/doc/landingpage.gsp new file mode 100644 index 0000000..452792a --- /dev/null +++ b/site/doc/landingpage.gsp @@ -0,0 +1,138 @@ +
+ + +
+ + + โ€” ARC42-GENERATOR โ€” + + ยง ARCHITECTURE / SPECIFICATION / BACKLOG +

One source,
every shape.

+

+ The arc42 template is maintained once, as AsciiDoc, in the + arc42-template repository โ€” the + Golden Master. Readers want it as Word, Markdown, HTML, LaTeX and a + dozen other formats, in their own language, with or without the embedded help texts. + This generator produces every one of those combinations and packs each into a ZIP + archive ready for download. +

+
+ ๐Ÿ“˜ Architecture + Just want a template? โ†’ +
+
+ +
โ›“โ›“โ›“
+ + +
+

Four phases, one command

+

Every language of the Golden Master, in two flavors, converted into seventeen formats.

+
+
+
โœ‚๏ธ
Generatestrip feature flags
+
๐Ÿ”
Discoverscan and validate
+
๐Ÿ”„
Convertasciidoctor + pandoc
+
๐Ÿ“ฆ
Packageone zip per variant
+
+ +
โ›“โ›“โ›“
+ + +
+

What you'll find here

+

+ This documentation was recovered from the source code, not written alongside it. + Every claim carries its evidence as file:line; facts only the team could + supply are marked (team answer). +

+
+
+
+
๐Ÿงฉ
+

Architecture

+

+ All twelve arc42 chapters. Context and building blocks as C4 diagrams, five + cross-cutting concepts, seven ADRs with Pugh matrices, and chapter 11 separating + risks from technical debt. +

+
+
+
๐ŸŽฏ
+

Product Requirements

+

+ The problem, four personas, the goals and where the product falls short of them + today. Success is measured in release effort, not in downloads. +

+
+
+
๐Ÿ“‹
+

Specification

+

+ Four persona use cases in Cockburn form, six system use cases for the technical + interfaces, ten business rules, Gherkin criteria and twelve EARS requirements. +

+
+
+
๐Ÿ—‚๏ธ
+

Backlog

+

+ Four EPICs, sixteen user stories, prioritized with MoSCoW. The first EPIC exists + because the build reports success even when conversions failed. +

+
+
+
๐ŸŒณ
+

Question Tree

+

+ How the documentation was recovered: five root questions refined until every leaf + could be answered from one specific place in the code โ€” or marked open. +

+
+
+
โ“
+

Open Questions

+

+ The nine questions the code could not answer, one section per role โ€” all of them + answered by the team, and those answers feed the documents above. +

+
+
+ +
โ›“โ›“โ›“
+ + +
+

Build it yourself

+

Docker is the supported way to run the generator; the documentation builds with docToolchain.

+
+
+
+
๐Ÿณ
+

The templates

+

+ docker compose up refreshes the Golden Master, generates both + flavors, converts every format and writes the archives to + arc42-template/dist/. +

+
+
+
๐Ÿ“–
+

This site

+

+ ./dtcw4 local generateSite renders docs/ into a + microsite. A GitHub Action does the same on every push and publishes the result + here. +

+
+
+
๐Ÿ”ง
+

Contribute

+

+ A new translation needs no change in this repository โ€” a directory matching + /^[A-Z]{2,}$/ in the Golden Master is picked up by itself. +

+
+
+ +