Add shared site navigation and contextual next steps

.github/scripts/test_methodology.cjs

@@ -18,11 +18,16 @@ function initialElements() {
   return elements;
 }
 
-async function load(fetch) {
+async function load(fetch, signal = new AbortController().signal) {
   const elements = initialElements();
   const context = vm.createContext({
     document: { getElementById: id => elements[id] },
-    fetch: url => { assert.equal(url, api); return fetch(); },
+    AbortSignal: { timeout: ms => { assert.equal(ms, 8000); return signal; } },
+    fetch: (url, options) => {
+      assert.equal(url, api);
+      assert.equal(options.signal, signal);
+      return fetch(url, options);
+    },
     console: { error() {} },
   });
   await vm.runInContext(script, context, { timeout: 1000 });
@@ -68,3 +73,11 @@ test('release names stay text and release tags stay within the tag URL', async (
   assert.match(elements['version-placeholder'].textContent, /Breaking changes/);
   assert.doesNotMatch(elements['version-placeholder'].textContent, /<img/);
 });
+
+test('a timed-out request keeps a truthful fallback destination and label', async () => {
+  const signal = AbortSignal.abort(new DOMException('Request timed out', 'TimeoutError'));
+  const elements = await load(async (url, { signal }) => { throw signal.reason; }, signal);
+  assert.equal(elements['spec-link'].href, latest);
+  assert.equal(elements['spec-link'].textContent, 'Read the full methodology specification on GitHub');
+  assert.equal(elements['version-placeholder'].textContent, 'View the latest methodology specification on GitHub.');
+});

.github/scripts/test_site_artifact.py

@@ -1,10 +1,78 @@
 from pathlib import Path
+from html.parser import HTMLParser
 import tempfile
 import unittest
+from urllib.parse import urljoin
 from build_site import build, consumer_paths
 
 
+class Navigation(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.navs = []
+        self.current = None
+
+    def handle_starttag(self, tag, attrs):
+        attrs = dict(attrs)
+        if tag == "nav":
+            self.current = {"class": attrs.get("class"), "label": attrs.get("aria-label"), "links": []}
+            self.navs.append(self.current)
+        elif tag == "a" and self.current is not None:
+            self.current["links"].append({**attrs, "text": ""})
+
+    def handle_data(self, text):
+        if self.current is not None and self.current["links"]:
+            self.current["links"][-1]["text"] += text
+
+    def handle_endtag(self, tag):
+        if tag == "nav":
+            self.current = None
+
+
 class SiteArtifactTests(unittest.TestCase):
+    def test_reader_pages_expose_the_primary_destinations_in_initial_html(self):
+        root = Path.cwd()
+        for path in sorted(consumer_paths(root)):
+            if not path.endswith("index.html") or path == "marketplace-status/index.html":
+                continue
+            html = (root / path).read_text()
+            if '<header class="site-header">' not in html:
+                continue
+            with self.subTest(page=path):
+                parser = Navigation()
+                parser.feed(html)
+                menus = [nav for nav in parser.navs if nav["class"] == "site-nav"]
+                self.assertEqual(len(menus), 1)
+                german = path.startswith("de/")
+                expected = [
+                    ("/learn/", "Lernen (EN)" if german else "Learn"),
+                    ("/de/dsl-examples/" if german else "/dsl-examples/", "Beispiele" if german else "Examples"),
+                    ("https://github.com/transitrix/methodology", "Methodik (EN)" if german else "Methodology"),
+                    ("/library/", "Bibliothek (EN)" if german else "Library"),
+                    ("/de/install/" if german else "/install/", "Installieren & starten" if german else "Install & start"),
+                ]
+                self.assertEqual(menus[0]["label"], "Hauptnavigation" if german else "Primary")
+                self.assertEqual([(a["href"], a["text"].strip()) for a in menus[0]["links"]], expected)
+                methodology = menus[0]["links"][2]
+                self.assertEqual(methodology.get("target"), "_blank")
+                self.assertEqual(set(methodology.get("rel", "").split()), {"noopener", "noreferrer"})
+                for href, _ in expected:
+                    if href.startswith("/"):
+                        self.assertTrue((root / href.lstrip("/") / "index.html").is_file())
+
+    def test_learning_path_can_be_followed_forward_and_backward(self):
+        steps = ["what-is-transitrix", "vs-drawing-tools", "enterprise-as-text", "do-i-need-dsm",
+                 "which-editor", "install", "strategy-and-behaviour", "is-it-open-source"]
+        for i, slug in enumerate(steps):
+            with self.subTest(page=slug):
+                parser = Navigation()
+                parser.feed((Path(slug) / "index.html").read_text())
+                navs = [nav for nav in parser.navs if nav["label"] == "Learning path navigation"]
+                self.assertEqual(len(navs), 1)
+                expected = ["/" + (steps[i - 1] if i else "learn") + "/",
+                            "/" + (steps[i + 1] if i + 1 < len(steps) else "dsl-examples") + "/"]
+                self.assertEqual([urljoin("/" + slug + "/", a["href"]) for a in navs[0]["links"]], expected)
+
     def test_real_site_has_only_consumer_paths_and_preserves_bytes(self):
         root = Path.cwd()
         with tempfile.TemporaryDirectory(prefix="site-artifact-") as tmp:

assets/css/style.css

@@ -90,7 +90,7 @@ a:hover {
 }
 
 .site-header {
-  padding: 1.75rem 0 2rem;
+  padding: 1rem 0;
   border-bottom: 1px solid var(--border);
 }
 
@@ -125,7 +125,7 @@ a:hover {
 }
 
 .header-right .theme-toggle {
-  margin-right: 1.75rem;
+  margin-right: 0;
 }
 
 .theme-toggle:hover {
@@ -185,6 +185,7 @@ a:hover {
 
 main {
   padding: 3rem 0 4rem;
+  overflow-wrap: anywhere;
 }
 
 .hero {
@@ -930,3 +931,42 @@ section ul li {
 .path-nav .path-next {
   margin-left: auto;
 }
+
+/* Primary links remain available at every width, including without JavaScript. */
+.site-nav {
+  flex-basis: 100%;
+  min-width: 0;
+}
+
+.site-nav ul {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 1.25rem;
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.site-nav a {
+  display: inline-block;
+  padding: 0.35rem 0;
+  font-size: 0.9rem;
+  text-decoration: none;
+}
+
+.site-nav a:hover,
+.site-nav a[aria-current="page"] {
+  text-decoration: underline;
+}
+
+a:focus-visible,
+button:focus-visible {
+  outline: 2px solid var(--cta);
+  outline-offset: 3px;
+}
+
+.next-step {
+  color: var(--muted);
+  margin: 2rem 0 0;
+  max-width: 44rem;
+}

de/dsl-examples/index.html

@@ -48,9 +48,18 @@
           <a href="./" aria-current="true">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Hauptnavigation">
+        <ul>
+          <li><a href="/learn/">Lernen (EN)</a></li>
+          <li><a href="/de/dsl-examples/" aria-current="page">Beispiele</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodik (EN)</a></li>
+          <li><a href="/library/">Bibliothek (EN)</a></li>
+          <li><a href="/de/install/">Installieren &amp; starten</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>DSL-Beispiele</h1>
       <p class="lede">Ein minimales, gültiges Beispiel pro Notation, die Transitrix Studio unterstützt — kopieren Sie die Struktur direkt, statt sie zu erraten.</p>
@@ -504,7 +513,7 @@ <h2 id="next-heading">Weiterführend</h2>
         <li>Rezepte, die andere Dateistruktur: <a href="/de/recipes/">Das <code>.ttrs</code>-Rezeptformat</a></li>
         <li>JSON Schemas: <a href="https://github.com/transitrix/transitrix-studio/tree/main/schemas">Schemas auf GitHub</a></li>
         <li>Maschinenlesbare Projektübersicht: <a href="/llms.txt">llms.txt</a></li>
-        <li>Studio installieren, um alles oben live in der Vorschau zu sehen: <a href="/install/">Installieren &amp; starten →</a></li>
+        <li>Studio installieren, um alles oben live in der Vorschau zu sehen: <a href="/de/install/">Installieren &amp; starten →</a></li>
       </ul>
     </section>
   </main>

de/dsm/index.html

@@ -48,9 +48,18 @@
           <a href="./" aria-current="true">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Hauptnavigation">
+        <ul>
+          <li><a href="/learn/">Lernen (EN)</a></li>
+          <li><a href="/de/dsl-examples/">Beispiele</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodik (EN)</a></li>
+          <li><a href="/library/">Bibliothek (EN)</a></li>
+          <li><a href="/de/install/">Installieren &amp; starten</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>Transitrix DSM — die Strategieebene</h1>
       <p class="lede">Dynamisches Strategiemanagement, das auf dem Transitrix-Modell operiert — eine Strategie, die sich aktualisiert, wenn sich das Unternehmensmodell verändert, statt eines Dokuments, das in der Woche nach seiner Verabschiedung veraltet.</p>
@@ -73,6 +82,7 @@ <h2 id="fit-heading">Wo das einzuordnen ist</h2>
       <h2 id="status-heading">Status</h2>
       <p>Transitrix DSM ist heute nicht offen: kein Build zum Installieren, kein Repository zum Klonen, und kein Datum dafür festgelegt, dass sich das ändert. Der Weg, es in Aktion zu sehen, ist ein Gespräch — schreiben Sie an <a href="mailto:hello@transitrix.com">hello@transitrix.com</a>.</p>
     </section>
+    <p class="next-step">Zum Modellieren mit den offenen Werkzeugen: <a href="/de/install/">Studio installieren und das erste Modell erstellen</a>.</p>
   </main>
   <footer class="site-footer">
     <div class="wrap">

de/index.html

@@ -49,9 +49,18 @@
           <a href="./" aria-current="true">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Hauptnavigation">
+        <ul>
+          <li><a href="/learn/">Lernen (EN)</a></li>
+          <li><a href="/de/dsl-examples/">Beispiele</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodik (EN)</a></li>
+          <li><a href="/library/">Bibliothek (EN)</a></li>
+          <li><a href="/de/install/">Installieren &amp; starten</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>Das Unternehmen als Text.<br>Geführt von Menschen und Maschinen gemeinsam.</h1>
       <p class="lede">

de/install/index.html

@@ -48,9 +48,18 @@
           <a href="./" aria-current="true">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Hauptnavigation">
+        <ul>
+          <li><a href="/learn/">Lernen (EN)</a></li>
+          <li><a href="/de/dsl-examples/">Beispiele</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodik (EN)</a></li>
+          <li><a href="/library/">Bibliothek (EN)</a></li>
+          <li><a href="/de/install/" aria-current="page">Installieren &amp; starten</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>Installieren &amp; starten</h1>
       <p class="lede">Zwei Schritte bis zum gerenderten Diagramm: Studio installieren, dann Ihre erste Datei erstellen.</p>

de/recipes/index.html

@@ -48,9 +48,18 @@
           <a href="./" aria-current="true">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Hauptnavigation">
+        <ul>
+          <li><a href="/learn/">Lernen (EN)</a></li>
+          <li><a href="/de/dsl-examples/">Beispiele</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodik (EN)</a></li>
+          <li><a href="/library/">Bibliothek (EN)</a></li>
+          <li><a href="/de/install/">Installieren &amp; starten</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>Das <code>.ttrs</code>-Rezeptformat</h1>
       <p class="lede">Ein Rezept ist Fließtext mit <code>{{ … }}</code>-Direktiven darin. Der Text wird unverändert übernommen; jede Direktive benennt etwas in einem Transitrix-Modell und wird durch das ersetzt, wozu sie aufgelöst wird.</p>

de/strategy-and-behaviour/index.html

@@ -48,9 +48,18 @@
           <a href="./" aria-current="true">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Hauptnavigation">
+        <ul>
+          <li><a href="/learn/">Lernen (EN)</a></li>
+          <li><a href="/de/dsl-examples/">Beispiele</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodik (EN)</a></li>
+          <li><a href="/library/">Bibliothek (EN)</a></li>
+          <li><a href="/de/install/">Installieren &amp; starten</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>Die Strategie- und Verhaltensebene</h1>
       <p class="lede">Zwei Einheiten vervollständigen den Transitrix-Stack — Transitrix DSM und Transitrix Swarm. Beide sind heute nicht offen: nichts zum Herunterladen, kein Repository zum Klonen.</p>
@@ -79,6 +88,7 @@ <h2 id="fit-heading">Wo das einzuordnen ist</h2>
       <h2 id="see-heading">In Aktion sehen</h2>
       <p>Beide laufen heute intern gegen reale Modelle. Wenn Sie eines der beiden in Aktion sehen möchten, ist der Weg dorthin ein Gespräch — schreiben Sie an <a href="mailto:hello@transitrix.com">hello@transitrix.com</a>.</p>
     </section>
+    <p class="next-step">Entdecken Sie die <a href="/de/dsl-examples/">Beispiele für Ziele und Fähigkeiten</a> in der offenen Grundlage.</p>
   </main>
   <footer class="site-footer">
     <div class="wrap">

do-i-need-dsm/index.html

@@ -42,9 +42,18 @@
           <svg class="icon-sun" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>
         </button>
       </div>
+      <nav class="site-nav" aria-label="Primary">
+        <ul>
+          <li><a href="/learn/">Learn</a></li>
+          <li><a href="/dsl-examples/">Examples</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodology</a></li>
+          <li><a href="/library/">Library</a></li>
+          <li><a href="/install/">Install &amp; start</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="path-position">Step 4 of 8 — <a href="../learn/">Back to learning path</a></div>
     <div class="hero">
       <h1>Do I need DSM to get started?</h1>
@@ -57,6 +66,11 @@ <h1>Do I need DSM to get started?</h1>
       <p>Getting started doesn't require it. The open methodology and Transitrix Studio are sufficient to author, validate and render a full model on their own. DSM becomes relevant later, once there's a model worth managing over time — not before.</p>
       <p>More on what DSM does and when it applies is on the <a href="../dsm/">Transitrix DSM page</a>.</p>
     </section>
+    <p class="next-step">Start with the open tools: <a href="/install/">install Studio and create your first model</a>.</p>
+    <nav class="path-nav" aria-label="Learning path navigation">
+      <a href="/enterprise-as-text/" class="path-prev">← Enterprise as text</a>
+      <a href="/which-editor/" class="path-next">Next: Which editor? →</a>
+    </nav>
   </main>
   <footer class="site-footer">
     <div class="wrap">

dsl-examples/index.html

@@ -48,9 +48,18 @@
           <a href="../de/dsl-examples/" hreflang="de">DE</a>
         </nav>
       </div>
+      <nav class="site-nav" aria-label="Primary">
+        <ul>
+          <li><a href="/learn/">Learn</a></li>
+          <li><a href="/dsl-examples/" aria-current="page">Examples</a></li>
+          <li><a href="https://github.com/transitrix/methodology" target="_blank" rel="noopener noreferrer">Methodology</a></li>
+          <li><a href="/library/">Library</a></li>
+          <li><a href="/install/">Install &amp; start</a></li>
+        </ul>
+      </nav>
     </div>
   </header>
-  <main id="main" class="wrap">
+  <main id="main" class="wrap" tabindex="-1">
     <div class="hero">
       <h1>DSL examples</h1>
       <p class="lede">One minimal, valid example per notation Transitrix Studio ships — copy the shape directly instead of guessing at it.</p>