Add package reference links to docs (#110)

* Surface package registries in docs home

* Show package table with live versions on docs home and landing

The docs home only listed package names as bullets at the very bottom,
with no version info. Surface every gem and npm package prominently with
its current version.

- Render a single Package | Version | Registry | Description table on the
  docs home, replacing the plain bulleted list (still before "Need more
  help?").
- Versions come from live shields.io badges, so they stay current with no
  manual updates.
- Add a Packages section to the landing page right after Quick Start.
- Introduce prototypes/docusaurus/src/data/packages.json as the single
  source of truth shared by the docs-home transform and the landing page.
- Update prepare-docs tests for the table + badge output.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Move package version badges from home page to footer

The full "Gems and npm packages" table was too heavy for the marketing
home page. Replace it with a slender, always-visible reference in the
site footer.

- Remove the PackagesSection (and its table CSS) from the landing page.
- Add a "Packages" column to the footer with one live shields.io version
  badge per package, each labeled with both the name and registry
  (e.g. "react_on_rails (gem) 16.6.0"), linking to its registry page.
- Footer badges are generated from the shared packages.json, the same
  source as the docs-home Packages table, so the two never drift.

The detailed Package | Version | Registry | Description table stays on
the docs home, unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Format footer packages as aligned name + version rows

The first footer pass rendered each package as one wide combined badge, so
the version pills landed at ragged, inconsistent positions and the longest
name overflowed the column.

- Split each row into a left-aligned monospace name (with a muted gem/npm
  tag) and a right-aligned live version pill, so the pills line up in a
  tidy column.
- Use flat-square shields badges for a cleaner look.
- Size the Packages footer column to its content so the longest name
  (react-on-rails-pro-node-renderer) and its pill never clip and all pills
  share one right edge.

Verified in light mode, dark mode, and mobile.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: justin808

prototypes/docusaurus/docusaurus.config.ts

@@ -2,6 +2,7 @@ import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 import type * as Preset from '@docusaurus/preset-classic';
 import {GlobExcludeDefault} from '@docusaurus/utils';
+import packages from './src/data/packages.json';
 
 // Use Algolia DocSearch when configured, otherwise fall back to local search.
 // Set ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY, and ALGOLIA_INDEX_NAME env vars
@@ -22,6 +23,24 @@ const localSearchTheme: NonNullable<Config['themes']>[number] = [
   },
 ];
 
+// Slender version reference for the site footer. Reads the shared packages.json
+// (same source as the docs-home Packages table) and renders one row per package:
+// the package name + registry on the left, a live shields.io version pill on the
+// right. CSS aligns the pills into a neat column (see custom.css).
+const packageFooterItems = packages.map((pkg) => {
+  const isGem = pkg.registry === 'rubygems';
+  const registryShort = isGem ? 'gem' : 'npm';
+  const page = isGem
+    ? `https://rubygems.org/gems/${pkg.name}`
+    : `https://www.npmjs.com/package/${pkg.name}`;
+  const badge = isGem
+    ? `https://img.shields.io/gem/v/${pkg.name}?style=flat-square&label=`
+    : `https://img.shields.io/npm/v/${pkg.name}?style=flat-square&label=`;
+  return {
+    html: `<a class="footer__package" href="${page}" target="_blank" rel="noopener noreferrer"><span class="footer__package-name">${pkg.name} <span class="footer__package-registry">(${registryShort})</span></span><img class="footer__package-version" src="${badge}" alt="${pkg.name} ${registryShort} version" loading="lazy" /></a>`,
+  };
+});
+
 const config: Config = {
   title: 'React on Rails',
   tagline: 'Integrate React with Rails, including SSR, RSC, and production-grade docs.',
@@ -197,6 +216,10 @@ const config: Config = {
             },
           ],
         },
+        {
+          title: 'Packages',
+          items: packageFooterItems,
+        },
       ],
       copyright: `Copyright © ${new Date().getFullYear()} ShakaCode. Built with Docusaurus.`,
     },

prototypes/docusaurus/src/css/custom.css

@@ -345,3 +345,46 @@ body {
     background: var(--site-surface);
   }
 }
