Skip to content

fix(docs): enable GFM table rendering in Starlight docs - #1944

Merged
Daniel Meppiel (danielmeppiel) merged 2 commits into
microsoft:mainfrom
syf2211:fix/docs-gfm-tables-rendering
Jun 28, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 2 commits into
microsoft:mainfrom
syf2211:fix/docs-gfm-tables-rendering

Conversation

@syf2211

Copy link
Copy Markdown
Contributor

Summary

Enable GFM (GitHub Flavored Markdown) in the Astro docs config so pipe tables render correctly across the site.

Motivation

Fixes #1940. GFM tables (e.g. the "What to commit" section on the quickstart page) were rendering as raw pipe text instead of HTML tables. This is a known regression with Astro 6.4 + Starlight 0.38.x where markdown.gfm is no longer enabled by default.

Changes

  • Add markdown: { gfm: true } to docs/astro.config.mjs
  • Restores GFM table, strikethrough, and task-list support for all .mdx content files

Tests

  • cd docs && npm ci && npm run build — passed (122 pages built, all internal links valid)
  • Verified dist/quickstart/index.html now contains a proper <table> element for the "What to commit" section

Notes

This is the minimal workaround for the current Starlight 0.38.4 pin. A follow-up Starlight upgrade to 0.40.0+ (which includes the canonical fix in withastro/starlight#3923) can be done separately to avoid broader dependency churn in this PR.

@syf2211

Copy link
Copy Markdown
Contributor Author

@microsoft-github-policy-service agree

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Enables GitHub Flavored Markdown (GFM) in the Astro/Starlight docs configuration so pipe tables (and other GFM features) render correctly across the documentation site, addressing the reported table-rendering regression.

Changes:

  • Enable GFM globally via markdown: { gfm: true } in the Astro config.
  • Restore proper rendering for GFM tables, strikethrough, and task lists in .mdx docs content.

Daniel Meppiel (danielmeppiel) added a commit to syf2211/apm that referenced this pull request Jun 28, 2026
Adds the Keep-a-Changelog entry for the docs GFM rendering fix that
closes microsoft#1940. Addresses doc-writer panel follow-up: CHANGELOG entry
for this user-visible fix was missing from [Unreleased] > Fixed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator

APM Review Panel: ship_now

Tiny docs-config fix is correct and safe to land; deprecated-API cleanup deferred to Starlight upgrade.

cc Yuefeng Shi (@syf2211) Daniel Meppiel (@danielmeppiel) Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

All active panelists are aligned on the change. The markdown.gfm: true key is deprecated in current Starlight (0.38.x) but remains the correct workaround until the Starlight 0.40+ upgrade path is available; the build evidence is green. The oss-growth-hacker flags this as conversion-critical: the quickstart landing page uses pipe-table content for the CLI feature comparison matrix, and GFM rendering was visibly broken without this fix. Supply-chain surface is clean. Doc-writer's CHANGELOG nit has been folded by the shepherd in commit fb75f2c. One follow-up deferred (deprecation cleanup) crosses a scope boundary requiring a separate Starlight version upgrade.

Aligned with: User experience (restores table rendering for all documentation visitors); Operational excellence (minimal, targeted config fix with zero Python or logic changes).

Growth signal. The quickstart landing page uses pipe-table content for the CLI feature comparison matrix. GFM rendering was broken without this fix; restoring it improves first-impressions conversion for new visitors.

Panel summary

Persona B R N Takeaway
Supply-chain security 0 0 0 No supply-chain concerns; config-only change.
OSS growth 0 1 0 Quickstart table rendering is conversion-critical; merge promptly.
Doc writer 0 1 1 Deprecated gfm: true noted (deferred to Starlight upgrade); CHANGELOG nit folded.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 1 follow-up

  1. [Doc writer] Remove deprecated markdown.gfm: true from docs/astro.config.mjs when Starlight 0.40+ lands -- the gfm key is deprecated in current Starlight and will be removed in a future version; track the Starlight changelog and drop it in the version upgrade PR.

Recommendation

Panel stance: ship_now. The change is correct, minimal (+3/-0 in a single config file), and restores GFM table rendering that was visibly broken in the documentation site.


Folded in this run

  • (panel) CHANGELOG entry was missing for this fix -- resolved in fb75f2c (CHANGELOG.md +3 lines; no code changed).

Copilot signals reviewed

  • review 4587776360 (COMMENTED, PR overview summary) -- NOT-LEGIT: bot-generated PR summary with no specific findings; no action required.

Deferred (out-of-scope follow-ups)

These items were surfaced by the panel but cross the stated scope of this PR. Each one suggests a separate follow-up.

  • (panel) Remove deprecated markdown.gfm: true from docs/astro.config.mjs when Starlight 0.40+ lands -- scope boundary: requires a separate Starlight version upgrade (docs/package.json bump); out of scope for this GFM rendering fix.

Lint contract

uv run --extra dev ruff check src/ tests/ and
uv run --extra dev ruff format --check src/ tests/ both silent.

CI

All 14 required checks were green on original SHA 8a451e4 (pre-fold). The post-fold CI runs (SHA fb75f2c) require maintainer approval for fork workflow runs (GitHub fork security gate). The fold is CHANGELOG.md-only; no Python or logic changed. Lint pair verified silent locally (after 0 CI fix iterations).

Mergeability status

Captured from gh pr view 1944 --json mergeable,mergeStateStatus,statusCheckRollup immediately after the last push of this run (shepherd-driver step X.8).

PR head SHA CEO stance iters folds defers Copilot rounds CI mergeable mergeStateStatus notes
#1944 fb75f2c ship_now 1 1 1 1 yellow MERGEABLE BLOCKED Fork CI approval needed for post-fold SHA; pre-fold CI was all green.

Convergence

1 outer iteration(s); 1 Copilot round(s). Final panel verdict: ship_now.

Ready for maintainer review.


Full per-persona findings

Supply-chain security

No findings.

OSS growth

  • [recommended] Quickstart table rendering is conversion-critical.
    The quickstart landing page uses pipe-table content for the CLI feature comparison matrix. GFM rendering was broken without this fix; restoring it unblocks first-impressions for new visitors. Merge promptly.

Doc writer

  • [recommended] The gfm: true key in the markdown config object is deprecated in current Starlight (0.38.x).
    It remains the correct workaround until the Starlight 0.40+ upgrade is available; the build evidence is green. Deferred: remove this key in the Starlight version-upgrade PR.
  • [nit] CHANGELOG entry was missing for this fix.
    A CHANGELOG entry was added by the shepherd in commit fb75f2c.

Python architect -- inactive

Not activated: no Python files modified.

CLI logging expert -- inactive

Not activated: no CLI output or logging code modified.

DevX UX expert -- inactive

Not activated: no command surface or install flow modified.

Auth expert -- inactive

Not activated: no auth surface modified.

Test coverage expert -- inactive

Not activated: no behavioral code changed; no new test coverage needed.

Performance expert -- inactive

Not activated: no code path, resolver, or download phase changed.

This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.

Yuefeng Shi (syf2211) and others added 2 commits June 28, 2026 22:06
GFM tables were not rendering because remark-gfm was not enabled in the
Astro markdown config. Set markdown.gfm: true as the workaround for the
current Starlight version (0.38.x), per withastro/starlight#3934.

Fixes microsoft#1940
Adds the Keep-a-Changelog entry for the docs GFM rendering fix that
closes microsoft#1940. Addresses doc-writer panel follow-up: CHANGELOG entry
for this user-visible fix was missing from [Unreleased] > Fixed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator

Rebased onto current main at cdc0495 -> 3265ca0.

Conflicting paths resolved (faithful merge of both intents):

Lint contract: uv run --extra dev ruff check src/ tests/ and
uv run --extra dev ruff format --check src/ tests/ both silent post-rebase.

Post-push mergeability: gh pr view --json mergeStateStatus,mergeable
reports BLOCKED / MERGEABLE (BLOCKED = pending required review only). Push used
git push --force-with-lease=fix/docs-gfm-tables-rendering:fb75f2cbf958d360da8f0a8f1dde489e1c39e621 https://github.com/syf2211/apm.git HEAD:fix/docs-gfm-tables-rendering (--force-with-lease, never bare --force).

Ready for maintainer review.

@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit b09d07a into microsoft:main Jun 28, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tables not rendering in the docs

3 participants