Repository navigation
fix(docs): enable GFM table rendering in Starlight docs - #1944
Daniel Meppiel (danielmeppiel) merged 2 commits into
Conversation
|
@microsoft-github-policy-service agree |
There was a problem hiding this comment.
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
.mdxdocs content.
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>
APM Review Panel:
|
| 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
- [Doc writer] Remove deprecated
markdown.gfm: truefromdocs/astro.config.mjswhen Starlight 0.40+ lands -- thegfmkey 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: truefromdocs/astro.config.mjswhen 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: truekey in themarkdownconfig 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.
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>
fb75f2c to
3265ca0
Compare
|
Rebased onto current main at cdc0495 -> 3265ca0. Conflicting paths resolved (faithful merge of both intents):
Lint contract: Post-push mergeability: Ready for maintainer review. |
b09d07a
into
microsoft:main
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.gfmis no longer enabled by default.Changes
markdown: { gfm: true }todocs/astro.config.mjs.mdxcontent filesTests
cd docs && npm ci && npm run build— passed (122 pages built, all internal links valid)dist/quickstart/index.htmlnow contains a proper<table>element for the "What to commit" sectionNotes
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.