+
+/* Size the Packages column to its content (instead of an equal 1/4 share) so the
+   longest package name plus its version pill never clips, and every pill aligns
+   to the same right edge. :has() targets only the column holding our badges. */
+.footer__col:has(.footer__package) {
+  flex: 0 0 auto;
+  width: auto;
+  max-width: none;
+}
+
+/* Footer "Packages" column: package name on the left, a live version pill on
+   the right. justify-content lines the pills up into a tidy column. */
+.footer__package {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.85rem;
+  padding: 0.12rem 0;
+  white-space: nowrap;
+  color: var(--ifm-footer-link-color);
+}
+
+.footer__package:hover {
+  text-decoration: none;
+}
+
+.footer__package:hover .footer__package-name {
+  text-decoration: underline;
+}
+
+.footer__package-name {
+  font-size: 0.82rem;
+  font-family: var(--ifm-font-family-monospace);
+}
+
+.footer__package-registry {
+  color: var(--ifm-color-content-secondary);
+}
+
+.footer__package-version {
+  height: 18px;
+  flex: none;
+}

prototypes/docusaurus/src/data/packages.json

@@ -0,0 +1,37 @@
+[
+  {
+    "name": "react_on_rails",
+    "registry": "rubygems",
+    "description": "Rails integration gem for React on Rails open source."
+  },
+  {
+    "name": "react-on-rails",
+    "registry": "npm",
+    "description": "JavaScript runtime and helpers for the open source gem."
+  },
+  {
+    "name": "react_on_rails_pro",
+    "registry": "rubygems",
+    "description": "Pro Rails gem for SSR, RSC, streaming, and Node Renderer integration."
+  },
+  {
+    "name": "react-on-rails-pro",
+    "registry": "npm",
+    "description": "Pro client package for higher-throughput SSR and related integrations."
+  },
+  {
+    "name": "react-on-rails-pro-node-renderer",
+    "registry": "npm",
+    "description": "Dedicated Node.js renderer used by React on Rails Pro."
+  },
+  {
+    "name": "react-on-rails-rsc",
+    "registry": "npm",
+    "description": "React Server Components support package."
+  },
+  {
+    "name": "create-react-on-rails-app",
+    "registry": "npm",
+    "description": "CLI for scaffolding a new Rails and React app."
+  }
+]

scripts/prepare-docs.mjs

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -652,6 +653,65 @@ async function normalizeCodeFences(docsRoot) {
   }
 }
 
