From 27f7645d4a020a1ce564dddf7b32e6b22b870644 Mon Sep 17 00:00:00 2001 From: Jonathan Peris Date: Sun, 3 May 2026 00:38:35 -0300 Subject: [PATCH 1/2] refactor(docs): derive SECTION_ORDER and add build-time assertion - Add SECTION_ORDER derived from SECTION_CATEGORIES.flatMap - Add build-time assertion validating category IDs against wiki slugs - Replace hardcoded ORDER with pagesBySlug lookup pattern - Update sectionsToRender to use {slug, page} tuple pattern - Replace hardcoded order array in getStaticPaths with SECTION_ORDER - Fix search clear to reset item.style.display and parent display --- docs/src/pages/docs/[...slug].astro | 64 +++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/docs/src/pages/docs/[...slug].astro b/docs/src/pages/docs/[...slug].astro index 19bb7e2..e034dc3 100644 --- a/docs/src/pages/docs/[...slug].astro +++ b/docs/src/pages/docs/[...slug].astro @@ -2,7 +2,13 @@ import BaseLayout from '../../layouts/BaseLayout.astro'; import '../../styles/docs.css'; -const ORDER = ['home', 'challenge', 'architecture', 'getting-started', 'performance', 'ci-cd-pipeline']; +const SECTION_CATEGORIES = [ + { label: '', ids: ['home'] }, + { label: 'Overview', ids: ['challenge', 'architecture'] }, + { label: 'Develop', ids: ['getting-started', 'performance', 'ci-cd-pipeline'] }, +]; + +const SECTION_ORDER = SECTION_CATEGORIES.flatMap(({ ids }) => ids); const SLUG_LABEL: Record = { home: 'Home', @@ -13,27 +19,44 @@ const SLUG_LABEL: Record = { 'ci-cd-pipeline': 'CI/CD Pipeline', }; -const SECTION_CATEGORIES = [ - { label: '', ids: ['home'] }, - { label: 'Overview', ids: ['challenge', 'architecture'] }, - { label: 'Develop', ids: ['getting-started', 'performance', 'ci-cd-pipeline'] }, -]; - const wikiPages = import.meta.glob('../../../wiki/*.md', { eager: true }); -const isRoot = Astro.params.slug === undefined; +const pagesBySlug: Record = {}; +for (const [path, module] of Object.entries(wikiPages)) { + const fileName = path.split('/').pop()!.replace('.md', ''); + pagesBySlug[fileName] = module; +} + +// Build-time assertion: validate SECTION_CATEGORIES IDs against discovered slugs +const availableSlugs = new Set(Object.keys(pagesBySlug)); +for (const cat of SECTION_CATEGORIES) { + for (const id of cat.ids) { + if (!availableSlugs.has(id)) { + const catName = cat.label || 'root'; + throw new Error( + `SECTION_CATEGORIES references id "${id}" (category: "${catName}") but no matching wiki/${id}.md was found. Available slugs: ${Array.from(availableSlugs).join(', ')}` + ); + } + } +} +const isRoot = Astro.params.slug === undefined; const requestedSlug = Astro.params.slug as string | undefined; const sectionsToRender = isRoot - ? ORDER - : ORDER.filter((slug) => slug === requestedSlug); + ? SECTION_ORDER + .map(slug => ({ slug, page: pagesBySlug[slug] })) + .filter(s => s.page) + : (() => { + const page = pagesBySlug[requestedSlug as string]; + if (!page) return []; + return [{ slug: requestedSlug!, page }]; + })(); export function getStaticPaths() { - const ORDER = ['home', 'challenge', 'architecture', 'getting-started', 'performance', 'ci-cd-pipeline']; return [ { params: { slug: undefined } }, - ...ORDER.map((slug) => ({ params: { slug } })), + ...SECTION_ORDER.filter(s => s !== 'home').map(slug => ({ params: { slug } })), ]; } @@ -109,10 +132,7 @@ const docsBase = Astro.site
- {sectionsToRender.map((slug) => { - const fileName = `${slug}.md`; - const wikiPage = wikiPages[`../../../wiki/${fileName}`]; - if (!wikiPage) return null; + {sectionsToRender.map(({ slug, page: wikiPage }) => { const Content = (wikiPage as any).default ?? wikiPage; return (
@@ -225,6 +245,18 @@ const docsBase = Astro.site } group.style.display = visibleCount === 0 ? 'none' : ''; }); + /* Reset on clear */ + if (!q) { + navItems.forEach(function (item) { + item.style.display = ''; + if (item.parentElement) item.parentElement.style.display = ''; + }); + categoryGroups.forEach(function (group) { + group.style.display = ''; + var catLabel = group.querySelector('.sidebar-category'); + if (catLabel) catLabel.style.display = ''; + }); + } }); } }); From d19e9bb11d80160954cd2477e8e61b13456a0a48 Mon Sep 17 00:00:00 2001 From: Jonathan Peris Date: Sun, 3 May 2026 00:52:10 -0300 Subject: [PATCH 2/2] fix(docs): extract SECTION_CATEGORIES to sidebar.config.ts for Astro hoisting getStaticPaths is hoisted by Astro and cannot reference frontmatter variables. Moving SECTION_CATEGORIES and SECTION_ORDER to sidebar.config.ts allows import to survive hoisting, fixing 'SECTION_ORDER is not defined' build error. Also fixes sectionsToRender to use pagesBySlug lookup pattern and search clear to reset item.style.display and parent display. --- docs/src/pages/docs/[...slug].astro | 9 +-------- docs/src/pages/docs/sidebar.config.ts | 7 +++++++ 2 files changed, 8 insertions(+), 8 deletions(-) create mode 100644 docs/src/pages/docs/sidebar.config.ts diff --git a/docs/src/pages/docs/[...slug].astro b/docs/src/pages/docs/[...slug].astro index e034dc3..f998743 100644 --- a/docs/src/pages/docs/[...slug].astro +++ b/docs/src/pages/docs/[...slug].astro @@ -1,14 +1,7 @@ --- import BaseLayout from '../../layouts/BaseLayout.astro'; import '../../styles/docs.css'; - -const SECTION_CATEGORIES = [ - { label: '', ids: ['home'] }, - { label: 'Overview', ids: ['challenge', 'architecture'] }, - { label: 'Develop', ids: ['getting-started', 'performance', 'ci-cd-pipeline'] }, -]; - -const SECTION_ORDER = SECTION_CATEGORIES.flatMap(({ ids }) => ids); +import { SECTION_CATEGORIES, SECTION_ORDER } from './sidebar.config'; const SLUG_LABEL: Record = { home: 'Home', diff --git a/docs/src/pages/docs/sidebar.config.ts b/docs/src/pages/docs/sidebar.config.ts new file mode 100644 index 0000000..c30b28b --- /dev/null +++ b/docs/src/pages/docs/sidebar.config.ts @@ -0,0 +1,7 @@ +export const SECTION_CATEGORIES = [ + { label: "", ids: ["home"] }, + { label: "Overview", ids: ["challenge", "architecture"] }, + { label: "Develop", ids: ["getting-started", "performance", "ci-cd-pipeline"] }, +] as const; + +export const SECTION_ORDER = SECTION_CATEGORIES.flatMap(({ ids }) => ids);