feat(layouts): consolidate topic page layouts by myelinated-wackerow · Pull Request #18198 · ethereum/ethereum-org-website

myelinated-wackerow · 2026-05-15T11:36:46Z

Summary

Folds Staking, UseCases, Roadmap, and Upgrade markdown layouts into a single async server TopicLayout driven by per-topic config in src/data/topics/<key>.ts. Each section becomes a small config file (translation namespace, dropdown items, hero dimensions, edit banner) instead of a near-duplicate layout component. The four old layout files become MDX component bundles only and move to src/components/MdComponents/topics/.

Companion changes in the same PR:

Migrates 375 markdown files (15 EN + 360 translations across 24 locales) from summaryPoint1..4 to a single summaryPoints array; drops the dead emoji frontmatter field. Safe to land as a flat find-replace because none of the touched paths are ingested by the intl-pipeline yet (verified via .manifests/public/content/ check).
Hoists the Codeblock-wrapped Pre handler -- previously duplicated inline in Docs and Tutorial layouts -- into MdComponents.htmlElements as the site-wide default for fenced code blocks.

Behavior preservation

Dropdown labels, Matomo event names/categories, hero image dimensions, the edit banner (UseCases topic), and Staking's community callout are preserved verbatim. The community callout is passed as an afterContent slot prop by the slug router for template: staking pages.

Translatathon deprecation handled separately in chore(translatathon): deprecate pages, archive leaderboard #18197
AiAgents PR AI content updates #17994 rebases onto this
TopicLayout Storybook story deferred -- server-component getTranslations needs a request context that the project's storybook-next-intl setup doesn't provide; worth its own discussion

Test plan

/staking/, /staking/solo/, /staking/saas/, /staking/pools/, /staking/withdrawals/ render with the staking dropdown, hero, and the community callout below content
All /use-cases/ subpages render with the use-cases dropdown, hero, and the "edit this page" banner
/roadmap/security/, /roadmap/scaling/, /roadmap/user-experience/, /roadmap/future-proofing/ render with the roadmap dropdown
/roadmap/beacon-chain/ and /roadmap/merge/ (template: upgrade) render with the upgrade dropdown and show "page last updated: ..." under the summary list
Spot-check one non-English locale (e.g. /es/staking/solo/) -- dropdown labels translate
Spot-check one RTL locale (e.g. /ar/staking/solo/) -- layout is correctly mirrored
Pages with fenced code blocks (e.g. /developers/docs/getting-started/) still render with syntax highlighting and the copy-to-clipboard widget

🤖 Generated with Claude Code

Folds Staking, UseCases, Roadmap, and Upgrade into a single async server TopicLayout. Per-topic config (translation namespace, dropdown items, hero dimensions, edit banner) lives in src/data/topics/. Old layout files become MDX component bundles only and move to src/components/MdComponents/topics/. Consolidates the four per-section Frontmatter interfaces plus SummaryPointsNumbered into TopicFrontmatter, and deletes the now-unused getSummaryPoints helper. Behavior preserved: dropdown items, Matomo events, hero dimensions, edit banner (UseCases topic), Staking community callout (passed as afterContent slot by the slug router). Translatathon untouched; pending its redirect-to-/contributing deletion in a separate PR. See docs/topic-layout-refactor.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Rewrites summaryPoint1..4 frontmatter fields into a single summaryPoints array across 15 EN markdown files plus their on-disk translations (~360 files, 24 locales). Also drops the dead emoji frontmatter field, verified unused in any topic layout or hero component. Possible only because none of the touched paths were ingested by the intl-pipeline yet (.manifests/public/content/ check confirms no entries). The migration is a flat find-replace on EN + translations rather than a pipeline-coordinated change. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Hoists the Codeblock-wrapped Pre handler (previously duplicated inline in Docs and Tutorial layouts) into MdComponents.htmlElements as the site-wide default for fenced code blocks. Topic, Static, and other markdown-content layouts now get syntax highlighting and the copy-to-clipboard widget for free. Drops the duplicate inline definitions from src/layouts/Docs.tsx and src/layouts/Tutorial.tsx. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

netlify · 2026-05-15T11:36:55Z

✅ Deploy Preview for ethereumorg ready!

