Generate documentation

.github/workflows/build-documentation.yml

@@ -0,0 +1,33 @@
+name: 📚🚀 Build documentation on release
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+concurrency:
+  group: docs-build-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: "package.json"
+          cache: "pnpm"
+
+      - name: Install deps
+        run: pnpm install --prefer-offline --frozen-lockfile
+
+      - name: Generate docs
+        working-directory: docs
+        run: pnpm run generate:docs

.gitignore

@@ -84,3 +84,6 @@ blob-report
 
 # Content collections output files
 .content-collections
+
+# Output base directory of the documentation
+generated-docs/

README.md

@@ -11,7 +11,6 @@ The project is built using the [@forge-42/base-stack](https://github.com/forge-4
 
 This folder contains React Router v7 web application folders and files, including components and UI primitives for the documentation site’s interface, internal hooks and utilities, and the tailwind.css file for styling.
 
-
 `resources/`
 
 This folder contains all the resources used by the documentation site, such as SVG icons, fonts, and other assets.
@@ -97,8 +96,10 @@ pnpm install
 
 4. Add `content` folder
 
-5. Start the development server:
+5. Run `pnpm run generate:docs` script
+
+6. Start the development server:
 ```bash
 pnpm run dev
 ```
-5. Happy coding!
+7. Happy coding!

app/components/sidebar/build-breadcrumbs.tsx

@@ -1,5 +1,5 @@
 import { href } from "react-router"
-import { splitSlug } from "~/utils/split-slug"
+import { splitSlugAndAppendVersion } from "~/utils/split-slug-and-append-version"
 import type { SidebarSection } from "./sidebar"
 
 // builds a breadcrumb trail from sidebar sections based on the current pathname
@@ -8,7 +8,7 @@ export const buildBreadcrumb = (items: SidebarSection[], pathname: string) => {
 
 	const walk = (section: SidebarSection, acc: string[]) => {
 		for (const doc of section.documentationPages) {
-			const docPath = href("/:version/:section/:subsection?/:filename", splitSlug(doc.slug))
+			const docPath = href("/:version/:section/:subsection?/:filename", splitSlugAndAppendVersion(doc.slug))
 			if (docPath === pathname) {
 				trail = [...acc, section.title, doc.title]
 				return true

app/components/sidebar/sidebar-section.tsx

@@ -1,6 +1,6 @@
 import { NavLink, href } from "react-router"
 import { AccordionItem } from "~/ui/accordion"
-import { splitSlug } from "~/utils/split-slug"
+import { splitSlugAndAppendVersion } from "~/utils/split-slug-and-append-version"
 import type { SidebarSection } from "./sidebar"
 
 const getIndentClass = (depth: number) => {
@@ -30,11 +30,10 @@ const SectionTitle = ({ title }: { title: string }) => {
 
 const SectionItemLink = ({ documentPage, depth, onItemClick }: SectionItemLinkProps) => {
 	const indentClass = getIndentClass(depth)
-
 	return (
 		<NavLink
 			prefetch="intent"
-			to={href("/:version/:section/:subsection?/:filename", splitSlug(documentPage.slug))}
+			to={href("/:version/:section/:subsection?/:filename", splitSlugAndAppendVersion(documentPage.slug))}
 			onClick={onItemClick}
 			className={({ isActive, isPending }) =>
 				`block rounded-md px-3 py-2 text-xs sm:text-sm md:text-base ${indentClass}

app/components/sidebar/sidebar.tsx

@@ -8,7 +8,6 @@ import { MobileSidebarProvider } from "./mobile-sidebar-context"
 export type SidebarSection = {
 	title: string
 	slug: string
-	sectionId: string
 	subsections: SidebarSection[]
 	documentationPages: {
 		title: string

app/components/sidebar/tests/build-breadcrumbs.test.tsx

@@ -1,94 +1,80 @@
-import { buildBreadcrumb } from "../build-breadcrumbs"
+import { describe, expect, it, vi } from "vitest"
 import type { SidebarSection } from "../sidebar"
 
+vi.mock("~/utils/split-slug-and-append-version", () => ({
+	splitSlugAndAppendVersion: (slug: string) => {
+		const parts = slug.split("/").filter(Boolean)
+		const version = "v1.0.0"
+
+		if (parts.length === 2) {
+			const [section, filename] = parts
+			return { version, section, filename }
+		}
+		if (parts.length === 3) {
+			const [section, subsection, filename] = parts
+			return { version, section, subsection, filename }
+		}
+
+		throw new Error(`Bad slug in test: ${slug}`)
+	},
+}))
+
+import { buildBreadcrumb } from "../build-breadcrumbs"
+
 type Doc = { slug: string; title: string }
-const sec = (over: Partial<SidebarSection>) => ({
+const makeDoc = (slug: string, title: string): Doc => ({ slug, title })
+
+type MinimalSection = Pick<SidebarSection, "title" | "slug" | "documentationPages" | "subsections">
+const makeSection = (overrides: Partial<MinimalSection> = {}) => ({
 	title: "",
 	slug: "",
-	sectionId: "",
 	documentationPages: [],
 	subsections: [],
-	...over,
+	...overrides,
 })
 
-const doc = (slug: string, title: string): Doc => ({ slug, title })
-
-describe("buildBreadcrumb test suite", () => {
+describe("buildBreadcrumb (versioned paths via splitSlugAndAppendVersion)", () => {
 	it("returns [] when pathname doesn't match any doc", () => {
 		const items = [
-			sec({
+			makeSection({
 				title: "Getting Started",
-				slug: "v1/started",
-				documentationPages: [doc("v1/started/intro", "Intro")],
+				slug: "getting-started",
+				documentationPages: [makeDoc("getting-started/intro", "Intro")],
 			}),
 		]
-
-		// biome-ignore lint/suspicious/noExplicitAny: we can use any in tests
-		const result = buildBreadcrumb(items as any, "/v1/started/unknown")
-		expect(result).toEqual([])
+		expect(buildBreadcrumb(items, "/v1.0.0/getting-started/unknown")).toEqual([])
 	})
 
 	it("returns [section, doc] for a top-level doc", () => {
 		const items = [
-			sec({
+			makeSection({
 				title: "Getting Started",
-				slug: "v1/started",
-				documentationPages: [doc("v1/started/intro", "Intro")],
+				slug: "getting-started",
+				documentationPages: [makeDoc("getting-started/intro", "Intro")],
 			}),
 		]
-
-		// biome-ignore lint/suspicious/noExplicitAny: we can use any in tests
-		const result = buildBreadcrumb(items as any, "/v1/started/intro")
-		expect(result).toEqual(["Getting Started", "Intro"])
+		expect(buildBreadcrumb(items, "/v1.0.0/getting-started/intro")).toEqual(["Getting Started", "Intro"])
 	})
 
 	it("returns full trail for a nested doc (root → sub → doc)", () => {
 		const items = [
-			sec({
+			makeSection({
 				title: "Configuration",
-				slug: "v1/configuration",
+				slug: "configuration",
 				subsections: [
-					sec({
+					makeSection({
 						title: "Advanced",
-						slug: "v1/configuration/advanced",
-						documentationPages: [doc("v1/configuration/advanced/tuning", "Tuning")],
-					}),
-				],
-				documentationPages: [doc("v1/configuration/setup", "Setup")],
-			}),
-		]
-
-		// biome-ignore lint/suspicious/noExplicitAny: we can use any in tests
-		const result = buildBreadcrumb(items as any, "/v1/configuration/advanced/tuning")
-		expect(result).toEqual(["Configuration", "Advanced", "Tuning"])
-	})
-
-	it("stops at the first matching branch across multiple roots", () => {
-		const items = [
-			sec({
-				title: "Alpha",
-				slug: "v1/alpha",
-				documentationPages: [doc("v1/alpha/readme", "Readme")],
-			}),
-			sec({
-				title: "Beta",
-				slug: "v1/beta",
-				subsections: [
-					sec({
-						title: "Deep",
-						slug: "v1/beta/deep",
-						documentationPages: [doc("v1/beta/deep/file", "File")],
+						slug: "configuration/advanced",
+						documentationPages: [makeDoc("configuration/advanced/tuning", "Tuning")],
 					}),
 				],
+				documentationPages: [makeDoc("configuration/setup", "Setup")],
 			}),
 		]
-
-		// biome-ignore lint/suspicious/noExplicitAny: we can use any in tests
-		const result1 = buildBreadcrumb(items as any, "/v1/alpha/readme")
-		expect(result1).toEqual(["Alpha", "Readme"])
-
-		// biome-ignore lint/suspicious/noExplicitAny: we can use any in tests
-		const result2 = buildBreadcrumb(items as any, "/v1/beta/deep/file")
-		expect(result2).toEqual(["Beta", "Deep", "File"])
+		expect(buildBreadcrumb(items, "/v1.0.0/configuration/advanced/tuning")).toEqual([
+			"Configuration",
+			"Advanced",
+			"Tuning",
+		])
 	})
 })

app/components/versions-dropdown.tsx

@@ -0,0 +1,55 @@
+import { useState } from "react"
+import { useNavigate } from "react-router"
+import { Icon } from "~/ui/icon/icon"
+import { getCurrentVersion, homepageUrlWithVersion, isKnownVersion } from "~/utils/version-resolvers"
+import { versions } from "~/utils/versions"
+
+export function VersionDropdown() {
+	const navigate = useNavigate()
+	const { version: currentVersion } = getCurrentVersion()
+	const [selectedVersion, setSelectedVersion] = useState(currentVersion)
+
+	function onChange(e: React.ChangeEvent<HTMLSelectElement>) {
+		const next = e.target.value
+		if (next === currentVersion) return
+
+		setSelectedVersion(isKnownVersion(next) ? next : currentVersion)
+
+		const to = homepageUrlWithVersion(next)
+		const nav = () => {
+			navigate(to)
+			e.target.blur()
+		}
+		if (document.startViewTransition) document.startViewTransition(nav)
+		else nav()
+	}
+
+	return (
+		<div className="relative inline-block text-[var(--color-text-normal)]">
+			<select
+				id="version"
+				name="version"
+				className="cursor-pointer appearance-none rounded-lg border border-[var(--color-border)] bg-[var(--color-background)] py-2.5 pr-10 pl-4 font-medium text-sm shadow-sm transition-all duration-200 hover:bg-[var(--color-border)] focus:border-transparent focus:bg-[var(--color-border)] focus:outline-none focus:ring-none"
+				value={selectedVersion}
+				onChange={onChange}
+				aria-label="Select documentation version"
+			>
+				{versions.map((v) => (
+					<option
+						key={v}
+						value={v}
+						className={`bg-[var(--color-background)] text-[var(--color-text-normal)] hover:bg-[var(--color-background-hover)]${selectedVersion === v ? "font-semibold text-[var(--color-text-active)]" : ""}
+						`}
+					>
+						{v}
+					</option>
+				))}
+			</select>
+
+			<Icon
+				name="ChevronDown"
+				className="-translate-y-1/2 pointer-events-none absolute top-1/2 right-3 h-4 w-4 text-[var(--color-text-muted)] transition-colors duration-200"
+			/>
+		</div>
+	)
+}

app/hooks/use-previous-next-pages.ts

@@ -1,7 +1,7 @@
 import { href, useLocation } from "react-router"
 import type { SidebarSection } from "~/components/sidebar/sidebar"
 import { flattenSidebarItems } from "~/utils/flatten-sidebar"
-import { splitSlug } from "~/utils/split-slug"
+import { splitSlugAndAppendVersion } from "~/utils/split-slug-and-append-version"
 
 export function usePreviousNextPages(sections: SidebarSection[]) {
 	const { pathname } = useLocation()
@@ -15,7 +15,7 @@ export function usePreviousNextPages(sections: SidebarSection[]) {
 
 		return {
 			title: item.title,
-			to: href("/:version/:section/:subsection?/:filename", splitSlug(item.slug)),
+			to: href("/:version/:section/:subsection?/:filename", splitSlugAndAppendVersion(item.slug)),
 		}
 	}
 

app/routes.ts

@@ -1,13 +1,15 @@
 import { type RouteConfig, index, layout, route } from "@react-router/dev/routes"
 
 export default [
+	index("routes/index.tsx"),
 	layout("routes/documentation-layout.tsx", [
-		index("routes/documentation-homepage.tsx"),
+		route(":version?/home", "routes/documentation-homepage.tsx"),
 		route(":version/:section/:subsection?/:filename", "routes/documentation-page.tsx"),
 	]),
 	route("sitemap-index.xml", "routes/sitemap-index[.]xml.ts"),
 	route("robots.txt", "routes/robots[.]txt.ts"),
 	route("resource/*", "routes/resource.locales.ts"),
 	route("$", "routes/$.tsx"),
 	route("sitemap/:lang.xml", "routes/sitemap.$lang[.]xml.ts"),
+	route(":version?/llms.txt", "routes/llms[.]txt.ts"),
 ] satisfies RouteConfig

app/routes/documentation-homepage.tsx

@@ -1,14 +1,16 @@
-import { allPages } from "content-collections"
 import GithubContributeLinks from "~/components/github-contribute-links"
 import PageMdxArticle from "~/components/page-mdx-article"
+import { loadContentCollections } from "~/utils/load-content-collections"
+import { resolveVersionForHomepage } from "~/utils/version-resolvers"
 import type { Route } from "./+types/documentation-homepage"
 
-export async function loader() {
-	const page = allPages.find((post) => post._meta.path === "_index")
-	if (!page) {
-		throw new Response("Not Found", { status: 404 })
-	}
-	return { page }
+export async function loader({ params }: Route.LoaderArgs) {
+	const { version } = resolveVersionForHomepage(params.version)
+	const { allPages } = await loadContentCollections(version)
+	const page = allPages.find((p) => p._meta.path === "_index")
+	if (!page) throw new Response("Not Found", { status: 404 })
+
+	return { page, version }
 }
 
 export default function DocumentationHomepage({ loaderData }: Route.ComponentProps) {

app/routes/documentation-layout.tsx

@@ -3,22 +3,29 @@ import { Header } from "~/components/header"
 import { Logo } from "~/components/logo"
 import { Sidebar } from "~/components/sidebar/sidebar"
 import { ThemeToggle } from "~/components/theme-toggle"
+import { VersionDropdown } from "~/components/versions-dropdown"
 import { createSidebarTree } from "~/utils/create-sidebar-tree"
+import { resolveVersionForLayout } from "~/utils/version-resolvers"
 import type { Route } from "./+types/documentation-layout"
 
-export async function loader() {
-	return { sidebarTree: createSidebarTree() }
+export async function loader({ params, request }: Route.LoaderArgs) {
+	const { version } = resolveVersionForLayout(params.version, request)
+	const sidebarTree = await createSidebarTree(version)
+	return { sidebarTree, version }
 }
-
 export default function DocumentationLayout({ loaderData }: Route.ComponentProps) {
 	const { sidebarTree } = loaderData
+
 	return (
 		<div className="block min-h-screen bg-[var(--color-background)] 2xl:container 2xl:mx-auto">
 			<Header>
-				<Logo>
-					{/* Replace with your Logo */}
-					<span>REACT ROUTER DEVTOOLS</span>
-				</Logo>
+				<div className="flex items-start gap-3">
+					<Logo>
+						{/* Replace with your Logo */}
+						<span className="p-0">REACT ROUTER DEVTOOLS</span>
+					</Logo>
+					<VersionDropdown />
+				</div>
 				<ThemeToggle />
 			</Header>