Lay out the documentation like kotlinlang.org/docsdesign/docs-layout

The three documentation pages each drew their own sidebar. The two hand-built
pages listed different topics: Getting started had no link to Syntax. Each page
also opened with a capitalized section kicker.

DocShell now frames every documentation page:

- On the left, the topics of the site, with the current one marked. On a
  narrow screen they fold into a Contents button above the page.
- Above the page, a breadcrumb: site / Documentation / topic.
- The page in a column of at most 720 px.
- On the right, "On this page". It is read from the h2 headings of the
  rendered page, and each heading gets an id from its words in any script.
  It is hidden below 1100 px.
- Under the page, previous and next topic cards and an "Edit this page"
  link to the file the page is written in.

DocPage, OverviewPage and GettingStartedPage use it and drop their own
sidebars and kickers. The styles of the old layout are removed. The labels
are in all four languages.

3 files changed, 139 insertions, 167 deletions

diff --git a/frontend/src/pages/DocPage.vue b/frontend/src/pages/DocPage.vue
index 061acb4..7b7ec07 100644
--- a/frontend/src/pages/DocPage.vue
+++ b/frontend/src/pages/DocPage.vue
@@ -3,58 +3,46 @@
 
 <script setup lang="ts">
 import { computed } from "vue";
-import { RouterLink } from "vue-router";
-import { sidebarFor } from "../content/routes";
+import DocShell from "../components/DocShell.vue";
 import type { DocTopic } from "../content/types";
 import { locale } from "../preferences";
 import { site } from "../site";
 
 const props = defineProps<{ topic: DocTopic; path: string }>();
 const page = computed(() => props.topic[locale.value]);
-const sidebar = computed(() => sidebarFor(site, locale.value));
-const kicker = { language: "TALA", talac: "TALAC", tazel: "TAZEL" }[site];
+// The file a page of each site is written in, for its "Edit this page" link.
+const source = {
+  language: "src/content/syntax.ts",
+  talac: "src/content/talac.ts",
+  tazel: "src/content/tazel.ts",
+}[site];
 </script>
 
 <template>
-  <div class="doc-layout section-wrap">
-    <aside class="doc-sidebar">
-      <span class="kicker">{{ kicker }}</span
-      ><RouterLink
-        v-for="entry in sidebar"
-        :key="entry.path"
-        :to="entry.path"
-        :aria-current="entry.path === path ? 'page' : undefined"
-        >{{ entry.label }}</RouterLink
-      ><a v-if="site === 'language'" href="https://github.com/Progmasoft/tala/tree/main/Spec"
-        >Specification ↗</a
-      >
-    </aside>
-    <article class="doc-content">
-      <span class="kicker">{{ page.section }}</span>
-      <h1>{{ page.heading }}</h1>
-      <p class="doc-lead">{{ page.lead }}</p>
-      <template v-for="(block, index) in page.blocks" :key="index">
-        <h2 v-if="block.kind === 'heading'">{{ block.text }}</h2>
-        <h3 v-else-if="block.kind === 'subheading'">{{ block.text }}</h3>
-        <p v-else-if="block.kind === 'text'">{{ block.text }}</p>
-        <pre
-          v-else-if="block.kind === 'code'"
-          class="doc-code"
-          dir="ltr"
-        ><code>{{ block.code }}</code></pre>
-        <dl v-else-if="block.kind === 'terms'" class="doc-boundaries">
-          <div v-for="item in block.items" :key="item.term">
-            <dt dir="ltr">
-              <code>{{ item.term }}</code>
-            </dt>
-            <dd>{{ item.detail }}</dd>
-          </div>
-        </dl>
-        <div v-else-if="block.kind === 'note'" class="doc-note">
-          <h3>{{ block.title }}</h3>
-          <p>{{ block.text }}</p>
+  <DocShell :path="path" :edit-path="source">
+    <h1>{{ page.heading }}</h1>
+    <p class="doc-lead">{{ page.lead }}</p>
+    <template v-for="(block, index) in page.blocks" :key="index">
+      <h2 v-if="block.kind === 'heading'">{{ block.text }}</h2>
+      <h3 v-else-if="block.kind === 'subheading'">{{ block.text }}</h3>
+      <p v-else-if="block.kind === 'text'">{{ block.text }}</p>
+      <pre
+        v-else-if="block.kind === 'code'"
+        class="doc-code"
+        dir="ltr"
+      ><code>{{ block.code }}</code></pre>
+      <dl v-else-if="block.kind === 'terms'" class="doc-boundaries">
+        <div v-for="item in block.items" :key="item.term">
+          <dt dir="ltr">
+            <code>{{ item.term }}</code>
+          </dt>
+          <dd>{{ item.detail }}</dd>
         </div>
