improvements

.dockerignore

@@ -0,0 +1,89 @@
+node_modules
+public/build
+build
+dist
+out
+coverage
+.history
+.react-router
+
+# Other Coverage tools
+*.lcov
+
+# macOS
+.DS_*
+
+# Cache Directories and files
+.cache
+.yarn*
+.env*
+!.env.example
+.swp*
+.turbo
+.npm
+.stylelintcache
+*.tsbuildinfo
+.node_repl_history
+
+# Lock files from other package managers
+package-lock.json
+yarn.lock
+
+# General tempory files and directories
+t?mp
+.t?mp
+*.t?mp
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Output of 'npm pack'
+*.tgz
+*.tar
+*.tar.gz
+*.tar.bz2
+*.tbz
+*.zip
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+vite.config.ts.*
+
+# Playwright various test reports
+test-results
+playwright-report
+blob-report
+
+
+# Editors
+.idea/workspace.xml
+.idea/usage.statistics.xml
+.idea/shelf
+
+# Dont commit sqlite database files
+*.db
+*.sqlite
+*.sqlite3
+*.db-journal
+
+
+# Content collections output files
+.content-collections
+
+# Output base directory of the documentation
+generated-docs/

.env.example

@@ -1,3 +1,4 @@
 GITHUB_OWNER="github-owner"  # Your username or organization name (Optional. For edit/report an issue for the documentation page)
 GITHUB_REPO="github-repo" # Repository name (Optional. For edit/report an issue for the documentation page)
 APP_ROOT_PATH="/path/to/your/app" # Optional. Default is `process.cwd()`
+GITHUB_REPO_URL="github-repo-url" # Optional. If you want to have GitHub icon link in the header or footer

.github/workflows/validate.yml → .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: 🚀 Validation Pipeline
+name: 🚀 Validation & Deploy Pipeline
 concurrency:
   group: ${{ github.repository }}-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -67,3 +67,24 @@ jobs:
         # Only works if you set `reportOnFailure: true` in your vite config as specified above
         if: always()
         uses: davelosert/vitest-coverage-report-action@v2
+
+
+  deploy:
+      needs: [lint, typecheck, check-unused, vitest]
+      name: 🚀 Deploy PR Preview
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v4
+        - uses: forge-42/fly-deploy@v1.0.0-rc.2
+          id: deploy
+          env:
+            FLY_ORG: ${{ vars.FLY_ORG }}
+            FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+            FLY_REGION: ${{ vars.FLY_REGION }}
+          with:
+            app_name: ${{github.event.repository.name}}-${{ github.event.number }}
+            env_vars: |
+              APP_ENV=staging
+              GITHUB_OWNER=${{github.repository_owner}}
+              GITHUB_REPO=${{github.event.repository.name}}
+              GITHUB_REPO_URL=https://github.com/${{ github.repository }}

.github/workflows/pr-close.yml

@@ -0,0 +1,27 @@
+name: 🧹 PR Close
+
+concurrency:
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches: [main]
+    types: closed
+
+jobs:
+
+  destroy-pr-preview:
+    name: 🧹 Destroy PR Preview
+    runs-on: ubuntu-latest
+    environment:
+      name: pr-preview
+    steps:
+      - uses: actions/checkout@v4
+      - uses: forge-42/fly-destroy@v1.0.0-rc.2
+        id: destroy
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+          FLY_ORG: ${{ vars.FLY_ORG }}
+        with:
+          app_name: ${{ env.FLY_ORG }}-${{ github.event.number }}

Dockerfile

@@ -0,0 +1,51 @@
+
+# syntax = docker/dockerfile:1.4
+
+# Base dependencies stage
+ARG NODE_VERSION=22.17.0
+FROM node:${NODE_VERSION}-slim AS base
+
+LABEL fly_launch_runtime="Node.js"
+
+# Node.js app lives here
+WORKDIR /app
+
+# Set production environment
+ENV NODE_ENV="production"
+
+# Install pnpm
+ARG PNPM_VERSION=10.13.0
+RUN npm install -g pnpm@$PNPM_VERSION
+
+
+# Throw-away build stage to reduce size of final image
+FROM base AS build
+
+# Install packages needed to build node modules
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y build-essential node-gyp pkg-config python-is-python3 git
+
+# Install node modules
+COPY .npmrc package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --prod=false
+
+# Copy application code
+COPY . .
+
+# Build application
+RUN pnpm run generate:docs
+RUN pnpm run build
+
+# Remove development dependencies
+RUN pnpm prune --prod
+
+
+# Final stage for app image
+FROM base
+
+# Copy built application
+COPY --from=build /app /app
+
+# Start the server by default, this can be overwritten at runtime
+EXPOSE 3000
+CMD [ "pnpm", "run", "start" ]

