From 424f3035baf06a341ce916f5ccf9703fc63eef64 Mon Sep 17 00:00:00 2001 From: Peter Amiri Date: Mon, 19 Oct 2026 12:42:06 -0700 Subject: [PATCH] fix(web): restore table semantics on the guides and API sites Starlight styles markdown tables with display: block (in @layer starlight.content), which drops the table role in Safari + VoiceOver. The guides site now runs the shared rehype-table-scroll plugin (#4605), which wraps each table in an accessible scroll region, and an unlayered .sl-markdown-content .table-scroll > table rule restores native display. The API site does not use the plugin: Astro runs markdown rehype plugins before rehype-raw, so it would double-wrap the generated parameter tables, which already sit in .wd-params-table with display: table. Its one plain table, the versions list in docs/index.md, is wrapped by hand. Inline code on Starlight pages also gets overflow-wrap: anywhere, matching the blog. Fixes #4608 Co-Authored-By: Claude Opus 5.5 Signed-off-by: Peter Amiri --- web/packages/ui/src/styles/starlight-theme.css | 15 +++++++++++++++ web/sites/api/astro.config.mjs | 6 ++++++ web/sites/api/src/content/docs/index.md | 4 ++++ web/sites/guides/astro.config.mjs | 4 ++++ 4 files changed, 29 insertions(+) diff --git a/web/packages/ui/src/styles/starlight-theme.css b/web/packages/ui/src/styles/starlight-theme.css index 5d4e4429d4..e5523da008 100644 --- a/web/packages/ui/src/styles/starlight-theme.css +++ b/web/packages/ui/src/styles/starlight-theme.css @@ -53,6 +53,10 @@ padding: 0.1em 0.35em; font-family: var(--font-mono); font-size: 0.875em; + /* Long inline code (identifiers, paths) must break inside the column + * rather than push the page sideways at phone width (#4608). Scoped + * away from `pre`, so fenced blocks keep their own scroll. */ + overflow-wrap: anywhere; } /* @@ -199,6 +203,17 @@ starlight-toc a[aria-current='true'] { word-break: break-word; } +/* Markdown tables are wrapped in a .table-scroll region by + * rehype-table-scroll.mjs (guides) or hand-written markup (api index). The + * scroll/focus styles come from base.css. Starlight's layered rule sets + * `display: block` on markdown tables, which drops the native table role for + * assistive tech (#4608); restore native display here, unlayered so it beats + * @layer starlight.content. */ +.sl-markdown-content .table-scroll > table { + display: table; + overflow: visible; +} + /* ── Prev/Next page footer ───────────────────────────────────────── * Starlight ships .link-title at 1.5rem which is louder than needed * on function reference pages where names like clearCachableActions() diff --git a/web/sites/api/astro.config.mjs b/web/sites/api/astro.config.mjs index 92c2f984eb..864b91d858 100644 --- a/web/sites/api/astro.config.mjs +++ b/web/sites/api/astro.config.mjs @@ -33,6 +33,12 @@ export default defineConfig({ // See the guides config: content links authored as `/v4-0-0/...` are not // rewritten by Astro's `base`, so the local bundle prefixes them here. markdown: { + // Deliberately no rehypeTableScroll here. Astro runs + // markdown.rehypePlugins before rehype-raw, so the plugin cannot see + // the raw
wrapper around the generated + // parameter tables and would double-wrap them. The one plain table + // (docs/index.md) is hand-wrapped; the generated tables already get + // display:table back from starlight-theme.css. rehypePlugins: [ [rehypeBasePrefix, { base: process.env.WHEELS_DOCS_BASE || '' }], ], diff --git a/web/sites/api/src/content/docs/index.md b/web/sites/api/src/content/docs/index.md index 508b0b3132..1c6c93bf75 100644 --- a/web/sites/api/src/content/docs/index.md +++ b/web/sites/api/src/content/docs/index.md @@ -8,6 +8,8 @@ from the framework's inline documentation annotations. ## Available versions +
+ | Version | Functions | Status | | ---------------------- | --------- | --------------- | | **[v4.2.0](/v4-2-0/)** | 406 | current release | @@ -22,6 +24,8 @@ from the framework's inline documentation annotations. | [v2.0.0](/v2-0-0/) | 254 | | | [v1.4.5](/v1-4-5/) | 219 | | +
+ ## How to use Every function page includes: diff --git a/web/sites/guides/astro.config.mjs b/web/sites/guides/astro.config.mjs index 9f0f3b6b77..a5c8e3a378 100644 --- a/web/sites/guides/astro.config.mjs +++ b/web/sites/guides/astro.config.mjs @@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'; import { dirname, resolve } from 'node:path'; import { GUIDES_VERSIONS } from '@wheels-dev/ui/data/versions'; import { rehypeBasePrefix } from '@wheels-dev/ui/markdown/rehype-base-prefix.mjs'; +import { rehypeTableScroll } from '@wheels-dev/ui/markdown/rehype-table-scroll.mjs'; import { remarkBasePrefix } from '@wheels-dev/ui/markdown/remark-base-prefix.mjs'; import cfmlGrammar from './languages/cfml.tmLanguage.json'; import cfscriptGrammar from './languages/cfscript.tmLanguage.json'; @@ -96,6 +97,9 @@ const config = defineConfig({ // rewrites them at build time. No-op when base is unset. rehypePlugins: [ [rehypeBasePrefix, { base: process.env.WHEELS_DOCS_BASE || '' }], + // Wrap markdown tables in the shared accessible scroll region so + // Starlight's `display: block` stopgap can be overridden (#4608). + rehypeTableScroll, ], }, redirects: {