refactor(home page): split components up to make the content more in markdown

Author: flippedcoder

COMPONENT_REGISTRY.md

@@ -2,40 +2,49 @@
 
 Generated by `scripts/audit-components.mjs`. Run to update.
 
-**Coverage: 28/33 (85%)**
+**Coverage: 34/40 (85%)**
 
 | Component | File Count | Strategy | Covered |
 |-----------|------------|----------|---------|
-| `TabItem` | 44 | `tabitem` | ✅ |
-| `Tabs` | 43 | `tabs` | ✅ |
-| `ReleaseNoteHeader` | 41 | `release-note-header` | ✅ |
+| `TabItem` | 79 | `tabitem` | ✅ |
+| `Tabs` | 78 | `tabs` | ✅ |
+| `NoZoom` | 60 | `UNKNOWN` | ❌ |
+| `ReleaseNoteHeader` | 48 | `release-note-header` | ✅ |
 | `ViewSourceCodeNotice` | 24 | `view-source-code-notice` | ✅ |
 | `RelatedReadContainer` | 23 | `related-read-container` | ✅ |
 | `RelatedReadItem` | 20 | `related-read-item` | ✅ |
 | `SetupSteps` | 14 | `setup-steps` | ✅ |
 | `SetupStep` | 14 | `setup-step` | ✅ |
 | `CodeSnippet` | 14 | `code-snippet` | ✅ |
+| `PatternCards` | 13 | `cards` | ✅ |
 | `SdkTabs` | 8 | `sdk-tabs` | ✅ |
 | `CallToAction` | 8 | `call-to-action` | ✅ |
 | `CaptionedImage` | 7 | `captioned-image` | ✅ |
-| `IntegrationsGrid` | 5 | `integrations-grid` | ✅ |
+| `IntegrationsGrid` | 6 | `integrations-grid` | ✅ |
 | `ToolTipTerm` | 4 | `tooltip-term` | ✅ |
 | `JsonTable` | 3 | `json-table` | ✅ |
 | `AWSRegions` | 2 | `transclude` | ✅ |
 | `GCPRegions` | 2 | `transclude` | ✅ |
-| `PatternCards` | 2 | `cards` | ✅ |
 | `CustomRolePermissionsTable` | 1 | `transclude` | ✅ |
 | `InvitationContent` | 1 | `strip-block` | ✅ |
 | `RetrySimulator` | 1 | `strip-block` | ✅ |
+| `ServerlessWorkerDemo` | 1 | `strip-block` | ✅ |
+| `StandaloneActivityDemo` | 1 | `UNKNOWN` | ❌ |
 | `SayHelloWorkflow` | 1 | `UNKNOWN` | ❌ |
 | `ISayHelloNexusService` | 1 | `UNKNOWN` | ❌ |
 | `CallerWorkflow` | 1 | `UNKNOWN` | ❌ |
-| `StandaloneActivityDemo` | 1 | `UNKNOWN` | ❌ |
-| `SdkSvg` | 1 | `strip-block` | ✅ |
-| `SdkGuideLinks` | 1 | `UNKNOWN` | ❌ |
-| `ServerlessWorkerDemo` | 1 | `strip-block` | ✅ |
+| `SdkGuideLinks` | 1 | `sdk-guide-links` | ✅ |
 | `CloudRegionCount` | 1 | `strip-block` | ✅ |
-| `HomePageHero` | 1 | `home-page-hero` | ✅ |
+| `GuidesGrid` | 1 | `UNKNOWN` | ❌ |
+| `HeroWrapper` | 1 | `strip-tag` | ✅ |
+| `HeroHeader` | 1 | `strip-tag` | ✅ |
+| `HeroSection` | 1 | `strip-tag` | ✅ |
+| `HeroContent` | 1 | `strip-tag` | ✅ |
+| `HeroCta` | 1 | `strip-tag` | ✅ |
+| `HeroActions` | 1 | `strip-tag` | ✅ |
+| `ActionCard` | 1 | `hero-card` | ✅ |
+| `CommunityCards` | 1 | `strip-tag` | ✅ |
+| `CommunityCard` | 1 | `hero-card` | ✅ |
 | `OperationsTable` | 1 | `strip-block` | ✅ |
 
 ## Strategy Definitions

