Rewrite v3 Getting Started docs

sites/website/eleventy.config.js

@@ -57,4 +57,35 @@ export default function (eleventyConfig) {
 
         return version;
     });
+
+    /**
+     * Flatten an eleventy-navigation tree depth-first and return the entries
+     * immediately before and after the current page URL. Used to derive
+     * prev/next pagination from the sidebar order.
+     */
+    eleventyConfig.addFilter("prevNext", function (navTree, currentUrl) {
+        const flat = [];
+
+        (function walk(nodes) {
+            if (!Array.isArray(nodes)) return;
+            for (const node of nodes) {
+                if (node?.url) {
+                    flat.push({ url: node.url, title: node.title });
+                }
+                if (node?.children?.length) {
+                    walk(node.children);
+                }
+            }
+        })(navTree);
+
+        const idx = flat.findIndex(entry => entry.url === currentUrl);
+        if (idx === -1) {
+            return { prev: null, next: null };
+        }
+
+        return {
+            prev: idx > 0 ? flat[idx - 1] : null,
+            next: idx < flat.length - 1 ? flat[idx + 1] : null,
+        };
+    });
 }

sites/website/package.json

@@ -7,7 +7,7 @@
     "clean": "clean build tmp",
     "prebuild": "npm run clean && node scripts/generate-docs.cjs 3",
     "build": "npm run prebuild && npx @11ty/eleventy --output=build --input=src",
-    "start": "npm run prebuild && npx @11ty/eleventy --output=build --input=src --serve",
+    "start": "npm run prebuild && npx @11ty/eleventy --output=build --input=src --serve --incremental",
     "help": "npx @11ty/eleventy --help"
   },
   "browserslist": {

sites/website/src/_includes/3x-container.njk

@@ -26,6 +26,8 @@ navigationOptions:
     <div class="container padding-top--md padding-bottom--lg">
         <div class="col doc-item">
             {{ content | safe }}
+            {% set paginationCollection = collections.3x %}
+            {% include "pagination-nav.njk" %}
         </div>
     </div>
 </main>

sites/website/src/_includes/pagination-nav.njk

@@ -0,0 +1,25 @@
+{# Derives prev/next from the eleventy-navigation tree for the current
+   collection. Requires `paginationCollection` to be set. #}
+{% set siblings = paginationCollection | eleventyNavigation | prevNext(page.url) %}
+{% set prevPage = siblings.prev %}
+{% set nextPage = siblings.next %}
+{% if prevPage or nextPage %}
+<nav class="pagination-nav" aria-label="Documentation page navigation">
+    {% if prevPage %}
+    <a class="pagination-nav__link pagination-nav__link--previous" href="{{ prevPage.url }}">
+        <div class="pagination-nav__sublabel">Previous</div>
+        <div class="pagination-nav__label">«&nbsp;{{ prevPage.title }}</div>
+    </a>
+    {% else %}
+    <div></div>
+    {% endif %}
+    {% if nextPage %}
+    <a class="pagination-nav__link pagination-nav__link--next" href="{{ nextPage.url }}">
+        <div class="pagination-nav__sublabel">Next</div>
+        <div class="pagination-nav__label">{{ nextPage.title }}&nbsp;»</div>
+    </a>
+    {% else %}
+    <div></div>
+    {% endif %}
+</nav>
+{% endif %}

sites/website/src/css/main.css

@@ -2696,6 +2696,47 @@ body:not(.navigation-with-keyboard) :not(input):focus {
     }
 }
 
+.pagination-nav {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 1rem;
+    margin-top: 3rem;
+}
+
+.pagination-nav__link {
+    border: 1px solid var(--ifm-color-emphasis-300);
+    border-radius: var(--ifm-global-radius);
+    display: flex;
+    flex-direction: column;
+    line-height: var(--ifm-heading-line-height);
+    padding: 1rem;
+    transition: border-color var(--ifm-transition-fast)
+        var(--ifm-transition-timing-default);
+}
+
+.pagination-nav__link:hover {
+    border-color: var(--ifm-color-primary);
+    text-decoration: none;
+}
+
+.pagination-nav__link--next {
+    grid-column: 2 / 3;
+    text-align: right;
+}
+
+.pagination-nav__sublabel {
+    color: var(--ifm-color-content-secondary);
+    font-size: var(--ifm-h6-font-size);
+    font-weight: var(--ifm-font-weight-semibold);
+    margin-bottom: 0.25rem;
+}
+
+.pagination-nav__label {
+    color: var(--ifm-link-color);
+    font-weight: var(--ifm-font-weight-bold);
+    word-break: break-word;
+}
+
 @media print {
     .footer,
     .menu,