-      </template>
-    </article>
-  </div>
+      </dl>
+      <div v-else-if="block.kind === 'note'" class="doc-note">
+        <h3>{{ block.title }}</h3>
+        <p>{{ block.text }}</p>
+      </div>
+    </template>
+  </DocShell>
 </template>
diff --git a/frontend/src/pages/GettingStartedPage.vue b/frontend/src/pages/GettingStartedPage.vue
index e526aff..d5794e7 100644
--- a/frontend/src/pages/GettingStartedPage.vue
+++ b/frontend/src/pages/GettingStartedPage.vue
@@ -2,6 +2,7 @@
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
 
 <script setup lang="ts">
+import DocShell from "../components/DocShell.vue";
 import { computed } from "vue";
 import { RouterLink } from "vue-router";
 import { arrow, locale } from "../preferences";
@@ -256,69 +257,60 @@ public class HelloWorld {
 </script>
 
 <template>
-  <div class="doc-layout section-wrap">
-    <aside class="doc-sidebar">
-      <span class="kicker">TALA</span
-      ><RouterLink to="/docs/overview">{{ c.navOverview }}</RouterLink
-      ><RouterLink to="/docs/getting-started" aria-current="page">{{ c.navStart }}</RouterLink
-      ><a href="https://github.com/Progmasoft/tala/tree/main/Spec">Specification ↗</a>
-    </aside>
-    <article class="doc-content">
-      <span class="kicker">{{ c.section }}</span>
-      <h1>{{ c.title }}</h1>
-      <p class="doc-lead">{{ c.lead }}</p>
-      <h2>{{ c.step1 }}</h2>
-      <p>{{ c.step1Text }}</p>
-      <pre
-        class="doc-code"
-      ><code>git clone --recurse-submodules https://github.com/Progmasoft/tala.git</code></pre>
-      <h2>{{ c.step2 }}</h2>
-      <p>{{ c.step2Text }}</p>
-      <p>{{ c.platform }}</p>
-      <pre class="doc-code"><code>go run ./helpers/cmd/develop doctor</code></pre>
-      <h3>{{ c.bootstrap }}</h3>
-      <p>{{ c.toolchainHelp }}</p>
-      <pre class="doc-code"><code>go run ./helpers/cmd/prebuild check
+  <DocShell path="/docs/getting-started" edit-path="src/pages/GettingStartedPage.vue">
+    <h1>{{ c.title }}</h1>
+    <p class="doc-lead">{{ c.lead }}</p>
+    <h2>{{ c.step1 }}</h2>
+    <p>{{ c.step1Text }}</p>
+    <pre
+      class="doc-code"
+    ><code>git clone --recurse-submodules https://github.com/Progmasoft/tala.git</code></pre>
+    <h2>{{ c.step2 }}</h2>
+    <p>{{ c.step2Text }}</p>
+    <p>{{ c.platform }}</p>
+    <pre class="doc-code"><code>go run ./helpers/cmd/develop doctor</code></pre>
+    <h3>{{ c.bootstrap }}</h3>
+    <p>{{ c.toolchainHelp }}</p>
+    <pre class="doc-code"><code>go run ./helpers/cmd/prebuild check
 go run ./helpers/cmd/prebuild install</code></pre>
-      <h2>{{ c.step3 }}</h2>
-      <p>{{ c.step3Text }}</p>
-      <pre class="doc-code"><code>go run ./helpers/cmd/develop build
+    <h2>{{ c.step3 }}</h2>
+    <p>{{ c.step3Text }}</p>
+    <pre class="doc-code"><code>go run ./helpers/cmd/develop build
 go run ./helpers/cmd/develop test</code></pre>
-      <h2>{{ c.step4 }}</h2>
-      <p>{{ c.step4Text }}</p>
-      <pre class="doc-code"><code>{{ hello }}</code></pre>
-      <h3>{{ c.fileCheck }}</h3>
-      <pre
-        class="doc-code"
-      ><code>talac Examples/HelloWorld/HelloWorld.tala --emit=metadata</code></pre>
-      <h3>{{ c.fileBuild }}</h3>
-      <pre
-        class="doc-code"
-      ><code>talac Examples/HelloWorld/HelloWorld.tala --entry=Examples.HelloWorld.HelloWorld</code></pre>
-      <p>{{ c.subset }}</p>
-      <h2>{{ c.step5 }}</h2>
-      <p>{{ c.step5Text }}</p>
-      <pre class="doc-code"><code>talac --help
+    <h2>{{ c.step4 }}</h2>
+    <p>{{ c.step4Text }}</p>
+    <pre class="doc-code"><code>{{ hello }}</code></pre>
+    <h3>{{ c.fileCheck }}</h3>
+    <pre
+      class="doc-code"
+    ><code>talac Examples/HelloWorld/HelloWorld.tala --emit=metadata</code></pre>
+    <h3>{{ c.fileBuild }}</h3>
+    <pre
+      class="doc-code"
+    ><code>talac Examples/HelloWorld/HelloWorld.tala --entry=Examples.HelloWorld.HelloWorld</code></pre>
+    <p>{{ c.subset }}</p>
+    <h2>{{ c.step5 }}</h2>
+    <p>{{ c.step5Text }}</p>
+    <pre class="doc-code"><code>talac --help
 tazel help</code></pre>
-      <div class="doc-resource-list">
-        <a v-for="link in c.links" :key="link.href" :href="link.href">
-          <strong>{{ link.title }} <span aria-hidden="true">↗</span></strong>
-          <span>{{ link.detail }}</span>
-        </a>
-      </div>
-      <div class="doc-note">
-        <h3>{{ c.note }}</h3>
-        <p>{{ c.noteText }}</p>
-      </div>
-      <div class="doc-actions">
-        <RouterLink class="button button-primary" to="/docs/overview"
-          >{{ c.more }} {{ arrow }}</RouterLink
-        ><a class="inline-link" href="https://github.com/Progmasoft/tala/tree/main/Spec"
-          >{{ c.spec }} ↗</a
-        ><a class="inline-link" href="https://github.com/Progmasoft/tala/tree/main/Examples"
-          >{{ c.examples }} ↗</a
-        >
-      </div>
-    </article>
-  </div>
+    <div class="doc-resource-list">
+      <a v-for="link in c.links" :key="link.href" :href="link.href">
+        <strong>{{ link.title }} <span aria-hidden="true">↗</span></strong>
+        <span>{{ link.detail }}</span>
+      </a>
+    </div>
+    <div class="doc-note">
+      <h3>{{ c.note }}</h3>
+      <p>{{ c.noteText }}</p>
+    </div>
+    <div class="doc-actions">
+      <RouterLink class="button button-primary" to="/docs/overview"
+        >{{ c.more }} {{ arrow }}</RouterLink
+      ><a class="inline-link" href="https://github.com/Progmasoft/tala/tree/main/Spec"
+        >{{ c.spec }} ↗</a
+      ><a class="inline-link" href="https://github.com/Progmasoft/tala/tree/main/Examples"
+        >{{ c.examples }} ↗</a
+      >
+    </div>
+  </DocShell>
 </template>
diff --git a/frontend/src/pages/OverviewPage.vue b/frontend/src/pages/OverviewPage.vue
index 2c4ccf0..4463135 100644
--- a/frontend/src/pages/OverviewPage.vue
+++ b/frontend/src/pages/OverviewPage.vue
@@ -2,6 +2,7 @@
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
 
 <script setup lang="ts">
+import DocShell from "../components/DocShell.vue";
 import { computed } from "vue";
 import { RouterLink } from "vue-router";
 import { arrow, locale } from "../preferences";
@@ -474,67 +475,58 @@ const c = computed(() => text[locale.value]);
 </script>
 
 <template>
-  <div class="doc-layout section-wrap">
-    <aside class="doc-sidebar">
-      <span class="kicker">TALA</span
-      ><RouterLink to="/docs/overview" aria-current="page">{{ c.navOverview }}</RouterLink
-      ><RouterLink to="/docs/getting-started">{{ c.navStart }}</RouterLink
-      ><a href="https://github.com/Progmasoft/tala/tree/main/Spec">Specification ↗</a>
-    </aside>
-    <article class="doc-content">
-      <span class="kicker">{{ c.section }}</span>
-      <h1>{{ c.title }}</h1>
-      <p class="doc-lead">{{ c.lead }}</p>
-      <h2>{{ c.goals }}</h2>
-      <div class="doc-points">
-        <section v-for="item in c.items" :key="item.title">
-          <h3>{{ item.title }}</h3>
-          <p>{{ item.body }}</p>
-        </section>
+  <DocShell path="/docs/overview" edit-path="src/pages/OverviewPage.vue">
+    <h1>{{ c.title }}</h1>
+    <p class="doc-lead">{{ c.lead }}</p>
+    <h2>{{ c.goals }}</h2>
+    <div class="doc-points">
+      <section v-for="item in c.items" :key="item.title">
+        <h3>{{ item.title }}</h3>
+        <p>{{ item.body }}</p>
+      </section>
+    </div>
+    <h2>{{ c.modelHeading }}</h2>
+    <p>{{ c.modelIntro }}</p>
+    <div class="doc-points">
+      <section v-for="item in c.model" :key="item.title">
+        <h3>{{ item.title }}</h3>
+        <p>{{ item.body }}</p>
+      </section>
+    </div>
+    <h2>{{ c.pipelineHeading }}</h2>
+    <p>{{ c.pipelineIntro }}</p>
+    <ol class="doc-pipeline">
+      <li v-for="step in c.pipeline" :key="step.title">
+        <h3>{{ step.title }}</h3>
+        <p>{{ step.body }}</p>
+      </li>
+    </ol>
+    <h2>{{ c.boundariesHeading }}</h2>
+    <dl class="doc-boundaries">
+      <div v-for="boundary in c.boundaries" :key="boundary.label">
+        <dt>{{ boundary.label }}</dt>
+        <dd>{{ boundary.value }}</dd>
       </div>
-      <h2>{{ c.modelHeading }}</h2>
-      <p>{{ c.modelIntro }}</p>
-      <div class="doc-points">
-        <section v-for="item in c.model" :key="item.title">
-          <h3>{{ item.title }}</h3>
-          <p>{{ item.body }}</p>
-        </section>
+    </dl>
+    <h2>{{ c.not }}</h2>
+    <p>{{ c.notText }}</p>
+    <h2>{{ c.questionHeading }}</h2>
+    <div class="doc-points">
+      <section v-for="question in c.questions" :key="question.q">
+        <h3>{{ question.q }}</h3>
+        <p>{{ question.a }}</p>
+      </section>
+    </div>
+    <div class="doc-next">
+      <h2>{{ c.next }}</h2>
+      <p>{{ c.nextText }}</p>
+      <div class="doc-actions">
+        <RouterLink class="button button-primary" to="/docs/getting-started"
+          >{{ c.start }} {{ arrow }}</RouterLink
+        ><a class="button button-quiet" href="https://github.com/Progmasoft/tala/tree/main/Spec"
+          >{{ c.spec }} ↗</a
+        ><a class="inline-link" href="https://github.com/Progmasoft/tala">{{ c.source }} ↗</a>
       </div>
-      <h2>{{ c.pipelineHeading }}</h2>
-      <p>{{ c.pipelineIntro }}</p>
-      <ol class="doc-pipeline">
-        <li v-for="step in c.pipeline" :key="step.title">
-          <h3>{{ step.title }}</h3>
-          <p>{{ step.body }}</p>
-        </li>
-      </ol>
-      <h2>{{ c.boundariesHeading }}</h2>
-      <dl class="doc-boundaries">
-        <div v-for="boundary in c.boundaries" :key="boundary.label">
-          <dt>{{ boundary.label }}</dt>
-          <dd>{{ boundary.value }}</dd>
-        </div>
-      </dl>
-      <h2>{{ c.not }}</h2>
-      <p>{{ c.notText }}</p>
-      <h2>{{ c.questionHeading }}</h2>
-      <div class="doc-points">
-        <section v-for="question in c.questions" :key="question.q">
-          <h3>{{ question.q }}</h3>
-          <p>{{ question.a }}</p>
-        </section>
-      </div>
-      <div class="doc-next">
-        <h2>{{ c.next }}</h2>
-        <p>{{ c.nextText }}</p>
-        <div class="doc-actions">
-          <RouterLink class="button button-primary" to="/docs/getting-started"
-            >{{ c.start }} {{ arrow }}</RouterLink
-          ><a class="button button-quiet" href="https://github.com/Progmasoft/tala/tree/main/Spec"
-            >{{ c.spec }} ↗</a
-          ><a class="inline-link" href="https://github.com/Progmasoft/tala">{{ c.source }} ↗</a>
-        </div>
-      </div>
-    </article>
-  </div>
+    </div>
+  </DocShell>
 </template>