refactor: videos page revamp by wackerow · Pull Request #17870 · ethereum/ethereum-org-website

wackerow · 2026-03-27T00:54:35Z

Note: This is a draft preview PR with intent to extend PR:

Video gallery feature, watch pages, embeds, and data layer #17602

Summary

Refactors the video data architecture and page structure to align with site conventions.

Data layer

Moved all video metadata from videos.json into markdown frontmatter (index.md)
Renamed transcript.md to index.md for each video
Rewrote data layer to read from filesystem instead of JSON
Added VideoFrontmatter type, replaced old Video/VideoMeta/VideoWithMeta types
Deleted videos.json and videoTranscripts.ts (merged into videos.ts)
Added breadcrumb frontmatter to all 42 videos
Used shared stripMarkdown instead of duplicate stripMdx

Components and organization

Moved page-scoped components out of src/components/ into app/[locale]/videos/_components/
Inlined transcript accordion and markdown rendering directly into page.tsx
Moved VIDEO_CATEGORIES to colocated constants.ts, getVideosByCategory to utils.ts
Updated VideoWatch shared component for new data layer
Cleaned up unused i18n keys
Removed PR-added unit and e2e tests

SEO preserved

JSON-LD VideoObject schema on every video detail page
Transcript text stays in DOM when accordion is closed via forceMount
generateStaticParams pre-renders all video pages at build time
Per-video generateMetadata for title and description meta tags
Breadcrumbs with translatable labels
Sitemap inclusion for video pages
Semantic HTML structure

Preview links

Schema Markup Validator

Add VideoFrontmatter interface extending SharedFrontmatter with video-specific fields (youtubeId, uploadDate, duration, topic as string[], etc). Replace Video/VideoMeta/VideoWithMeta with VideoData and VideoCardData types. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename transcript.md to index.md for all 42 videos. Merge metadata from videos.json into YAML frontmatter (youtubeId, uploadDate, duration, educationLevel, topic as array, format, author, lang, breadcrumb). This consolidates the split data model into a single source of truth per video. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rewrite videos.ts to read video data from index.md frontmatter via readdir + gray-matter instead of videos.json. Delete videos.json and videoTranscripts.ts (logic merged into videos.ts). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add optional boolean parameter to preserve paragraph structure instead of collapsing all whitespace. Used by video JSON-LD transcript output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Update VideoWatch to use getVideoData and conditionally hide transcript link. Delete Transcript, TranscriptContent (inlined into page.tsx), VideoGalleryFilter (moved to _components/), and barrel export from src/components/Videos/. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add VideoGalleryFilter, constants.ts (VIDEO_CATEGORIES), and utils.ts (getVideosByCategory) under the /videos route. Update listing page to use filesystem-based getVideos() and colocated imports. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rewrite video detail page to use getVideoData with frontmatter, SimpleHero, Breadcrumbs, formatDate, renderSimpleMarkdown for transcript, and forceMount accordion for SEO. Update JSON-LD to accept VideoFrontmatter and use shared stripMarkdown. Update translation keys. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove PR-added Playwright test files for video utilities. These tested the old JSON-based data layer and are not needed for production. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove unused CSS classes from VideoWatch, delete e2e video tests from PR, and remove 5 unused i18n keys from page-videos.json. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

myelinated-wackerow · 2026-04-01T19:57:08Z

Review cleanup

Performance

Static generation for all 25 locales (was English-only; non-English was SSR on-demand)
Sitemap updated with all locale variants and hreflang alternates
String comparison for date sorting (YYYY-MM-DD is lexicographic; avoids Date object churn)
JSON-LD ItemList sorted by newest before slice, matching default page display

Dead code removed

getTranscript(), getVideoMeta() -- exported but never called
minVideos on every category -- defined, typed, never read
4 unused fields trimmed from VideoCardData client serialization (youtubeId, educationLevel, format, author) -- full data still available server-side via VideoFrontmatter

DRY / cleanup

Shared cached getVideoSlugs() eliminates duplicate readdir calls
Removed unnecessary cn() wrapping static class strings
Fixed SimpleHero import to use barrel export
Renamed view-transcript key to page-videos-view-transcript for prefix consistency
Removed redundant .trim() check on transcript

Reviewed by Claude Opus 4.6

wackerow · 2026-04-02T01:25:21Z

