Fix Markdown table rendering (#1216)

Enable GFM rendering for the docs pipeline and add a Playwright regression test that validates common Markdown renders as semantic HTML on the contributor guide.

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: IEvangelist

.agents/skills/doc-writer/SKILL.md

@@ -146,6 +146,18 @@ When you introduce or change a custom component that is used by docs pages:
 - Prefer moving heavier shared logic into colocated `.ts` helpers when the `.astro` frontmatter becomes large or is duplicated across components.
 - Treat user-visible behavior, accessibility, and responsive behavior as part of the documentation contract, not as optional polish.
 
+### Common Markdown syntax
+
+Use the rendered examples in `src/frontend/src/content/docs/community/contributor-guide.mdx` as the canonical reference for common Markdown syntax. When adding tables, use padded pipes, a separator row with at least three hyphens per cell, and blank lines before and after the table:
+
+```md
+| Feature | Description | Status |
+| ------- | ----------- | ------ |
+| Dashboard | Web-based monitoring | Available |
+```
+
+Do not replace standard Markdown with ad hoc HTML unless a component or layout requirement cannot be expressed clearly in Markdown.
+
 #### Aside (Callouts)
 
 Prefer fenced `:::` callouts for tips, notes, cautions, and warnings. Use the `Aside` component only when a JSX-only composition pattern is required.

src/frontend/astro.config.mjs

@@ -10,6 +10,7 @@ import { socialConfig } from './config/socials.config.ts';
 import catppuccin from '@catppuccin/starlight';
 import lunaria from './config/lunaria-starlight.mjs';
 import mermaid from 'astro-mermaid';
+import mdx from '@astrojs/mdx';
 import starlight from '@astrojs/starlight';
 import starlightGitHubAlerts from 'starlight-github-alerts';
 import starlightImageZoom from 'starlight-image-zoom';
@@ -224,6 +225,10 @@ export default defineConfig({
         }),
       ],
     }),
+    mdx({
+      optimize: true,
+      gfm: true,
+    }),
     jopSoftwarecookieconsent(cookieConfig),
     ...(isBuildTimingEnabled ? [buildTiming()] : []),
   ],

src/frontend/package.json

@@ -59,6 +59,7 @@
   "dependencies": {
     "@astro-community/astro-embed-vimeo": "^0.3.12",
     "@astro-community/astro-embed-youtube": "^0.5.10",
+    "@astrojs/mdx": "^5.0.6",
     "@astrojs/rss": "^4.0.18",
     "@astrojs/starlight": "^0.39.3",
     "@catppuccin/starlight": "^2.0.1",

src/frontend/pnpm-lock.yaml

@@ -391,23 +391,23 @@ Renders as:
 
 ### Tables
 
-Create tables using pipes `|` and hyphens `-`:
+Create tables using pipes `|` and hyphens `-`. Keep a blank line before and after the table, include one separator cell for each heading, and use at least three hyphens in each separator cell:
 
 ```md title="src/content/docs/example.md"
 | Feature | Description | Status |
-|--|--|--|
-| Dashboard | Web-based monitoring | ✅ Available |
-| Telemetry | OpenTelemetry support | ✅ Available |
-| Deployment | Kubernetes deployment | 🚧 Preview |
+| ------- | ----------- | ------ |
+| Dashboard | Web-based monitoring | Available |
+| Telemetry | OpenTelemetry support | Available |
+| Deployment | Kubernetes deployment | Preview |
 ```
 
 Renders as:
 
 | Feature | Description | Status |
-|--|--|--|
-| Dashboard | Web-based monitoring | ✅ Available |
-| Telemetry | OpenTelemetry support | ✅ Available |
-| Deployment | Kubernetes deployment | 🚧 Preview |
+| ------- | ----------- | ------ |
+| Dashboard | Web-based monitoring | Available |
+| Telemetry | OpenTelemetry support | Available |
+| Deployment | Kubernetes deployment | Preview |
 
 <Aside type="tip">
   You can align columns using colons: `| :--- |` for left, `| :---: |` for center, and `| ---: |` for right alignment.

src/frontend/src/content/docs/community/contributor-guide.mdx

@@ -0,0 +1,56 @@
+import { expect, test } from '@playwright/test';
+
+import { dismissCookieConsentIfVisible } from '@tests/e2e/helpers';
+
+test('contributor guide renders common Markdown as semantic HTML', async ({ page }) => {
+  await page.goto('/community/contributor-guide/#write-markdown');
+  await dismissCookieConsentIfVisible(page);
+
+  const main = page.locator('main');
+  await expect(page.getByRole('heading', { name: /Write Markdown/i })).toBeVisible();
+
+  const markdownTable = main
+    .locator('table')
+    .filter({ hasText: 'Dashboard' })
+    .filter({ hasText: 'OpenTelemetry support' })
+    .first();
+
+  await expect(markdownTable).toBeVisible();
+  await expect(markdownTable.locator('thead th')).toHaveText([
+    'Feature',
+    'Description',
+    'Status',
+  ]);
+  await expect(markdownTable.locator('tbody tr')).toHaveCount(3);
+  await expect(markdownTable).toContainText('Kubernetes deployment');
+
+  await expect(main.locator('p').filter({ hasText: /^\|\s*Feature\s*\|/ })).toHaveCount(0);
+  await expect(main.getByRole('complementary', { name: 'Tip' }).first()).toBeVisible();
+  await expect(main.getByRole('link', { name: 'David Pine' })).toHaveAttribute(
+    'href',
+    /https:\/\/davidpine\.net\/?/
+  );
+  await expect(main.locator('p code').filter({ hasText: 'Inline code' })).toBeVisible();
+  await expect(
+    main.locator('pre code').filter({ hasText: 'builder.AddProject<Projects.ApiService>' }).first()
+  ).toBeVisible();
+  await expect(
+    main.locator('blockquote').filter({ hasText: 'This is a note or important callout.' })
+  ).toBeVisible();
+  await expect(main.locator('hr')).toHaveCount(1);
+  await expect(main.locator('del').filter({ hasText: 'This text is crossed out' })).toBeVisible();
+
+  const completedTask = main
+    .locator('li')
+    .filter({ hasText: 'Add Aspire to your project' })
+    .locator('input[type="checkbox"]');
+  const pendingTask = main
+    .locator('li')
+    .filter({ hasText: 'Deploy to Azure' })
+    .locator('input[type="checkbox"]');
+
+  await expect(completedTask).toBeChecked();
+  await expect(pendingTask).not.toBeChecked();
+  await expect(main.locator('ul').filter({ hasText: 'First item' }).first()).toBeVisible();
+  await expect(main.locator('ol').filter({ hasText: 'First step' }).first()).toBeVisible();
+});