astro

.github/workflows/main.yml

@@ -54,6 +54,12 @@ jobs:
       environment: production
     secrets: inherit
 
+  astro-website:
+    uses: ./.github/workflows/website-astro.yml
+    with:
+      environment: astro-production
+    secrets: inherit
+
   storybook:
     uses: ./.github/workflows/storybook.yml
     with:

.github/workflows/pr.yml

@@ -31,6 +31,13 @@ jobs:
     if: ${{ !github.event.pull_request.head.repo.fork }}
     secrets: inherit
 
+  astro-website-preview:
+    uses: ./.github/workflows/website-astro.yml
+    with:
+      environment: astro-preview
+    if: ${{ !github.event.pull_request.head.repo.fork }}
+    secrets: inherit
+
   storybook-preview:
     uses: ./.github/workflows/storybook.yml
     with:

.github/workflows/website-astro.yml

@@ -0,0 +1,66 @@
+name: Astro website
+
+on:
+  workflow_call:
+    inputs:
+      environment:
+        type: string
+        required: true
+
+jobs:
+  deployment:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    environment:
+      name: ${{ inputs.environment }}
+      url: ${{ steps.deploy.outputs.deployment-url }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: setup bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: build
+        run: bun run build
+        working-directory: packages/documentation-astro
+        env:
+          NODE_OPTIONS: "--max-old-space-size=8192"
+
+      - name: deploy to cloudflare workers
+        uses: cloudflare/wrangler-action@da0e0dfe58b7a431659754fdf3f186c529afbe65 # v3.14.1
+        id: deploy
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          packageManager: bun
+          workingDirectory: packages/documentation-astro
+          command: |
+            ${{ github.ref == 'refs/heads/main' && 'deploy' || 'versions upload' }}
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: find astro deployment comment
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        id: fc
+        if: ${{ github.event.pull_request.number != '' }}
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: "github-actions[bot]"
+          body-includes: <!--- astro-deployment-preview --->
+
+      - name: create/update astro deployment comment
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
+        if: ${{ github.event.pull_request.number != '' }}
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            <!--- astro-deployment-preview --->
+
+            Astro: [${{ steps.deploy.outputs.deployment-url }}](${{ steps.deploy.outputs.deployment-url }})
+          edit-mode: replace

.gitignore

@@ -16,6 +16,7 @@ coverage
 .vercel
 
 # Build Outputs
+.astro/
 .next/
 out/
 build

.oxfmtrc.json

@@ -13,6 +13,7 @@
     ".vercel/",
     ".output/",
     ".cache/",
+    ".astro/",
     ".source/",
     ".tldr/",
     ".context/",

packages/documentation-astro/README.md

@@ -0,0 +1,58 @@
+# Documentation in Astro
+
+This package is an attempt in converting the existing documentation located at `../documentation` to an astro static page.
+
+The goal is to keep all the content (assets, markdown files) withion the old documentation for now (so it does not go out of sync).
+
+All the pages implemented should follow the existing components within the `../documentation` and `../design-system` folders.
+
+When tasked to migrate a page follow these steps:
+
+- find the corresponding page within the old docs, trace the components
+- create the new components as astro components (keep markdown and classes identical if possible)
+- implement the new pages
+- leverage playwrigth/chromium for visually diffing the pages
+- check if components were already created for other pages before creating them
+
+# Action Items
+
+## Pages needing migration
+
+- [x] `/blog`
+- [x] `/product-updates`
+- [x] `/ecosystem`
+- [x] `/gateway`
+
+## Adjustments required for docs
+
+- [x] The docs styles for paragraphs, headings, lists etc are off
+- [x] the navigation is in the wrong order, we need a way to order the docs based on the existing `meta.json` files in the old docs
+- [x] The stylings of many components is off; create a list of components to review
+  - [x] `Callout.astro` only had dark-mode colors ported (dark navy/olive/brown boxes), but the site only renders in light mode — fixed to use the actual light-mode design tokens (`--color-*-100/500/800`) and the real per-type icons instead of a placeholder glyph.
+  - [x] Product updates timeline and detail page should use the same styles as the old one — rewrote both to match the old site's exact Tailwind classes (`ProductUpdatesPage`/`ProductUpdateTeaser` timeline, `Heading size="md"` for titles) instead of a from-scratch custom-CSS design; the detail page's byline now reuses `BlogAuthors.astro` instead of duplicating markup.
+  - [x] fix the step component to look like the original one (used in GraphQL Federation) — `Step`/`Steps` now match fumadocs' real `.fd-step`/`.fd-steps` classes (muted secondary-token badge instead of a loud brand-accent circle).
+  - [x] fix the file component tree component (used in GraphQL Federation) — `File`/`Files`/`Folder` now match fumadocs' real component (bordered card, lucide file/folder icons, open/closed folder state) instead of plain "▾"/"└" text glyphs.
+  - [x] fix the tab component — `Tabs`/`Tab` now match the real `@hive/design-system/tabs` component (flat underline-style tab list) instead of a boxed pill-button tab bar.
+  - [x] fix the mermaid diagrams — now rendered at build time with `rehype-mermaid` + Playwright, matching the old site exactly: added `rehype-mermaid` and `playwright` as dependencies, wired the plugin into the `unified()` markdown processor in `astro.config.mjs` (`src/markdown/rehype-mermaid-config.mjs`, ported verbatim from `packages/documentation/source.config.ts`'s `mermaidConfig()`), and excluded `mermaid` from Shiki syntax highlighting (`mdx({ syntaxHighlight: { excludeLangs: ["mermaid"] } })`) so rehype-mermaid sees the unprocessed code block — Shiki would otherwise tokenize it first since Astro/MDX apply syntax highlighting before user rehype plugins by default. Diagrams are now static inline SVGs styled via the same `--mermaid-*` CSS custom properties as the old site (ported into `global.css`, light-mode values only). No client JS, no flash of raw code. (Superseded the earlier client-side `mermaid.js` approach from the previous pass in this file.)
+
+## Remaining documentation features
+
+- [ ] Restore documentation page actions: Copy Markdown, View on GitHub, and Edit on GitHub.
+- [ ] Restore last-updated metadata on documentation pages.
+- [ ] Restore the inline self-hosting deployment changelog instead of linking to GitHub.
+- [ ] Include deployment changelog headings in the page table of contents and search index.
+- [ ] Restore the root deployment changelog RSS feed and add RSS discovery links.
+- [ ] Restore rich code-block behavior: copy buttons, titles, highlighted lines, `npm2yarn`, light/dark themes, and explicitly triggered Twoslash.
+
+## Remaining quality work
+
+- [ ] Make the mobile navigation behave as an accessible drawer with Escape-to-close, focus transfer, focus trapping, focus restoration, background inertness, and scroll locking.
+- [ ] Add a visible focus style to the responsive "On this page" control.
+- [ ] Add schemas for docs, blog posts, product updates, and case studies to validate and normalize frontmatter during the build.
+- [ ] Restore lazy viewport mounting for StackBlitz and CodeSandbox embeds.
+- [ ] Preserve production base-path handling for local videos and other MDX media.
+- [ ] Review migrated video defaults against the old autoplay, loop, muted, and controls behavior.
+- [ ] Restore the old YouTube iframe security attributes where applicable.
+- [ ] Add generated-output link and anchor checking, including unresolved relative links, public assets, redirects, and external links.
+- [ ] Scope Pagefind content and add useful metadata, filters, weights, and ignored regions so navigation and footer content do not pollute results.
+- [ ] Add integration tests for StackBlitz, CodeSandbox, YouTube, local video, Mermaid, tabs, files, steps, and other MDX compatibility components.

packages/documentation-astro/astro.config.mjs

@@ -0,0 +1,149 @@
+import mdx from "@astrojs/mdx";
+import { unified } from "@astrojs/markdown-remark";
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "astro/config";
+import {
+  rehypeCode,
+  rehypeCodeDefaultOptions,
+} from "fumadocs-core/mdx-plugins";
+import { fileURLToPath } from "node:url";
+
+import {
+  DOCS_CODE_LANGS,
+  DOCS_CODE_THEMES,
+} from "../documentation/src/lib/docs-code-config.ts";
+import { mermaidRehypePlugin } from "./src/markdown/rehype-mermaid-config.mjs";
+import { remarkNpm2Yarn } from "./src/markdown/remark-npm2yarn.mjs";
+import { remarkRelativeLinks } from "./src/markdown/remark-relative-links.mjs";
+
+export default defineConfig({
+  integrations: [
+    mdx({
+      processor: unified({
+        // Keep this in sync with the Fumadocs pipeline so code-block metadata,
+        // including filenames, has identical semantics in both sites.
+        rehypePlugins: [
+          mermaidRehypePlugin,
+          [
+            rehypeCode,
+            {
+              langs: [...DOCS_CODE_LANGS],
+              tab: false,
+              themes: DOCS_CODE_THEMES,
+              transformers: rehypeCodeDefaultOptions.transformers,
+            },
+          ],
+        ],
+        remarkPlugins: [remarkNpm2Yarn, remarkRelativeLinks],
+      }),
+      syntaxHighlight: false,
+    }),
+  ],
+  publicDir: fileURLToPath(new URL("../documentation/public", import.meta.url)),
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: [
+        alias(
+          "@hive/design-system/hive-components/callout",
+          "./src/mdx-shims/callout.ts",
+        ),
+        alias("@hive/design-system/tabs", "./src/mdx-shims/tabs.ts"),
+        alias("@hive/design-system/image", "./src/mdx-shims/image.ts"),
+        alias(
+          "@hive/design-system/hive-components/card",
+          "./src/mdx-shims/card.ts",
+        ),
+        alias(
+          "@hive/design-system/hive-components/screenshot",
+          "./src/mdx-shims/screenshot.ts",
+        ),
+        alias(
+          "@hive/design-system/call-to-action",
+          "./src/mdx-shims/call-to-action.ts",
+        ),
+        alias(
+          "@hive/design-system/contact-us",
+          "./src/mdx-shims/contact-us.ts",
+        ),
+        alias(
+          "@hive/design-system/mdx-components/mdx-video",
+          "./src/mdx-shims/video.ts",
+        ),
+        alias(
+          "@hive/design-system/youtube-iframe",
+          "./src/mdx-shims/youtube-iframe.ts",
+        ),
+        alias(
+          "@hive/design-system/hive-components/cli-errors",
+          "./src/mdx-shims/cli-errors.ts",
+        ),
+        alias(
+          "@hive/design-system/hive-components/stack-blitz",
+          "./src/mdx-shims/stack-blitz.ts",
+        ),
+        alias(
+          "@hive/design-system/hive-components/code-sandbox",
+          "./src/mdx-shims/code-sandbox.ts",
+        ),
+        alias(
+          "@hive/design-system/hive-components/link-card",
+          "./src/mdx-shims/link-card.ts",
+        ),
+        alias(
+          "@hive/design-system/hive-components/comparison",
+          "./src/mdx-shims/comparison.ts",
+        ),
+        alias("fumadocs-ui/components/steps", "./src/mdx-shims/steps.ts"),
+        alias("fumadocs-ui/components/files", "./src/mdx-shims/files.ts"),
+        alias("fumadocs-ui/components/callout", "./src/mdx-shims/callout.ts"),
+        alias(
+          "#components/otel-metrics/metrics-section",
+          "./src/mdx-shims/metrics-section.ts",
+        ),
+        alias("#components/large-callout", "./src/mdx-shims/large-callout.ts"),
+        alias("#components/lede", "./src/mdx-shims/lede.ts"),
+        alias("#components/small-avatar", "./src/mdx-shims/small-avatar.ts"),
+        alias(
+          "@/components/deployment-changelog",
+          "./src/mdx-shims/changelog.ts",
+        ),
+        alias(
+          "virtual:deployment-changelog-toc",
+          "./src/mdx-shims/changelog-toc.ts",
+        ),
+        {
+          find: /.*\/src\/components\/arrow-icon\.tsx$/,
+          replacement: fileURLToPath(
+            new URL("./src/mdx-shims/arrow-icon.ts", import.meta.url),
+          ),
+        },
+        {
+          find: /.*\/src\/components\/blog\/welcome-hive-router-components(\.tsx)?$/,
+          replacement: fileURLToPath(
+            new URL(
+              "./src/mdx-shims/welcome-hive-router-components.ts",
+              import.meta.url,
+            ),
+          ),
+        },
+        {
+          find: /.*\/src\/components\/blog\/welcome-hive-router-zero-copy-json(\.tsx)?$/,
+          replacement: fileURLToPath(
+            new URL(
+              "./src/mdx-shims/welcome-hive-router-zero-copy-json.ts",
+              import.meta.url,
+            ),
+          ),
+        },
+      ],
+    },
+  },
+});
+
+function alias(find, path) {
+  return {
+    find,
+    replacement: fileURLToPath(new URL(path, import.meta.url)),
+  };
+}