+// Registry-specific URL and shields.io badge builders. The bare `?label=` keeps
+// the badge as a colored version pill only; the Registry table column carries
+// the npm/RubyGems distinction so the two never repeat.
+const registryConfig = {
+  npm: {
+    label: "npm",
+    pageUrl: (name) => `https://www.npmjs.com/package/${name}`,
+    badgeUrl: (name) => `https://img.shields.io/npm/v/${name}?label=`
+  },
+  rubygems: {
+    label: "RubyGems",
+    pageUrl: (name) => `https://rubygems.org/gems/${name}`,
+    badgeUrl: (name) => `https://img.shields.io/gem/v/${name}?label=`
+  }
+};
+
+// Single source of truth for the package list, shared with the landing page
+// (src/pages/index.tsx reads the same file). Versions are not stored here; they
+// render live from the registries via the shields.io badges above.
+const packageReferences = JSON.parse(
+  readFileSync(
+    path.join(workspaceRoot, "prototypes", "docusaurus", "src", "data", "packages.json"),
+    "utf8"
+  )
+);
+
+function packageReferencesMarkdown() {
+  const rows = packageReferences
+    .map((entry) => {
+      const registry = registryConfig[entry.registry];
+      const pageUrl = registry.pageUrl(entry.name);
+      const badgeUrl = registry.badgeUrl(entry.name);
+      return `| [\`${entry.name}\`](${pageUrl}) | [![${entry.name} version](${badgeUrl})](${pageUrl}) | ${registry.label} | ${entry.description} |`;
+    })
+    .join("\n");
+
+  return `## Packages
+
+React on Rails ships as a Ruby gem with companion npm packages. Versions are pulled live from each registry.
+
+| Package | Version | Registry | Description |
+| --- | --- | --- | --- |
+${rows}
+`;
+}
+
+function injectPackageReferences(markdown) {
+  if (/^## Packages$/m.test(markdown)) {
+    return markdown;
+  }
+
+  const section = packageReferencesMarkdown();
+  if (markdown.includes("\n## Need more help?")) {
+    return markdown.replace("\n## Need more help?", `\n${section}\n## Need more help?`);
+  }
+
+  return `${markdown.trimEnd()}\n\n${section}`;
+}
+
 export function docsHomeMarkdown(sourceMarkdown, { hasArchive }) {
   const archiveBlock = hasArchive ? "- [Historical Reference](./archive/README.md)\n" : "";
   const friendlyLicenseSection = `## Friendly License Model
@@ -660,13 +720,13 @@ export function docsHomeMarkdown(sourceMarkdown, { hasArchive }) {
 - Production deployments require a paid license. See [Pro pricing and sign up](https://pro.reactonrails.com/) for current options. If your organization is budget-constrained, [contact us](mailto:justin@shakacode.com) about free or low-cost licenses.
 `;
 
-  const updated = sourceMarkdown
+  const updated = injectPackageReferences(sourceMarkdown
     .trim()
     .replaceAll("(./oss/", "(./")
     .replace("](https://reactonrails.com/examples)", "](/examples)")
     .replace(/\n- \[Documentation website\]\(https:\/\/reactonrails\.com\/docs\/\)\s*/g, "\n")
     .replace(/## Friendly evaluation policy\n\n[\s\S]*?(?=\n## )/, `${friendlyLicenseSection}\n`)
-    .replace("## Need more help?\n\n", `## Need more help?\n\n${archiveBlock}`);
+    .replace("## Need more help?\n\n", `## Need more help?\n\n${archiveBlock}`));
 
   return `---\ncustom_edit_url: null\n---\n\n${updated}\n`;
 }

scripts/prepare-docs.test.mjs

@@ -88,6 +88,42 @@ test("docs homepage uses current friendly license model copy", () => {
   assert.doesNotMatch(updated, /Friendly evaluation policy/);
 });
 
+test("docs homepage renders a package table with linked names and live version badges", () => {
+  const sourceMarkdown = `# React on Rails
+
+## Need more help?
+`;
+
+  const updated = docsHomeMarkdown(sourceMarkdown, { hasArchive: false });
+
+  // Heading + table scaffold
+  assert.match(updated, /## Packages/);
+  assert.match(updated, /\| Package \| Version \| Registry \| Description \|/);
+
+  // Every package: name links to its registry page, version renders as a live
+  // shields.io badge, and the registry column labels the source.
+  assert.match(
+    updated,
+    /\| \[`react_on_rails`\]\(https:\/\/rubygems\.org\/gems\/react_on_rails\) \| \[!\[react_on_rails version\]\(https:\/\/img\.shields\.io\/gem\/v\/react_on_rails\?label=\)\]\(https:\/\/rubygems\.org\/gems\/react_on_rails\) \| RubyGems \|/
+  );
+  assert.match(
+    updated,
+    /\| \[`react-on-rails`\]\(https:\/\/www\.npmjs\.com\/package\/react-on-rails\) \| \[!\[react-on-rails version\]\(https:\/\/img\.shields\.io\/npm\/v\/react-on-rails\?label=\)\]\(https:\/\/www\.npmjs\.com\/package\/react-on-rails\) \| npm \|/
+  );
+
+  // Remaining packages each appear with a registry page link and a version badge.
+  for (const name of [
+    "react_on_rails_pro",
+    "react-on-rails-pro",
+    "react-on-rails-pro-node-renderer",
+    "react-on-rails-rsc",
+    "create-react-on-rails-app",
+  ]) {
+    assert.match(updated, new RegExp(`\\[\`${name}\`\\]`));
+    assert.match(updated, new RegExp(`img\\.shields\\.io/(npm|gem)/v/${name}\\?label=`));
+  }
+});
+
 test("site sidebar replaces the external changelog link with an internal doc reference", () => {
   const source = `const sidebars = {
   docsSidebar: [