Name	Link
🔨 Latest commit	`c930c4c`
🔍 Latest deploy log	https://app.netlify.com/projects/ethereumorg/deploys/6a0c96ea53dd460008fb2892
😎 Deploy Preview	https://deploy-preview-18198.ethereum.it
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	7 paths audited Performance: 66 (🟢 up 2 from production) Accessibility: 95 (🔴 down 1 from production) Best Practices: 100 (🟢 up 1 from production) SEO: 98 (🔴 down 1 from production) PWA: 59 (no change from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

Adds the canonical-layouts reference and a top-level rule in the design-system skill so future agents reach for a TopicLayout config (src/data/topics/<key>.ts) before creating a new layout component. The default should be "configure, don't add new" for any page that fits the topic-hub-with-sub-nav pattern. - references/layouts.md: full inventory of the six canonical layouts (TopicLayout, StaticLayout, DocsLayout, TutorialLayout, ContentLayout, BaseLayout), worked example for adding a new topic, and the cases where a new layout is actually warranted. - SKILL.md: top rule #11 surfacing the guidance up front, plus a references-table entry pointing to layouts.md. - references/cleanup-playbook.md: "per-section layout -> TopicLayout config" entry with before/after, so agents auditing legacy code know the canonical replacement. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

pettinarip

@myelinated-wackerow great work overall!

pettinarip · 2026-05-18T14:33:33Z

  ...props
 }: ContentLayoutProps) => {
  return (
    <div {...props}>
+      {editBanner}


this is a parent implementation problem that should live here. This banner or whatever the parent want to render should probable be part of heroSection and keep the API clean. Small issue but leaves an unnecessary prop imo

Agree -- patched

pettinarip · 2026-05-18T14:34:09Z

+  "use-cases": TopicLayout,
+  staking: TopicLayout,
+  roadmap: TopicLayout,
+  upgrade: TopicLayout,


pettinarip · 2026-05-18T14:37:34Z

+  if (topicConfig) {
+    const afterContent =
+      layout === "staking" ? (
+        <StakingCommunityCallout className="my-16" />


sidecomment, we should probably need to think about a global callout component (in base layout perhaps) to be used for any page that needs something like this

Agree -- can separate this task

pettinarip · 2026-05-18T14:39:18Z

+            config={topicConfig}
+            afterContent={afterContent}
+          >
+            {content}


instead of adding a new prop afterContent we could just do

Suggested change

{content}

{content}

{afterContent}

Agree -- patched

pettinarip · 2026-05-18T14:42:26Z

+      },
+    ],
+  },
+  heroImage: { width: 1456, height: 816 },


I'd strip this heroImage data from here. This is a UI related data that the Layout knows better the size of the hero image to be displayed.

@pettinarip thanks for this... yeah this was faulty anyway—image sizes didn't necessarily match but also, it's not appropriate to apply to the full layout since the front matter dictates the actual image (where aspect ratios can/will vary).

Replaced with usage of sizeOf as a build-time image-size probe in compile.ts so next/image gets the correct aspect ratio for each -- similar to our blurDataURL -- Double check me that this will work with our setup, but I think that should do it.

(Commit: c930c4c)

ContentLayout no longer takes editBanner; TopicLayout bundles the banner and hero into a single heroSection fragment. TopicLayout no longer takes afterContent; the slug router passes the staking community callout as a sibling of the markdown content via children. Same render output, two fewer pass-through props. Addresses pettinarip review feedback on #18198. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

Probe each topic page's hero image with image-size at compile time and surface the intrinsic width/height on the frontmatter, replacing the hardcoded config.heroImage values. The previous config was silently feeding next/image the wrong aspect ratio on both upgrade pages (4000x2576 and 4964x4056 were both forced into a 5750x4332 box) and on /staking/withdrawals/ (800x613 forced into 800x605). Piggybacks on the existing fs.readFileSync the blurDataURL pipeline already does, so no new I/O surface. Addresses pettinarip review feedback on #18198. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-Authored-By: wackerow <54227730+wackerow@users.noreply.github.com>

myelinated-wackerow and others added 3 commits May 15, 2026 03:37

myelinated-wackerow requested review from pettinarip and wackerow as code owners May 15, 2026 11:36

github-actions Bot added content 🖋️ This involves copy additions or edits tooling 🔧 Changes related to tooling of the project translation 🌍 This is related to our Translation Program labels May 15, 2026

wackerow removed the translation 🌍 This is related to our Translation Program label May 15, 2026

github-actions Bot added the translation 🌍 This is related to our Translation Program label May 15, 2026

pettinarip reviewed May 18, 2026

View reviewed changes

myelinated-wackerow and others added 4 commits May 19, 2026 08:02

Merge branch 'dev' into feat/topic-layout-refactor

540aea8

patch: remove unavailable export

3545d00

pettinarip approved these changes May 20, 2026

View reviewed changes

pettinarip merged commit bf837c2 into dev May 20, 2026
27 checks passed

pettinarip deleted the feat/topic-layout-refactor branch May 20, 2026 08:52

claude Bot mentioned this pull request May 22, 2026

Deploy v11.7.0 #18258

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(layouts): consolidate topic page layouts#18198

feat(layouts): consolidate topic page layouts#18198
pettinarip merged 8 commits into
devfrom
feat/topic-layout-refactor

myelinated-wackerow commented May 15, 2026 •

edited by wackerow

Loading

Uh oh!

netlify Bot commented May 15, 2026 •

edited

Loading

Uh oh!

pettinarip left a comment

Uh oh!

pettinarip May 18, 2026

Uh oh!

wackerow May 20, 2026

Uh oh!

pettinarip May 18, 2026

Uh oh!

pettinarip May 18, 2026

Uh oh!

wackerow May 20, 2026

Uh oh!

pettinarip May 18, 2026

Uh oh!

wackerow May 20, 2026

Uh oh!

pettinarip May 18, 2026

Uh oh!

wackerow May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

myelinated-wackerow commented May 15, 2026 • edited by wackerow Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Behavior preservation

Related

Test plan

Uh oh!

netlify Bot commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ethereumorg ready!

Uh oh!

pettinarip left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

myelinated-wackerow commented May 15, 2026 •

edited by wackerow

Loading

netlify Bot commented May 15, 2026 •

edited

Loading