Fix #177 GFM table rendering and WCAG AA contrast failures in docs (#191)

* fix: restore GFM table rendering in .mdx docs

Astro 6.4.x regression (withastro/astro#16971) drops the markdown.gfm
default for .mdx files specifically, so every table in the block docs
(e.g. GitAuth's Providers table) silently rendered as raw pipe text
instead of an HTML table. Set gfm: true explicitly to work around it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix: resolve WCAG AA color-contrast failures across docs theme

Audited every page in both light and dark themes with axe-core; these
were the failures found, all fixed in place with colors already in
the palette where possible:

- --sl-color-gray-3 (dark) was 3.66:1 against the page background,
  failing normal-text AA. It backs Starlight's footer/edit-link text
  plus our TOC and homepage muted text, so this was the widest-reaching
  fix. Lightened to hit 4.5:1+ against both the page bg and gray-7.
- .source-link (dark) used the border-tuned gray-4 for text (2.29:1);
  switched to gray-3.
- The hero "Get Started" button's white text on the dark accent blue
  was 3.68:1; scoped a darker blue to that button only so the shared
  accent variable (fine everywhere else) doesn't need to change.
- A prior gray-6 (dark) tweak aimed at "better backgrounds" had
  lightened the Expressive Code editor background enough to drop the
  built-in syntax theme's comment/keyword/string colors below AA.
  Reverted to the original value, close to the theme's own reference
  background.
- Links inside colored callout boxes (tip/caution/danger asides)
  didn't have enough contrast against every variant's tint, in both
  themes. Added a scoped override.
- Inline <code> inside links was 4.38:1 in light mode, just under the
  4.5:1 threshold; switched to the darker accent-high tone.
- Footer.astro: the decorative "·" separator used a border-tuned
  color; matched it to the surrounding footer text color instead.

Verified with axe-core (WCAG 2 AA) against all 41 docs pages in both
themes: 0 remaining color-contrast violations.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: odgrim

docs/astro.config.mjs

@@ -5,6 +5,14 @@ import starlight from '@astrojs/starlight';
 // https://astro.build/config
 export default defineConfig({
 	site: 'https://runbooks.gruntwork.io',
+	// Astro 6.4.x regression (withastro/astro#16971): markdown.gfm no longer
+	// defaults to true for .mdx files, so GFM tables silently stop rendering
+	// (they fall back through as raw pipe text instead of <table>). Must be
+	// set explicitly at this top level — setting it via a remark/unified
+	// option does not work around the regression.
+	markdown: {
+		gfm: true,
+	},
 	integrations: [
 		starlight({
 			title: 'Gruntwork Runbooks',

docs/src/components/Footer.astro

@@ -52,7 +52,7 @@ import Default from '@astrojs/starlight/components/Footer.astro';
   }
 
   .gruntwork-footer-separator {
-    color: var(--sl-color-gray-5);
+    color: var(--sl-color-gray-3);
   }
 
   .gruntwork-footer-link {

docs/src/styles/custom.css

@@ -64,10 +64,15 @@ html {
   --sl-color-white: #fafafa;
   --sl-color-gray-1: #e4e4e7;
   --sl-color-gray-2: #a1a1aa;
-  --sl-color-gray-3: #71717a;
+  --sl-color-gray-3: #909099;  /* Lightened from #71717a — 3.66:1 on --sl-color-bg failed WCAG AA (4.5:1) for footer/edit-link/TOC text; this hits ~4.7:1+ against both --sl-color-bg and --sl-color-gray-7 */
   --sl-color-gray-4: #52525b;
   --sl-color-gray-5: #52525b;  /* Increased from #3f3f46 for better borders */
-  --sl-color-gray-6: #3f3f46;  /* Increased from #27272a for better backgrounds */
+  --sl-color-gray-6: #27272a;  /* Reverted from #3f3f46: that lighter value became the Expressive Code
+                                   editor background, and the built-in Night Owl syntax theme's comment/
+                                   keyword/string colors (tuned for a ~#23262f bg) dropped to ~3.8:1 against
+                                   it — below WCAG AA. #27272a is close to the theme's own reference bg and
+                                   restores ~5.4:1+ for those tokens; all other consumers (borders, hover
+                                   backgrounds) still pass comfortably at this value too. */
   --sl-color-gray-7: #27272a;  /* Adjusted for code blocks */
   --sl-color-black: #09090b;
 
@@ -201,9 +206,12 @@ header.header {
   color: #93c5fd;
 }
 
-/* Code within links - better contrast */
+/* Code within links - better contrast. Inline code's background is
+   Starlight's --sl-color-bg-inline-code (= gray-6); --sl-color-accent text
+   on top of that only hits 4.38:1 in light mode, just under WCAG AA, so use
+   the darker accent-high tone here instead (6.78:1). */
 .sl-markdown-content a code {
-  color: var(--sl-color-accent);
+  color: var(--sl-color-accent-high);
   text-decoration: none;
   border-bottom: 1px solid transparent;
   transition: border-color 0.15s ease;
@@ -287,6 +295,19 @@ header.header {
   border-left-width: 3px;
 }
 
+/* Our link accent is tuned against a neutral page background, but note/tip/
+   caution/danger asides tint the background per-variant. In some variants
+   (tip, caution in dark mode; note, danger in light mode) that drops link
+   contrast below 4.5:1. Use colors already in the palette that pass against
+   all four variant backgrounds in both themes. */
+.starlight-aside a {
+  color: var(--sl-color-accent-high);
+}
+
+:root[data-theme='dark'] .starlight-aside a {
+  color: #93c5fd;
+}
+
 /* ============================================
    TABLE OF CONTENTS
    ============================================ */
@@ -418,6 +439,15 @@ html[data-has-hero] {
   filter: brightness(1.15);
 }
 
+/* Dark-mode accent (#3b82f6) only gives white text 3.68:1 here — fails WCAG
+   AA (4.5:1). Use a darker blue for this button only; --sl-color-accent
+   itself stays untouched since it passes contrast everywhere else it's used
+   as foreground text/link color. */
+:root[data-theme='dark'][data-has-hero] .hero .sl-link-button.primary {
+  background: #2563eb !important;
+  border-color: #2563eb !important;
+}
+
 [data-has-hero] .hero .sl-link-button.minimal {
   color: #cbd5e1 !important;
   background: transparent !important;
@@ -522,6 +552,12 @@ html[data-has-hero] {
   text-decoration: none !important;
 }
 
+/* Dark-mode gray-4 (#52525b) is tuned for borders, not text — only 2.29:1 on
+   --sl-color-bg. Use gray-3 here instead so the link stays readable. */
+:root[data-theme='dark'][data-has-hero] .source-link {
+  color: var(--sl-color-gray-3) !important;
+}
+
 /* Block list rows on splash page */
 [data-has-hero] .block-list {
   text-align: left;