Merge pull request #23 from galaxyproject/site

Toolchain floor: bring the pattern site onto the reference stack

Author: jmchilton

content/pattern/standing-up-a-foundry.instructions.txt

@@ -266,15 +266,35 @@ that a note is well-formed.
   legibility is a substrate concern.
 - ASTRO 7 RUNS NO REMARK OR REHYPE PLUGIN UNLESS YOU ASK. It renders markdown with Sätteri, a Rust
   pipeline, and `markdown.remarkPlugins` — the astro ≤6 spelling, and the one every tutorial still
-  shows — is simply not consulted. It does not warn. The failure is a site that builds clean with
-  every `[[Target]]` rendered as literal text and every `$…$` as literal dollars, which is why the
-  wiring above names `markdown.processor` instead: opting the unified pipeline back in explicitly.
-  For this stack that is not a nicety — `[[wiki-links]]` is one of the six installed packages, and
-  Part 4's link check asserts against a grammar the renderer would no longer be applying.
-  `compressHTML: true` is a second pin of the same shape: 7 defaults it to 'jsx', which drops the
-  whitespace between inline elements that sit on their own source lines, so prose silently loses
-  spaces around links. Both are places where the SILENT default changed, and both are worth a
-  comment in the config saying so — a future reader deleting either sees no test go red.
+  shows — is not the wiring any more, which is why the block above names `markdown.processor`
+  instead: opting the unified pipeline back in explicitly. For this stack that is not a nicety —
+  `[[wiki-links]]` is one of the six installed packages, and Part 4's link check asserts against a
+  grammar the renderer would no longer be applying.
+  This entry USED to say the legacy spelling was silently ignored, leaving a site that built clean
+  with every `[[Target]]` rendered as literal text. Measured against 7.1.6 while bringing the
+  pattern repo itself onto the stack, that is wrong, and wrong in the reassuring direction: there
+  is a shim. With `@astrojs/markdown-remark` absent the build FAILS and names the package to
+  install. With it present, and `markdown.processor` either unset or already a unified one, the
+  plugins are moved onto it and you get a deprecation warning. Either way you are told. Write
+  `markdown.processor` because it is the form the shim is asking for, not out of fear of a silent
+  break. The one arrangement that still loses plugins quietly is setting `processor: satteri(…)`
+  and leaving `remarkPlugins` beside it: the shim will not migrate onto a non-unified processor,
+  so you get a warning and no plugins. Do not spell both.
+- `compressHTML: true` is the pin in this part that DOES fail silently, and it is the one to spend
+  the paranoia on. 7 defaults it to 'jsx', which drops the whitespace between inline elements that
+  sit on their own source lines. Removing the pin on a finished site builds clean and glues prose
+  together on every page — nav rendering as `The PatternThe CaseInstances`, and the spaces around
+  inline links gone. Nothing goes red. Worth a comment in the config saying so, because a future
+  reader deleting it gets no other signal.
+  Both pins share a lesson bigger than either: ACCEPT A BUMP ON THE RENDERED PAGE, NOT THE BUILD.
+  A green `astro build` is evidence about the build, and these are defaults that change the OUTPUT.
+  Keep the pre-bump dist/, then diff the rendered TEXT of every page against it: strip the tags,
+  collapse runs of whitespace, compare. A glued word merges two tokens into one, so it shows up as
+  a changed line. Count the resolved `[[link]]` anchors on both sides too — equal counts is the
+  check the processor migration actually needs.
+  Strip each tag to the EMPTY STRING, not to a space. Replacing `</a>` with a space re-supplies
+  the very whitespace compressHTML dropped, and the comparison passes clean on a site whose every
+  page has visibly run together — which is this bullet's own failure mode, found by running it.
 - Declare routes in the page router site/src/pages/<collection>/[...slug].astro (+ index.astro
   per collection), and name each route AFTER ITS COLLECTION KEY, so the key IS the route and
   there is no mapping to keep. The collection table (Part 3) is then the only list of

site/astro.config.mjs

@@ -1,5 +1,6 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
 import tailwindcss from '@tailwindcss/vite';
 import pagefind from 'astro-pagefind';
 import remarkWikiLinks from './src/lib/remark-wiki-links.ts';
@@ -12,13 +13,22 @@ const BASE = '/foundry-pattern';
 export default defineConfig({
   site: SITE,
   base: BASE,
+  // Astro 7 defaults this to 'jsx', which drops the whitespace between inline elements that
+  // sit on their own source lines — prose loses the spaces around its links. Pinned to the
+  // pre-7 behaviour rather than hand-spacing the components.
+  compressHTML: true,
   integrations: [pagefind()],
+  // Astro 7 renders markdown with Sätteri, which runs no remark plugins. `[[wiki-links]]` are
+  // this corpus's link grammar and the prebuild link check asserts against them, so the unified
+  // pipeline is opted back into explicitly. The astro ≤6 spelling — `markdown.remarkPlugins` —
+  // still works in 7.1.6 via a shim that migrates the array onto a unified processor and warns;
+  // this is the non-deprecated form the shim is telling you to write.
   markdown: {
-    remarkPlugins: [[remarkWikiLinks, { contentDir: '../content', base: BASE }]],
+    processor: unified({
+      remarkPlugins: [[remarkWikiLinks, { contentDir: '../content', base: BASE }]],
+    }),
   },
   vite: {
-    // Cast: Astro bundles its own nested vite, so the plugin's vite types and the
-    // top-level vite types are nominally distinct though structurally identical.
-    plugins: [/** @type {any} */ (tailwindcss())],
+    plugins: [tailwindcss()],
   },
 });