packages/documentation-astro/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "documentation-astro",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build && bun run generate:sitemap && bun run generate:redirects && pagefind --site dist",
+    "generate:redirects": "bun scripts/generate-redirects.ts",
+    "generate:sitemap": "bun scripts/generate-sitemap.ts",
+    "typecheck": "astro check"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "7.2.2",
+    "@astrojs/mdx": "7.0.5",
+    "@hive/design-system": "workspace:*",
+    "astro": "7.2.0",
+    "fumadocs-core": "16.4.7",
+    "npm-to-yarn": "3.0.1",
+    "playwright": "1.57.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "rehype-mermaid": "3.0.0",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@astrojs/check": "0.9.10",
+    "@tailwindcss/vite": "4.1.18",
+    "@types/react": "19.2.8",
+    "@types/react-dom": "19.2.3",
+    "pagefind": "1.5.2",
+    "tailwindcss": "4.1.18",
+    "typescript": "5.9.3"
+  }
+}

packages/documentation-astro/scripts/generate-redirects.ts

@@ -0,0 +1,38 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import { routeRules } from "../../documentation/redirects.ts";
+
+const outputDirectory = fileURLToPath(new URL("../dist", import.meta.url));
+const outputFile = fileURLToPath(
+  new URL("../dist/_redirects", import.meta.url),
+);
+
+const redirects = Object.entries(routeRules)
+  .map(([source, rule]) => {
+    if (!rule.redirect || typeof rule.redirect === "string") {
+      throw new Error(`Expected ${source} to contain a redirect object`);
+    }
+
+    return {
+      source: source.replace(/\/\*\*$/, "/*"),
+      destination: rule.redirect.to,
+      status: rule.redirect.status,
+    };
+  })
+  .sort(
+    (a, b) => Number(a.source.endsWith("/*")) - Number(b.source.endsWith("/*")),
+  );
+
+const contents = [
+  "# Generated from packages/documentation/redirects.ts. Do not edit manually.",
+  ...redirects.map(
+    ({ source, destination, status }) => `${source} ${destination} ${status}`,
+  ),
+  "",
+].join("\n");
+
+await mkdir(outputDirectory, { recursive: true });
+await writeFile(outputFile, contents);
+
+console.log(`Generated ${redirects.length} redirects in ${outputFile}`);