@pettinarip Wouldn't merge this without checking with @mnelsonBT but marking it for code review

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Extract escapeHeadingIds to shared module and add remark-heading-id plugin to renderSimpleMarkdown so video transcripts can use {#custom-header-ids}. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Replaces `sddefault` (640x480) which is not guaranteed to exist Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

wackerow · 2026-04-09T19:46:34Z

src/lib/md/renderSimple.tsx

@@ -1,8 +1,10 @@
 import { compileMDX, type MDXRemoteProps } from "next-mdx-remote/rsc"
 import remarkGfm from "remark-gfm"
+import remarkHeadingId from "remark-heading-id"


markdownlint enforcing header ID's on all content -- This enables proper parsing when using renderSimple approach. Compatible for even simpler markdown where these ID's won't be present (e.g., externally fetched data)

wackerow · 2026-04-09T19:46:57Z

src/lib/nav/buildNavigation.ts

+          label: t("nav-videos-label"),
+          description: t("nav-videos-description"),


Reminder note: These need translations

wackerow · 2026-04-09T19:49:07Z

src/lib/utils/videos.ts

+/**
+ * Default YouTube thumbnail URL derived from a video ID.
+ * Returns hqdefault (480x360) which is guaranteed to exist.
+ */
+export function getDefaultThumbnailUrl(youtubeId: string): string {
+  return `https://img.youtube.com/vi/${youtubeId}/hqdefault.jpg`
+}


sddefault.jpg not always available (higher resolution)

Using hq version for now which is guaranteed to be available from YT

Conditionally rendering sd if available requires several sequential fetches during build -- avoided

Future Trigger.dev task could load highest-quality image to s3 bucket so we can point to that instead

wackerow · 2026-04-09T19:49:53Z

src/components/ui/card.tsx

  {
    variants: {
      variant: {
+        semibold: "text-lg font-semibold",


Small addition here in lieu of hard-coding this styling into where the card is consumed

wackerow · 2026-04-09T19:50:39Z

src/lib/md/compile.ts

-// Preprocess the markdown content
-function preprocessMarkdown(content: string) {
-  // Replace heading IDs without escaping to escaped version
-  // TODO: move to a separate file and test it more
-  return content.replace(/^(#{1,6}.*?)\{(#[\w-]+)\}/gm, "$1\\{$2\\}")
-}
-


Shared -- abstracted to @/lib/md/escapeHeadingIds and renamed

wackerow · 2026-04-09T19:52:37Z

src/lib/interfaces.ts

+  youtubeId: string
+  uploadDate: string
+  duration: string
+  educationLevel: "beginner" | "intermediate" | "advanced"


(Some of these are used for JSONLD and not rendered)

wackerow · 2026-04-09T19:53:18Z

next.config.js

        { protocol: "https", hostname: "cdn.charmverse.io" },
        { protocol: "https", hostname: "ethwingman.com" },
        { protocol: "https", hostname: "eth-mcp.dev" },
+        { protocol: "https", hostname: "img.youtube.com", pathname: "/vi/**" },


If/when we implement Trigger.dev/s3 bucket handling for these, we could remove this

mnelsonBT and others added 30 commits March 26, 2026 15:37

Add agent context schemas

a9b76cc

video gallery feature

cc37857

adding real transcripts

0b9612e

editing transcripts

e9a852e

editing video descriptions

73c4ac2

editing page headings

abfc865

fixing curly brackets

459ef36

embedding remaining videos

89ebf00

reducing caption length

f53a55f

updating accordian for SEO

df7dbde

transcript format tweak

959d6de

updating page subtitle

93da4d0

remove context files and revert next.config.js

b662eaa

refactor: use breadcrumb molecule component

ef36f3d

refactor: use ui/card component, server-side

4ec6660

refactor: use ui/section, add sr-only h2

47a7924

adding StartTime and pulling in site videos

56acfc2

adding transcripts

16c7225

text to markdown

7c51fb9

removing category shelves from landing

56b7938

adding new videos

820ad7d

refactor: filesystem-based video data layer

4c8d3dd

Rewrite videos.ts to read video data from index.md frontmatter via readdir + gray-matter instead of videos.json. Delete videos.json and videoTranscripts.ts (logic merged into videos.ts). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: add preserveNewlines to stripMarkdown

d4c2012

Add optional boolean parameter to preserve paragraph structure instead of collapsing all whitespace. Used by video JSON-LD transcript output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: remove video unit tests

0913d74

Remove PR-added Playwright test files for video utilities. These tested the old JSON-based data layer and are not needed for production. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: audit cleanup

fed337b

Remove unused CSS classes from VideoWatch, delete e2e video tests from PR, and remove 5 unused i18n keys from page-videos.json. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge branch 'dev' into pr-17870-videos-static

025a4fd

wackerow marked this pull request as ready for review April 2, 2026 01:25

wackerow requested review from minimalsm and pettinarip as code owners April 2, 2026 01:25

mnelsonBT added 2 commits April 6, 2026 16:13

adding video documentation

468e014

fixing gallery category constants

098d5c1

github-actions bot added the documentation 📖 Change or add documentation label Apr 6, 2026

wackerow and others added 20 commits April 6, 2026 17:37

docs: sync video tag reference with constants

32d55c6

docs: clarify category key tag requirement

2ce29d0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

adding trailing videos

9fde07f

transcript copyedits

8302b72

feat: add video counts to category filter tags

6959b0c

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

fixing transcripts

d4f15f2

patch: EthBoulder 2026 year

cc04d48

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Merge branch 'dev' into videos-refactor

0999214

feat: add remark-heading-id to simple MD renderer

a819c09

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

chore: apply custom header IDs to video transcripts

e09a41e

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

fix(refactor): getTranslations string argument

77075d1

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

revert: crowdin-translation-guide video

a1e2ef3

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

fix: use hqdefault (480x360) thumbnail

ecbb782

Replaces `sddefault` (640x480) which is not guaranteed to exist Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

feat(ui): move h1 below image

5fc5f14

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

feat(ui): add timer, align breadcrumb position

542e27c

Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Merge branch 'dev' into videos-refactor

9cd91e2

feat(ui): semibold CardTitle variant

f6d09f9

feat(ui): use ui/card for VideoWatch

03885af

feat: pass className to VideoWatch

e33ef78

wackerow commented Apr 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: videos page revamp#17870

refactor: videos page revamp#17870
wackerow wants to merge 64 commits intodevfrom
videos-refactor

wackerow commented Mar 27, 2026 •

edited

Loading

Uh oh!

myelinated-wackerow commented Apr 1, 2026

Uh oh!

wackerow commented Apr 2, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

wackerow Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		label: t("nav-videos-label"),
		description: t("nav-videos-description"),

Conversation

wackerow commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Data layer

Components and organization

SEO preserved

Preview links

Uh oh!

myelinated-wackerow commented Apr 1, 2026

Review cleanup

Uh oh!

wackerow commented Apr 2, 2026

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

wackerow Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wackerow commented Mar 27, 2026 •

edited

Loading