MARKDOWN_PIPELINE.md

@@ -69,7 +69,7 @@ docusaurus-plugin-llms ───────────────────
 | `scripts/mdx-to-md.mjs` | **The transformer.** Exports `transformMdx()` + parsing helpers and `COMPONENT_REGISTRY`. Zero-dependency ES module. |
 | `scripts/component-handlers/data-tables.mjs` | Handler for `<JsonTable>` — resolves a `static/json/*.json` file into a Markdown table. |
 | `scripts/component-handlers/integrations.mjs` | Handler for `<IntegrationsGrid>` — reads `src/components/IntegrationsGrid/integrations-data.json`, filters by the `defaultSdks` prop, and emits a Markdown list. |
-| `scripts/component-handlers/home-page-hero.mjs` | Handler for `<HomePageHero>` — emits the homepage hero's headline, intro, and link cards. Content is mirrored from the component (no shared data file). |
+| `scripts/component-handlers/hero.mjs` | Handler for the homepage hero cards (`<ActionCard>` / `<CommunityCard>`) — parses `title`/`href` props and children into a Markdown link-list item. Copy lives in `docs/index.mdx`; layout wrappers strip generically. |
 | `scripts/component-handlers/cards.mjs` | Handler for `<QuickstartCards>` / `<PatternCards>` — parses the inline `items={[{href,title,description}]}` prop into a Markdown link list. |
 | `scripts/audit-components.mjs` | Inventory/coverage tool. Scans all docs, reports per-component coverage, writes `COMPONENT_REGISTRY.md` at the repo root. |
 | `src/components/LLMActions/LLMActions.tsx` | On-page actions (Copy, View as Markdown, Open in ChatGPT/Claude). Points at the generated `/<path>.md` (not the raw MDX). |
