fix(docs): rename agents/*.md to .mdx so JSX components render#89
Merged
Conversation
Astro v2.0 removed legacy.astroFlavoredMarkdown — `import` statements
and JSX components (Card, CardGrid, LinkCard, Tabs) only render when
the file extension is `.mdx`. Verified against current
`@withastro/starlight` and `@withastro/docs` Context7 sources:
> Removed: `legacy.astroFlavoredMarkdown` — In v1.0, Astro moved the
> old Astro-Flavored Markdown to a legacy feature. Astro v2.0 removes
> it completely. Importing and using components in `.md` files will
> no longer work.
The 13 pages under `packages/docs/src/content/docs/agents/` were
authored with `import { Card, CardGrid, LinkCard } from
"@astrojs/starlight/components"` at the top — under `.md` Astro
silently dropped the JSX, so the live site rendered no editor cards
on /agents/, no setup grid on /agents/install/, no failure-mode cards
on /agents/why-mcp/, etc. Plain prose-only output.
Renamed all 13 to `.mdx` via `git mv`. The follow-on issue MDX
introduced was strict-parser fatal-on-bare-autolinks (`<https://...>`
is interpreted as a JSX tag). Six occurrences in `registries.mdx`
converted to standard `[text](url)` markdown link syntax.
Verified locally:
- `pnpm -F @opencodehub/docs build` -> 64 pages, all internal links
valid, llm-nav still patches the 63 sibling .md files astro emits
alongside the .html
- `curl http://localhost:4321/opencodehub/agents/` shows rendered
`sl-link-card` and `CardGrid` markup where the `<LinkCard>` /
`<CardGrid>` JSX expanded
Closed
theagenticguy
added a commit
that referenced
this pull request
May 10, 2026
## Summary Astro v2.0 removed `legacy.astroFlavoredMarkdown` — JSX components and `import` statements only render in `.mdx` files. The 13 pages under `packages/docs/src/content/docs/agents/` (shipped in PR #87) were authored as `.md` with `<Card>` / `<CardGrid>` / `<LinkCard>` JSX. Astro silently dropped the components and rendered prose-only. Verified against current Starlight + Astro docs via Context7: > Removed: `legacy.astroFlavoredMarkdown` — Astro v2.0 removes it completely. Importing and using components in `.md` files will no longer work. ## Fix - `git mv` all 13 `agents/**/*.md` → `*.mdx`. - 6 bare autolinks in `registries.mdx` (`<https://...>`) converted to standard `[text](url)` markdown — MDX is stricter than MD and treats `<https://...>` as a JSX tag. ## Verification - `pnpm -F @opencodehub/docs build` exits 0 — 64 pages built, all internal links valid, llm-nav still patches the 63 sibling `.md` files Astro emits alongside `.html` - `curl http://localhost:4321/opencodehub/agents/` shows rendered `sl-link-card` and `CardGrid` markup where the JSX expanded - The orphaned May-1 site at `https://theagenticguy.github.io/opencodehub/agents/` was the trigger — user reported `LinkCard` not loading. Confirmed in WebFetch that the live site previously rendered prose-only with no card grids. ## Test plan - [ ] CI green - [ ] After merge, Pages workflow re-deploys and `/agents/` shows the editor card grid + LinkCard navigation visible inline
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Astro v2.0 removed
legacy.astroFlavoredMarkdown— JSX components andimportstatements only render in.mdxfiles. The 13 pages underpackages/docs/src/content/docs/agents/(shipped in PR #87) were authored as.mdwith<Card>/<CardGrid>/<LinkCard>JSX. Astro silently dropped the components and rendered prose-only.Verified against current Starlight + Astro docs via Context7:
Fix
git mvall 13agents/**/*.md→*.mdx.registries.mdx(<https://...>) converted to standard[text](url)markdown — MDX is stricter than MD and treats<https://...>as a JSX tag.Verification
pnpm -F @opencodehub/docs buildexits 0 — 64 pages built, all internal links valid, llm-nav still patches the 63 sibling.mdfiles Astro emits alongside.htmlcurl http://localhost:4321/opencodehub/agents/shows renderedsl-link-cardandCardGridmarkup where the JSX expandedhttps://theagenticguy.github.io/opencodehub/agents/was the trigger — user reportedLinkCardnot loading. Confirmed in WebFetch that the live site previously rendered prose-only with no card grids.Test plan
/agents/shows the editor card grid + LinkCard navigation visible inline