README.md

@@ -17,7 +17,7 @@ This folder contains all the resources used by the documentation site, such as S
 
 `content/`
 
-This folder contains sections and subsections with .mdx files that hold your documentation content. Below is the recommended structure to follow.
+This folder contains .md and .mdx files that hold your documentation content. Below is the recommended structure to follow.
 
 
 An example of a valid content/ folder structure for organizing your package documentation:
@@ -46,12 +46,15 @@ content/
         ├── 01-buttons.mdx
         └── 02-modals.mdx
 ```
-- Top-level .mdx files (like 01-changelog.mdx) are allowed.
-- Sections (like 04-getting-started, 05-core-features) are subfolders inside the content/ folder.
-- Subsections (like 03-data-management, 04-ui-components) are nested folders within sections.
-- Each section or subsection should have an index.md file for its sidebar title.
+- Top-level .mdx files (like 01-changelog.mdx) are allowed, but we recommend placing them in order before the sections, as shown in the example.
 
-### Example of the valid `02-introduction.mdx` file:
+- Sections (like 04-getting-started, 05-core-features) are subfolders inside the `content` folder.
+
+- Subsections (like 03-data-management, 04-ui-components) are nested folders within sections. Filenames inside them should start with `01-*.mdx`.
+
+- Each section or subsection should include an `index.md` file, which defines its sidebar title.
+
+### Example of the valid `**/*.mdx` file:
 ```
 ---
 title: "Introduction to Forge42 Base Stack"
@@ -75,7 +78,7 @@ cd my-app
 npm install
 ```
 
-### Example of the valid `04-getting-started/index.md` file:
+### Example of the valid `**/*.md` file:
 ```
 ---
 title: Getting Started

app/components/command-k/components/search-input.tsx

