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: ${{ env.FLY_ORG }}-${{ github.event.number }}
+            env_vars: |
+              APP_ENV=staging
+              GITHUB_OWNER=forge-42
+              GITHUB_REPO=docs-template
+              GITHUB_REPO_URL=https://github.com/forge-42/docs-template

Dockerfile

@@ -0,0 +1,50 @@
+# syntax = docker/dockerfile:1
+
+# Adjust NODE_VERSION as desired
+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.2.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,7 +108,7 @@ function extractHeadingSections(rawMdx: string) {
 
 export function createSearchIndex(pages: Page[]) {
 	return pages
-		.filter((page) => page._meta.fileName !== "_index.mdx" && page.slug !== "_index")
+		.filter((page) => page._meta.fileName === "_index.mdx" && page.slug !== "_index")
 		.flatMap((page) => {
 			const pageSlug = getPageSlug(page)
 			const pageUrl = pageSlug.startsWith("/") ? pageSlug : `/${pageSlug}`

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/page-mdx-article.tsx

@@ -1,4 +1,4 @@
-import type { Page } from "~/routes/documentation-page"
+import type { Page } from "content-collections"
 import { Title } from "~/ui/title"
 import { MDXWrapper } from "./mdx-wrapper"
 
@@ -10,9 +10,9 @@ export default function PageMdxArticle({ page }: { page: Page }) {
 					{page.title}
 				</Title>
 				{page.description && (
-					<Title as="h5" className="my-6 text-[var(--color-text-muted)] text-lg">
+					<p className="my-6 font-normal text-[var(--color-text-muted)] text-base sm:text-lg md:text-xl">
 						{page.description}
-					</Title>
+					</p>
 				)}
 			</header>
 			<MDXWrapper content={page.content} />

app/components/sidebar/build-breadcrumbs.ts

@@ -0,0 +1,41 @@
+import type { Page } from "content-collections"
+import type { SidebarSection } from "~/utils/create-sidebar-tree"
+import { buildDocPathFromSlug } from "~/utils/path-builders"
+
+export const buildBreadcrumbs = (
+	items: SidebarSection[],
+	pathname: string,
+	documentationPages: Pick<Page, "title" | "slug">[] = []
+) => {
+	// for standalone pages: /:filename
+	for (const page of documentationPages) {
+		const docPath = buildDocPathFromSlug(page.slug)
+		if (docPath === pathname) {
+			return [page.title]
+		}
+	}
+
+	// for sectioned pages: /:section/:subsection?/:filename
+	let trail: string[] = []
+
+	const walk = (section: SidebarSection, acc: string[]): boolean => {
+		for (const doc of section.documentationPages) {
+			const docPath = buildDocPathFromSlug(doc.slug)
+			if (docPath === pathname) {
+				trail = [...acc, section.title, doc.title]
+				return true
+			}
+		}
+
+		for (const sub of section.subsections) {
+			if (walk(sub, [...acc, section.title])) return true
+		}
+		return false
+	}
+
+	for (const root of items) {
+		if (walk(root, [])) break
+	}
+
+	return trail
+}

app/components/sidebar/desktop-sidebar.tsx

@@ -1,14 +1,14 @@
+import type { SidebarTree } from "~/utils/create-sidebar-tree"
 import { cn } from "~/utils/css"
-import type { SidebarSection } from "./sidebar"
 import { SidebarContent } from "./sidebar-content"
 
-export const DesktopSidebarPanel = ({ items, className }: { items: SidebarSection[]; className: string }) => (
+export const DesktopSidebarPanel = ({ sidebarTree, className }: { sidebarTree: SidebarTree; className: string }) => (
 	<div
 		className={cn(
 			"sticky top-[var(--header-height)] flex h-[calc(100vh-var(--header-height))] w-80 flex-col overflow-hidden bg-[var(--color-background)] p-4",
 			className
 		)}
 	>
-		<SidebarContent items={items} />
+		<SidebarContent sidebarTree={sidebarTree} />
 	</div>
 )