From 07cbd16a352f504fea3c34703be38cdc872fa5b4 Mon Sep 17 00:00:00 2001
From: Darius Cepulis <dcepulis@mux.com>
Date: Wed, 15 Jul 2026 12:47:08 -0700
Subject: [PATCH] fix(site): render changelog with shared MDX typography
 (#1846)

---
 .github/workflows/changelog-prose.yml         |  7 +-
 .github/workflows/release-pr.yml              |  6 +-
 site/CLAUDE.md                                |  6 +-
 site/src/content.config.ts                    |  8 +--
 .../{10.0.0-beta.1.md => 10.0.0-beta.1.mdx}   |  0
 .../{10.0.0-beta.10.md => 10.0.0-beta.10.mdx} |  0
 .../{10.0.0-beta.11.md => 10.0.0-beta.11.mdx} |  0
 .../{10.0.0-beta.12.md => 10.0.0-beta.12.mdx} |  0
 .../{10.0.0-beta.13.md => 10.0.0-beta.13.mdx} |  0
 .../{10.0.0-beta.14.md => 10.0.0-beta.14.mdx} |  0
 .../{10.0.0-beta.15.md => 10.0.0-beta.15.mdx} |  0
 .../{10.0.0-beta.16.md => 10.0.0-beta.16.mdx} |  0
 .../{10.0.0-beta.17.md => 10.0.0-beta.17.mdx} |  0
 .../{10.0.0-beta.18.md => 10.0.0-beta.18.mdx} |  0
 .../{10.0.0-beta.19.md => 10.0.0-beta.19.mdx} |  0
 .../{10.0.0-beta.2.md => 10.0.0-beta.2.mdx}   |  0
 .../{10.0.0-beta.20.md => 10.0.0-beta.20.mdx} |  0
 .../{10.0.0-beta.21.md => 10.0.0-beta.21.mdx} |  0
 .../{10.0.0-beta.22.md => 10.0.0-beta.22.mdx} |  0
 .../{10.0.0-beta.23.md => 10.0.0-beta.23.mdx} |  0
 .../{10.0.0-beta.24.md => 10.0.0-beta.24.mdx} |  0
 .../{10.0.0-beta.25.md => 10.0.0-beta.25.mdx} |  0
 .../{10.0.0-beta.3.md => 10.0.0-beta.3.mdx}   |  0
 .../{10.0.0-beta.4.md => 10.0.0-beta.4.mdx}   |  0
 .../{10.0.0-beta.5.md => 10.0.0-beta.5.mdx}   |  0
 .../{10.0.0-beta.6.md => 10.0.0-beta.6.mdx}   |  0
 .../{10.0.0-beta.7.md => 10.0.0-beta.7.mdx}   |  0
 .../{10.0.0-beta.8.md => 10.0.0-beta.8.mdx}   |  0
 .../{10.0.0-beta.9.md => 10.0.0-beta.9.mdx}   |  0
 site/src/pages/changelog/[...slug].astro      | 65 +------------------
 30 files changed, 18 insertions(+), 74 deletions(-)
 rename site/src/content/changelog/{10.0.0-beta.1.md => 10.0.0-beta.1.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.10.md => 10.0.0-beta.10.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.11.md => 10.0.0-beta.11.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.12.md => 10.0.0-beta.12.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.13.md => 10.0.0-beta.13.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.14.md => 10.0.0-beta.14.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.15.md => 10.0.0-beta.15.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.16.md => 10.0.0-beta.16.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.17.md => 10.0.0-beta.17.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.18.md => 10.0.0-beta.18.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.19.md => 10.0.0-beta.19.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.2.md => 10.0.0-beta.2.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.20.md => 10.0.0-beta.20.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.21.md => 10.0.0-beta.21.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.22.md => 10.0.0-beta.22.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.23.md => 10.0.0-beta.23.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.24.md => 10.0.0-beta.24.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.25.md => 10.0.0-beta.25.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.3.md => 10.0.0-beta.3.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.4.md => 10.0.0-beta.4.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.5.md => 10.0.0-beta.5.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.6.md => 10.0.0-beta.6.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.7.md => 10.0.0-beta.7.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.8.md => 10.0.0-beta.8.mdx} (100%)
 rename site/src/content/changelog/{10.0.0-beta.9.md => 10.0.0-beta.9.mdx} (100%)

diff --git a/.github/workflows/changelog-prose.yml b/.github/workflows/changelog-prose.yml
index b99c3f48..59de4d30 100644
--- a/.github/workflows/changelog-prose.yml
+++ b/.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:**
diff --git a/.github/workflows/release-pr.yml b/.github/workflows/release-pr.yml
index 187e5072..410bab48 100644
--- a/.github/workflows/release-pr.yml
+++ b/.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
           ---
diff --git a/site/CLAUDE.md b/site/CLAUDE.md
index 4bd29c36..de60717b 100644
--- a/site/CLAUDE.md
+++ b/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/`)
 
diff --git a/site/src/content.config.ts b/site/src/content.config.ts
index 9acb9e84..892df9c4 100644
--- a/site/src/content.config.ts
+++ b/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(),
diff --git a/site/src/content/changelog/10.0.0-beta.1.md b/site/src/content/changelog/10.0.0-beta.1.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.1.md
rename to site/src/content/changelog/10.0.0-beta.1.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.10.md b/site/src/content/changelog/10.0.0-beta.10.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.10.md
rename to site/src/content/changelog/10.0.0-beta.10.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.11.md b/site/src/content/changelog/10.0.0-beta.11.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.11.md
rename to site/src/content/changelog/10.0.0-beta.11.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.12.md b/site/src/content/changelog/10.0.0-beta.12.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.12.md
rename to site/src/content/changelog/10.0.0-beta.12.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.13.md b/site/src/content/changelog/10.0.0-beta.13.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.13.md
rename to site/src/content/changelog/10.0.0-beta.13.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.14.md b/site/src/content/changelog/10.0.0-beta.14.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.14.md
rename to site/src/content/changelog/10.0.0-beta.14.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.15.md b/site/src/content/changelog/10.0.0-beta.15.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.15.md
rename to site/src/content/changelog/10.0.0-beta.15.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.16.md b/site/src/content/changelog/10.0.0-beta.16.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.16.md
rename to site/src/content/changelog/10.0.0-beta.16.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.17.md b/site/src/content/changelog/10.0.0-beta.17.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.17.md
rename to site/src/content/changelog/10.0.0-beta.17.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.18.md b/site/src/content/changelog/10.0.0-beta.18.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.18.md
rename to site/src/content/changelog/10.0.0-beta.18.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.19.md b/site/src/content/changelog/10.0.0-beta.19.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.19.md
rename to site/src/content/changelog/10.0.0-beta.19.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.2.md b/site/src/content/changelog/10.0.0-beta.2.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.2.md
rename to site/src/content/changelog/10.0.0-beta.2.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.20.md b/site/src/content/changelog/10.0.0-beta.20.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.20.md
rename to site/src/content/changelog/10.0.0-beta.20.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.21.md b/site/src/content/changelog/10.0.0-beta.21.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.21.md
rename to site/src/content/changelog/10.0.0-beta.21.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.22.md b/site/src/content/changelog/10.0.0-beta.22.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.22.md
rename to site/src/content/changelog/10.0.0-beta.22.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.23.md b/site/src/content/changelog/10.0.0-beta.23.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.23.md
rename to site/src/content/changelog/10.0.0-beta.23.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.24.md b/site/src/content/changelog/10.0.0-beta.24.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.24.md
rename to site/src/content/changelog/10.0.0-beta.24.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.25.md b/site/src/content/changelog/10.0.0-beta.25.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.25.md
rename to site/src/content/changelog/10.0.0-beta.25.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.3.md b/site/src/content/changelog/10.0.0-beta.3.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.3.md
rename to site/src/content/changelog/10.0.0-beta.3.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.4.md b/site/src/content/changelog/10.0.0-beta.4.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.4.md
rename to site/src/content/changelog/10.0.0-beta.4.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.5.md b/site/src/content/changelog/10.0.0-beta.5.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.5.md
rename to site/src/content/changelog/10.0.0-beta.5.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.6.md b/site/src/content/changelog/10.0.0-beta.6.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.6.md
rename to site/src/content/changelog/10.0.0-beta.6.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.7.md b/site/src/content/changelog/10.0.0-beta.7.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.7.md
rename to site/src/content/changelog/10.0.0-beta.7.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.8.md b/site/src/content/changelog/10.0.0-beta.8.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.8.md
rename to site/src/content/changelog/10.0.0-beta.8.mdx
diff --git a/site/src/content/changelog/10.0.0-beta.9.md b/site/src/content/changelog/10.0.0-beta.9.mdx
similarity index 100%
rename from site/src/content/changelog/10.0.0-beta.9.md
rename to site/src/content/changelog/10.0.0-beta.9.mdx
diff --git a/site/src/pages/changelog/[...slug].astro b/site/src/pages/changelog/[...slug].astro
index add509d5..73dbfd0e 100644
--- a/site/src/pages/changelog/[...slug].astro
+++ b/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>