@@ -13,7 +13,7 @@ export function SearchInput({ value, onChange, placeholder, ref }: SearchInputPr
 	return (
 		<div
 			className={cn(
-				"flex items-center gap-3 border-[var(--color-input-border)] border-b bg-[var(--color-input-bg)] px-4 py-4"
+				"flex items-center gap-3 border-[var(--color-input-border)] border-b bg-[var(--color-input-bg)] px-4 py-3"
 			)}
 		>
 			<Icon name="Search" className="size-5 flex-shrink-0 text-[var(--color-input-icon)]" />

app/components/command-k/components/trigger-button.tsx

@@ -12,7 +12,7 @@ export const TriggerButton = ({
 		type="button"
 		onClick={onOpen}
 		className={cn(
-			"group flex items-center gap-2 rounded-lg border px-3 py-2 text-sm shadow-sm transition-all duration-200",
+			"group flex items-center gap-2 rounded-lg border px-2 py-1.5 text-sm shadow-sm transition-all duration-200 xl:px-3 xl:py-2",
 			"border-[var(--color-trigger-border)] bg-[var(--color-trigger-bg)] text-[var(--color-trigger-text)]",
 			"hover:border-[var(--color-trigger-hover-border)] hover:bg-[var(--color-trigger-hover-bg)] hover:shadow-md",
 			"focus:border-[var(--color-trigger-focus-border)] focus:outline-none focus:ring-2 focus:ring-[var(--color-trigger-focus-ring)]"
@@ -22,8 +22,8 @@ export const TriggerButton = ({
 			name="Search"
 			className={cn("size-4 transition-colors", "group-hover:text-[var(--color-trigger-hover-text)]")}
 		/>
-		<span className="hidden sm:inline">{placeholder}</span>
-		<div className="ml-auto hidden items-center gap-1 sm:flex">
+		<span className="hidden xl:inline">{placeholder}</span>
+		<div className="ml-auto hidden items-center gap-1 xl:flex">
 			<kbd
 				className={cn(
 					"rounded border border-[var(--color-kbd-border)] bg-[var(--color-kbd-bg)] px-1.5 py-0.5 font-mono text-xs",

app/components/command-k/create-search-index.ts

@@ -108,12 +108,11 @@ function extractHeadingSections(rawMdx: string) {
 
 export function createSearchIndex(pages: Page[]) {
 	return pages
-		.filter((page) => page._meta.fileName !== "_index.mdx" && page.slug !== "_index")
+		.filter((page) => page.slug !== "_index")
 		.flatMap((page) => {
 			const pageSlug = getPageSlug(page)
 			const pageUrl = pageSlug.startsWith("/") ? pageSlug : `/${pageSlug}`
 			const sections = extractHeadingSections(page.rawMdx)
-
 			return sections.map((section) => {
 				const heading = section.heading === "_intro" ? page.title : section.heading
 

app/components/command-k/hooks/use-debounce.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react"
+
+export function useDebounce<T>(value: T, delay = 250) {
+	const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+	useEffect(() => {
+		const id = setTimeout(() => setDebouncedValue(value), delay)
+		return () => clearTimeout(id)
+	}, [value, delay])
+
+	return debouncedValue
+}

app/components/command-k/hooks/use-search.ts

@@ -1,9 +1,10 @@
-import { useState } from "react"
+import { useEffect, useRef, useState } from "react"
 import { useFetcher } from "react-router"
 import z from "zod"
 import type { Version } from "~/utils/version-resolvers"
 import { versions } from "~/utils/versions"
 import type { SearchResult } from "../search-types"
+import { useDebounce } from "./use-debounce"
 
 export const commandKSearchParamsSchema = z.object({
 	query: z.string(),
@@ -23,31 +24,36 @@ function createCommandKSearchParams(params: Record<string, string>) {
 	return { params: new URLSearchParams(result.data) }
 }
 
+const debounceMs = 250
+const minChars = 1
+
 export function useSearch({ version }: { version: Version }) {
 	const fetcher = useFetcher<{ results: SearchResult[] }>()
 	const [query, setQuery] = useState("")
-	//we will show results as soon as we have a non-empty query
-	//this does not debounce or wait for fetcher.state === "idle".
+	const debouncedQuery = useDebounce(query, debounceMs)
+	const lastLoadedRef = useRef<string | null>(null)
+
 	const results = query.trim() ? (fetcher.data?.results ?? []) : []
 
 	function search(q: string) {
-		const trimmed = q.trim()
+		setQuery(q)
+	}
 
-		if (!trimmed) {
-			setQuery("")
+	useEffect(() => {
+		const trimmed = debouncedQuery.trim()
+		if (!trimmed || trimmed.length < minChars) {
+			lastLoadedRef.current = null
 			return
 		}
 
-		setQuery(trimmed)
+		if (lastLoadedRef.current === trimmed) return
+		lastLoadedRef.current = trimmed
+
 		const { params } = createCommandKSearchParams({ query: trimmed, version })
-		if (!params) {
-			// biome-ignore lint/suspicious/noConsole: keep for debugging
-			console.error("Failed to create search parameters.")
-			return
-		}
+		if (!params) return
 
 		fetcher.load(`/search?${params.toString()}`)
-	}
+	}, [debouncedQuery, version, fetcher])
 
 	return {
 		results,

app/components/icon-link.tsx

@@ -0,0 +1,28 @@
+import type { ComponentProps } from "react"
+import { Icon } from "~/ui/icon/icon"
+import type { IconName } from "~/ui/icon/icons/types"
+import { cn } from "~/utils/css"
+
+interface IconLinkProps extends ComponentProps<"a"> {
+	name: IconName
+}
+
+export const IconLink = ({ name, className, ...props }: IconLinkProps) => {
+	const { href } = props
+	const isExternal = typeof href === "string" && /^https?:\/\//i.test(href)
+	return (
+		<a
+			className={cn(
+				"group relative inline-flex cursor-pointer items-center justify-center rounded-full text-[var(--color-text-active)] transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-border)] focus-visible:ring-offset-2",
+				className
+			)}
+			target={isExternal ? "_blank" : undefined}
+			rel="noopener noreferrer"
+			aria-label={name}
+			href={href}
+			{...props}
+		>
+			<Icon name={name} className="size-4 transition-all duration-300 xl:size-5" />
+		</a>
+	)
+}

app/components/logo.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from "react"
 
 export const Logo = ({ children }: { children: ReactNode }) => {
 	return (
-		<div className="relative block font-semibold font-space text-[var(--color-text-active)] text-lg md:text-2xl xl:text-4xl">
+		<div className="relative block font-semibold font-space text-[var(--color-text-active)] text-lg md:text-2xl xl:text-3xl">
 			{children}
 		</div>
 	)