From 5dd78bde8369c747a595e724a7a33cd8068f63c1 Mon Sep 17 00:00:00 2001 From: Phlex Agent Date: Fri, 7 Aug 2026 13:12:27 -0400 Subject: [PATCH] docs: exclude docs/old/** from the VitePress build MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/old/` holds two superseded planning notes. They were being compiled into the site output as `/old/phlix_update` and `/old/worklog`, reachable by direct URL and indexed by the local search provider. Verified the premise before applying the recorded fix, and it is only half true. `docs/old/` is gitignored (.gitignore:9) and untracked, so `actions/checkout` never materialises it and neither `Build Docs` nor `Deploy Docs` has ever seen those files. The published site has therefore never contained the pages, and this commit does not remove anything from what ships. What it does remove is the local-vs-CI divergence. On a developer checkout the files are present and get built, so every locally measured figure disagrees with CI — 160 pages / 3613 links locally against 158 / 3474 in a clean checkout. A local corpus number consequently could not be compared with the CI one, which has already cost review time. With the exclusion a local build on a tree that still contains the files reports 158 / 3474, byte-identical to the clean-checkout control. Scoped to `old/**` only. `archive/` lives at the repository root, outside VitePress's `docs` srcDir, and was confirmed absent from the build output; it needs no exclusion. Checked for inbound links before excluding — no live page links into `old/**` in either the markdown source or the emitted HTML (the sole grep hit was "household/" in parental-controls.md matching the substring "old/"), so the exclusion creates no dead anchors. The test asserts the resolved `srcExclude` export rather than the config file's text, because a text match would also be satisfied by the comment that explains the option. Co-Authored-By: Claude Opus 5 (1M context) --- docs/.vitepress/config.ts | 19 +++++++++++++++++++ tests/config.import.test.ts | 10 ++++++++++ 2 files changed, 29 insertions(+) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 5cf9dac..50e4f7e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -364,5 +364,24 @@ export default defineConfig({ } }, cleanUrls: false, + // `docs/old/` is a scratch archive of superseded planning notes. It is + // gitignored (.gitignore:9) and untracked, so `actions/checkout` never + // materialises it and the PUBLISHED site has never contained those pages — + // this exclusion is therefore not a fix to what ships. + // + // What it does fix is the local-vs-CI divergence. On a developer checkout the + // two files are present, VitePress happily builds them, and every locally + // measured figure silently disagrees with CI: 159 pages locally vs 157 in a + // clean checkout, with the anchor gate's link corpus inflated to match. That + // gap has already cost review time, because a local corpus number cannot be + // compared against the CI one. Excluding the directory makes a local + // `npm run docs:build` produce the same corpus CI does. + // + // Scoped deliberately to `old/**` only. `archive/` sits at the repository + // root, outside VitePress's `docs` srcDir, so it is already unreachable by + // the build and needs no exclusion. No live page links into `old/**` + // (verified against both the markdown source and the emitted HTML), so + // excluding it creates no dead links for the anchor gate to trip over. + srcExclude: ['old/**'], ignoreDeadLinks: false }) diff --git a/tests/config.import.test.ts b/tests/config.import.test.ts index 77ae0ae..75d588d 100644 --- a/tests/config.import.test.ts +++ b/tests/config.import.test.ts @@ -88,6 +88,16 @@ describe('Config Module Loading', () => { expect(configModule.default.ignoreDeadLinks).toBe(false) }) + // Asserted against the RESOLVED export, not the file text. A + // `configContent.toContain('srcExclude')` check would also be satisfied by + // the explanatory comment sitting directly above the option, so it could not + // tell a live setting apart from a description of one. + it('should exclude docs/old from the build via srcExclude', async () => { + const configModule = await import('../docs/.vitepress/config.ts') + expect(configModule.default).toHaveProperty('srcExclude') + expect(configModule.default.srcExclude).toEqual(['old/**']) + }) + it('should have dark mode enabled', async () => { const configModule = await import('../docs/.vitepress/config.ts') expect(configModule.default.themeConfig).toHaveProperty('darkModeSwitch')