@@ -118,7 +118,8 @@ Each component maps to a strategy in `COMPONENT_REGISTRY` (in `scripts/mdx-to-md
 | `SetupSteps` / `SetupStep` | `setup-steps` / `setup-step` | Prose children plus code extracted from the `code={…}` JSX prop |
 | `JsonTable` | `json-table` | Markdown table resolved from the referenced `static/json/*.json` |
 | `IntegrationsGrid` | `integrations-grid` | Markdown list resolved from `integrations-data.json`, filtered by the `defaultSdks` prop |
-| `HomePageHero` | `home-page-hero` | Homepage hero's headline, intro paragraphs, and link cards (content mirrored from the component) |
+| `ActionCard` / `CommunityCard` | `hero-card` | Homepage hero cards → `- [title](href): description` link-list item (copy authored in `docs/index.mdx`) |
+| `HeroWrapper`, `HeroHeader`, `HeroSection`, `HeroContent`, `HeroActions`, `HeroCta`, `CommunityCards` | `strip-tag` | Homepage hero layout wrappers — stripped to their inner Markdown (headline + intro prose) |
 | `QuickstartCards`, `PatternCards` | `cards` | Markdown link list parsed from the inline `items={[{href,title,description}]}` prop |
 | `ZoomPanPinch` | `transparent` | Wrapper stripped; inner content passed through |
 | `DocCardList`, `CardList`, `LandingCard`, `ThemedImage`, `SdkSvg`, `CloudRegionCount`, `RetrySimulator`, `ServerlessWorkerDemo`, `OperationsTable`, `InvitationContent` | `strip-block` | Removed entirely (visual/dynamic, no extractable text) |
@@ -144,24 +145,19 @@ transformer itself is safe from these — its detection is anchored to whole lin
 4. Run `node scripts/audit-components.mjs` to refresh coverage.
 
 **Keep handlers and components in sync.** When a handler reproduces content or logic that also
-lives in the React component (data-driven components like `JsonTable`, `IntegrationsGrid`, or the
-content-mirroring `HomePageHero`), add a cross-reference comment in *both* files — a `⚠️ LLM
-MARKDOWN PIPELINE` comment in the component pointing at the handler, and a `Component:` line in
-the handler pointing back — so a future change to one prompts updating the other. Components
-transformed generically (e.g. `Tabs`, `CallToAction`) have no separate source of truth and don't
-need this.
+lives in the React component (data-driven components like `JsonTable` or `IntegrationsGrid`), add
+a cross-reference comment in *both* files — a `⚠️ LLM MARKDOWN PIPELINE` comment in the component
+pointing at the handler, and a `Component:` line in the handler pointing back — so a future change
+to one prompts updating the other. Components transformed generically (e.g. `Tabs`,
+`CallToAction`, and the homepage hero cards) have no separate source of truth and don't need this
+— the copy lives in the MDX and the handler reads it straight from the page.
 
 ### Known limitation: content/logic duplicated between components and handlers (follow-up)
 
 A few handlers currently re-express something that also lives in the React component, which
 means two places to keep in sync. This is a known issue to be addressed in a follow-up; the
 cross-reference comments above are an interim guard, not the fix.
 
-- **`HomePageHero` — duplicated content.** `scripts/component-handlers/home-page-hero.mjs` holds
-  its own copy of the homepage hero's text (headline, intro paragraphs, action/community cards),
-  duplicating `src/components/elements/HomePageHero.js`. The intended fix is to move that content
-  into the page's source of truth — `docs/index.mdx` — and reduce the component to presentation
-  (content via props/children), so the hero-specific handler can be removed entirely.
 - **`IntegrationsGrid` — duplicated logic.** The data is already shared
   (`integrations-data.json`), but the default-view filter/sort in
   `scripts/component-handlers/integrations.mjs` (`selectIntegrations`) mirrors the filtering in

docs/index.mdx

@@ -7,6 +7,50 @@ hide_title: true
 description: Official docs for Temporal, the open source Durable Execution platform for crash-proof applications. Guides, SDKs, and references for reliable workflows.
 ---
 
-import HomePageHero from '@site/src/components/elements/HomePageHero';
+import {
+  HeroWrapper,
+  HeroHeader,
+  HeroSection,
+  HeroContent,
+  HeroHeadline,
+  HeroActions,
+  HeroCta,
+  ActionCard,
+  CommunityCards,
+  CommunityCard,
+} from '@site/src/components';
 
-<HomePageHero />
+<HeroWrapper>
+
+<HeroHeader>Temporal Docs</HeroHeader>
+
+<HeroSection>
+
+<HeroContent>
+
+<HeroHeadline>Build applications that never fail</HeroHeadline>
+
+Temporal is an open-source platform for building reliable applications. Temporal delivers crash-proof execution by guaranteeing that applications resume exactly where they left off after crashes, network failures, or infrastructure outages, whether that happens seconds, days, or even years later.
+
+Temporal enables developers to focus on building features that drive the business while ensuring that mission-critical processes such as order fulfillment, customer onboarding, and payment processing never fail or disappear, regardless of what goes wrong.
+
+<HeroCta href="/quickstarts">Quickstart</HeroCta>
+
+</HeroContent>
+
+<HeroActions>
+  <ActionCard href="/quickstarts" icon="bolt" iconAlt="Lightning icon" title="Quickstart">Setup your local and run a Hello World workflow.</ActionCard>
+  <ActionCard href="/develop" icon="code" iconAlt="Code icon" title="Developer Guide">Dive into everything you need to know about building Temporal workflows.</ActionCard>
+  <ActionCard href="/production-deployment" icon="rocket" iconAlt="Rocket icon" title="Deploy your Workflows">Deploy your Temporal Application to your environment. Self-Host the Temporal Service or use Temporal Cloud.</ActionCard>
+  <ActionCard href="https://temporal.io/cloud" icon="cloud" iconAlt="Cloud icon" title="Get started for free with $1000 in credits"><span className="linkify">Sign up for Temporal Cloud</span> and let us host the Temporal Service for you.</ActionCard>
+</HeroActions>
+
+</HeroSection>
+
+<CommunityCards>
+  <CommunityCard href="https://temporal.io/slack" icon="slack" iconAlt="Slack" title="Slack Community">Join us on <a href="https://temporal.io/slack">temporal.io/slack</a> and say hi or ask us a question.</CommunityCard>
+  <CommunityCard href="https://community.temporal.io" icon="forum" iconAlt="Message" title="Developer Forum"><a href="https://community.temporal.io">Find out</a> if your question has already been asked.</CommunityCard>
+  <CommunityCard href="https://learn.temporal.io/courses/" icon="learn" iconAlt="Education" title="Learn it all"><a href="https://learn.temporal.io/courses/">Master Temporal</a> with our courses and tutorials.</CommunityCard>
+</CommunityCards>
+
+</HeroWrapper>

scripts/component-handlers/hero.mjs

@@ -0,0 +1,77 @@
+/**
+ * component-handlers/hero.mjs
+ *
+ * Handler for the homepage hero cards (<ActionCard> / <CommunityCard>) used in
+ * docs/index.mdx and rendered by src/components/elements/HomePageHero.js.
+ *
+ * The copy lives in the MDX itself: `title` and `href` are props on the tag and
+ * the description is the element's children (which may contain inline links or
+ * <span> markup). This handler parses one card element into a Markdown link-list
+ * item: `- [title](href): description`.
+ *
+ * The layout wrappers (HeroWrapper, HeroSection, HeroContent, …) are handled by
+ * the transformer's generic `strip-tag` strategy — they carry no copy of their
+ * own, so there is nothing to resolve here.
+ */
+
+/** Read a `name="..."`, `name='...'`, or `name={"..."}` prop from a tag string. */
+function getProp(tagStr, name) {
+  const m =
+    tagStr.match(new RegExp(`${name}=["']([^"']*)["']`)) ||
+    tagStr.match(new RegExp(`${name}=\\{["'\`]([^"'\`]*)["'\`]\\}`));
+  return m ? m[1] : "";
+}
+
+/** Convert the inline children markup to plain Markdown. */
+function cleanInline(s) {
+  return s
+    // <a href="X">Y</a> → [Y](X)
+    .replace(/<a\s+[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)")
+    // drop any remaining inline HTML tags (e.g. <span class="linkify">)
+    .replace(/<\/?[a-z][^>]*>/gi, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Parse a single hero card element string into its parts.
+ * @param {string} elementStr e.g. `<ActionCard href="/x" title="Y">desc</ActionCard>`
+ * @returns {{href: string, title: string, description: string}}
+ */
+export function parseHeroCard(elementStr) {
+  const openEnd = elementStr.indexOf(">");
+  const closeStart = elementStr.lastIndexOf("</");
+  const openTag = elementStr.slice(0, openEnd + 1);
+  const inner = openEnd >= 0 && closeStart > openEnd ? elementStr.slice(openEnd + 1, closeStart) : "";
+  return {
+    href: getProp(openTag, "href"),
+    title: getProp(openTag, "title"),
+    description: cleanInline(inner),
+  };
+}
+
+/**
+ * Resolve a <HeroHeadline>…</HeroHeadline> element to a Markdown H1.
+ * The homepage headline is a React-rendered <h1> (not a Markdown `#`) so it
+ * skips the theme's h1 override; here we restore it as a heading for the .md.
+ * @returns {string} `# text` (empty string if no text)
+ */
+export function heroHeadlineToMarkdown(elementStr) {
+  const openEnd = elementStr.indexOf(">");
+  const closeStart = elementStr.lastIndexOf("</");
+  const text = openEnd >= 0 && closeStart > openEnd ? cleanInline(elementStr.slice(openEnd + 1, closeStart)) : "";
+  return text ? `# ${text}` : "";
+}
+
+/**
+ * Resolve a hero card element to a Markdown link-list item.
+ * @returns {string} `- [title](href): description` (empty string if no content)
+ */
+export function heroCardToMarkdown(elementStr) {
+  const { href, title, description } = parseHeroCard(elementStr);
+  if (!href && !title) return "";
+  const label = title || href;
+  let line = href ? `- [${label}](${href})` : `- ${label}`;
+  if (description) line += `: ${description}`;
+  return line;
+}

scripts/component-handlers/home-page-hero.mjs

@@ -34,7 +34,7 @@
 
 import { jsonTableToMarkdown } from "./component-handlers/data-tables.mjs";
 import { integrationsGridToMarkdown } from "./component-handlers/integrations.mjs";
-import { homePageHeroToMarkdown } from "./component-handlers/home-page-hero.mjs";
+import { heroCardToMarkdown, heroHeadlineToMarkdown } from "./component-handlers/hero.mjs";
 import { parseCardItems, cardsToMarkdown } from "./component-handlers/cards.mjs";
 import { FEATURE_RELEASE_TYPES } from "../src/constants/featureReleaseTypes.js";
 import { readFileSync, existsSync } from "fs";
@@ -69,8 +69,23 @@ export const COMPONENT_REGISTRY = {
   SetupStep: "setup-step",
   JsonTable: "json-table",
   IntegrationsGrid: "integrations-grid",
-  HomePageHero: "home-page-hero",
   ViewSourceCodeNotice: "view-source-code-notice",
+
+  // Homepage hero (docs/index.mdx). Copy is authored in the MDX and composed
+  // from presentational components in src/components/elements/HomePageHero.js.
+  // Layout wrappers strip to their inner Markdown; the single-line HeroHeader /
+  // HeroCta lines strip whole (their text is redundant with the title / first
+  // action card); the cards resolve to Markdown link-list items.
+  HeroWrapper: "strip-tag",
+  HeroHeader: "strip-tag",
+  HeroSection: "strip-tag",
+  HeroContent: "strip-tag",
+  HeroHeadline: "hero-headline",
+  HeroActions: "strip-tag",
+  HeroCta: "strip-tag",
+  CommunityCards: "strip-tag",
+  ActionCard: "hero-card",
+  CommunityCard: "hero-card",
   DefinitionList: "strip-tag",
   DL: "strip-tag",
   DT: "strip-tag",
@@ -1167,12 +1182,37 @@ export function transformMdx(mdxContent, options = {}) {
       continue;
     }
 
-    // --- HomePageHero (self-closing) → hardcoded hero content ---
-    // See scripts/component-handlers/home-page-hero.mjs (kept in sync with
-    // src/components/elements/HomePageHero.js).
-    if (state === State.NORMAL && /^\s*<HomePageHero\b/.test(line)) {
-      outputLines.push(homePageHeroToMarkdown());
-      outputLines.push("");
+    // --- HeroHeadline → Markdown H1 ---
+    if (state === State.NORMAL && /^\s*<HeroHeadline\b/.test(line)) {
+      let el = line;
+      while (!/<\/HeroHeadline>/.test(el) && i + 1 < lines.length) {
+        i++;
+        el += "\n" + lines[i];
+      }
+      const md = heroHeadlineToMarkdown(el);
+      if (md) {
+        outputLines.push(md);
+        outputLines.push("");
+      }
+      continue;
+    }
+
+    // --- ActionCard / CommunityCard → Markdown link-list item ---
+    // The homepage hero cards (docs/index.mdx). Accumulate the whole element
+    // (usually a single line) and resolve title/href/description to a list item.
+    if (state === State.NORMAL && /^\s*<(ActionCard|CommunityCard)\b/.test(line)) {
+      const name = line.match(/^\s*<(ActionCard|CommunityCard)\b/)[1];
+      const closeRe = new RegExp(`</${name}>`);
+      let el = line;
+      while (!closeRe.test(el) && i + 1 < lines.length) {
+        i++;
+        el += "\n" + lines[i];
+      }
+      const md = heroCardToMarkdown(el);
+      if (md) {
+        outputLines.push(md);
+        outputLines.push("");
+      }
       continue;
     }