fix(site): render changelog with shared MDX typography (#1846)

.github/workflows/changelog-prose.yml

@@ -75,7 +75,7 @@ jobs:
       - name: Guard — check raw changelog exists
         id: guard
         run: |
-          FILE="site/src/content/changelog/${{ steps.version.outputs.version }}.md"
+          FILE="site/src/content/changelog/${{ steps.version.outputs.version }}.mdx"
           if [ ! -f "$FILE" ]; then
             echo "::warning::Raw changelog file $FILE not found on main — skipping prose generation"
             echo "skip=true" >> "$GITHUB_OUTPUT"
@@ -103,8 +103,8 @@ jobs:
 
             1. **Load context:**
                - Read `.claude/skills/docs/references/writing-style.md` for tone and style rules.
-               - Read the raw changelog at `site/src/content/changelog/${{ steps.version.outputs.version }}.md`.
-               - Read other existing `.md` files in `site/src/content/changelog/` (if any) to match their tone and format.
+               - Read the raw changelog at `site/src/content/changelog/${{ steps.version.outputs.version }}.mdx`.
+               - Read other existing `.mdx` files in `site/src/content/changelog/` (if any) to match their tone and format.
                - List the available docs pages so you can link them: `ls site/src/content/docs/concepts site/src/content/docs/how-to site/src/content/docs/reference`. A page's slug is its path under `site/src/content/docs/` without the extension (e.g. `reference/menu.mdx` → `reference/menu`).
 
             2. **Gather PR context:**
@@ -140,6 +140,7 @@ jobs:
                - Omit features reverted before this release. If a PR appears alongside a revert of it (the raw file's Revert section, or a revert commit in the range), it did not ship — leave it out entirely.
                - Summarize smaller fixes briefly, grouped. Skip internal-only changes (CI, tooling, changelog maintenance) — unless the release is entirely internal, in which case describe it honestly in a sentence or two rather than leaving the body empty.
                - If the raw file has a "New Contributors" section, remove it and end with one sentence thanking first-time contributors by name, linking their GitHub profiles.
+               - Keep the result valid MDX: put code-like text containing `<`, `>`, `{`, or `}` in backticks, and escape those characters in ordinary prose.
                - Follow `writing-style.md` strictly. Do not fabricate — stick to what the PRs actually say.
 
             4. **Write the `description` field:**

.github/workflows/release-pr.yml

@@ -65,6 +65,10 @@ jobs:
             BODY=$(tail -n +"$((LINE_NUM + 1))" CHANGELOG.md)
           fi
 
+          # Commit titles are untrusted MDX input. Escape JSX/expression
+          # delimiters outside inline code spans while preserving their output.
+          BODY=$(printf '%s\n' "$BODY" | perl -pe 's{(`[^`]*`)(*SKIP)(*F)|([<>{}])}{\\$2}g')
+
           # Determine prerelease and breaking
           PRERELEASE=false
           if echo "$VERSION" | grep -q '-'; then
@@ -80,7 +84,7 @@ jobs:
           COMPARE_URL=$(grep -Fm1 "[@videojs/core@${VERSION}]: " CHANGELOG.md | sed 's/.*]: //' || true)
 
           # Write the site changelog file
-          OUTFILE="site/src/content/changelog/${VERSION}.md"
+          OUTFILE="site/src/content/changelog/${VERSION}.mdx"
           mkdir -p "$(dirname "$OUTFILE")"
           cat > "$OUTFILE" <<EOF
           ---

site/CLAUDE.md

@@ -466,9 +466,9 @@ Without a manual override, `Base.astro` derives `/og/{slug}.png` and `/og/twitte
 
 ### Changelog Collection (`src/content/changelog/`)
 
-**Exception to the MDX-only rule:** changelog entries are plain `.md` files generated by CI (the release workflow writes raw git-cliff bullets; the changelog-prose workflow rewrites them into prose). Generated content never contains components, and `.md` is robust against PR titles that would break MDX parsing (`<`, `{`).
+Changelog entries are `.mdx` files generated by CI: the release workflow writes raw git-cliff bullets, then the changelog-prose workflow rewrites them into prose. Literal MDX syntax in generated text (`<`, `>`, `{`, or `}`) must be put in backticks or escaped.
 
-**Filename convention:** `{version}.md` (e.g. `10.0.0-beta.24.md`) — the filename is the entry id and URL slug: `/changelog/10.0.0-beta.24/`.
+**Filename convention:** `{version}.mdx` (e.g. `10.0.0-beta.24.mdx`) — the filename is the entry id and URL slug: `/changelog/10.0.0-beta.24/`.
 
 **Schema:**
 ```ts
@@ -482,7 +482,7 @@ Without a manual override, `Base.astro` derives `/og/{slug}.png` and `/og/twitte
 }
 ```
 
-**Rendering caveat:** Astro's `components` prop on `<Content />` is MDX-only, so the typography components don't apply to changelog bodies. `src/pages/changelog/[...slug].astro` mirrors their styles in a scoped `<style>` block — keep it in sync with `src/components/typography/`.
+Changelog bodies use the same `defaultMarkdownComponents` mapping as blog posts, so their Markdown typography stays identical.
 
 ### Docs Collection (`src/content/docs/`)
 

site/src/content.config.ts

@@ -97,13 +97,13 @@ const docs = defineCollection({
 });
 
 // Release notes generated by the release workflow (raw git-cliff bullets),
-// then rewritten into prose by the changelog-prose workflow. Plain `.md` —
-// generated content never contains components. Filename is the version.
+// then rewritten into prose by the changelog-prose workflow. MDX lets the
+// changelog use the same typography component mapping as the blog.
 const changelog = defineCollection({
   loader: glob({
     base: './src/content/changelog',
-    pattern: '*.md',
-    generateId: ({ entry }) => entry.replace(/\.md$/, ''),
+    pattern: '*.mdx',
+    generateId: ({ entry }) => entry.replace(/\.mdx$/, ''),
   }),
   schema: z.object({
     description: z.string(),

site/src/pages/changelog/[...slug].astro

@@ -4,6 +4,7 @@ import type { CollectionEntry } from 'astro:content';
 import { getCollection, render } from 'astro:content';
 import { ArrowUpRight } from 'lucide-react';
 import FormattedDate from '@/components/FormattedDate.astro';
+import defaultMarkdownComponents from '@/components/typography/defaultMarkdownComponents';
 import Blog from '@/layouts/Blog.astro';
 
 export async function getStaticPaths() {
@@ -60,68 +61,6 @@ const description =
         Compare changes on GitHub <ArrowUpRight size="1em" aria-hidden="true" />
       </a>
     </header>
-    <div class="changelog-content mx-auto max-w-3xl">
-      <Content />
-    </div>
+    <Content components={{ ...defaultMarkdownComponents }} />
   </article>
 </Blog>
-
-{
-  /*
-  Changelog entries are plain `.md` (generated by CI), and Astro's `components`
-  prop on <Content /> is MDX-only — so the typography components in
-  `@/components/typography` can't be applied here. Mirror their classes instead;
-  keep in sync with that directory and `typography/styles.ts`.
-*/
-}
-<style>
-  @reference "../../styles/globals.css";
-
-  .changelog-content :global(h2) {
-    @apply mt-16 mb-8 font-display text-h3 leading-tight uppercase @lg:text-h25;
-  }
-
-  .changelog-content :global(h3) {
-    @apply my-8 font-display text-h3 leading-tight;
-  }
-
-  .changelog-content :global(h4) {
-    @apply mt-8 mb-4 text-p15 font-bold;
-  }
-
-  .changelog-content :global(p) {
-    @apply my-4;
-  }
-
-  .changelog-content :global(ul) {
-    @apply mb-4 list-outside list-disc pl-4;
-  }
-
-  .changelog-content :global(ol) {
-    @apply mb-4 list-outside list-decimal pl-4;
-  }
-
-  .changelog-content :global(li + li) {
-    @apply mt-1;
-  }
-
-  .changelog-content :global(a) {
-    @apply underline intent:decoration-gold;
-  }
-
-  .changelog-content :global(strong) {
-    @apply font-bold;
-  }
-
-  .changelog-content :global(em) {
-    @apply italic;
-  }
-
-  .changelog-content :global(code) {
-    @apply rounded border border-manila-75 bg-manila-25 px-1 font-mono text-code break-words normal-case dark:border-warm-gray dark:bg-soot;
-  }
-
-  .changelog-content :global(hr) {
-    @apply my-8 border-t border-manila-75 dark:border-warm-gray;
-  }
-</style>