generate-docs updated test

abrulic · abrulic · commit 6e808f9d7bbf · 2025-11-17T14:22:25.000+01:00
diff --git a/content/06-usage-inside-monorepo.mdx b/content/06-usage-inside-monorepo.mdx
@@ -0,0 +1,65 @@
+---
+title: "Usage inside a monorepo"
+summary: "Add the docs-template into an existing monorepo and run it locally (pnpm workspace, workflows, and content setup)."
+description: "Step-by-step guide for integrating the docs-template into a monorepo: add the `docs/` package to `pnpm-workspace.yaml`, move CI workflows to `.github/workflows`, resolve FIXME markers, replace example content under `docs/content`, and run the local dev server with pnpm."
+---
+
+## Usage inside a monorepo
+
+This page explains the minimal steps to install the docs-template into an existing monorepo and run the documentation locally. The template is designed to be dropped under the `/docs` folder of your repository and wired into pnpm workspaces.
+
+Follow these steps:
+
+1. Create a repository (or use an existing one)
+
+   - You can start from our example stack `@forge42/open-source-stack` or any repo you control. The important part is that you can add a `/docs` folder and control the repository root (where `.github`, `pnpm-workspace.yaml`, etc. live).
+
+2. Download and extract the docs-template into your monorepo
+
+   - Download the `docs-template` files from the main branch (or copy the template contents) and extract them into the repository root inside a `docs/` directory.
+
+   - Make sure your root `pnpm-workspace.yaml` includes the `docs` package so pnpm can hoist and link the docs project. Example snippet:
+
+   ```yaml
+   packages:
+      packages/*
+      test-apps/*
+     + docs
+   onlyBuiltDependencies:
+      '@biomejs/biome'
+      esbuild
+      lefthook
+   ```
+
+
+3. Move or add workflow files to `.github/workflows` in the monorepo root
+
+   - The template includes CI workflows (for example: `ci.yml`, `publish-documentation.yml`, and `pr-close.yml`). Move these into your repository root under `.github/workflows/` so GitHub Actions can find and run them.
+
+   - The workflows use Fly.io and the template `fly.toml` and `Dockerfile`. If you don't use Fly, you can customize the workflows or remove those steps.
+
+4. Check and resolve FIXME comments inside workflows
+
+   - Open the workflow files and search for `FIXME` markers. Resolve those before relying on the workflows.
+
+5. Make sure you have a `/content` folder with documentation pages
+
+   - The template ships with example content in `docs/content` that briefly explains how the template works. Remove those example files and add your own documentation content (for example: `01-getting-started.mdx`, `02-project-structure.mdx`, etc.).
+
+6. Install and run locally
+
+   - From the repository root run:
+
+   ```bash
+   pnpm install
+   pnpm run dev
+   ```
+
+   - After `pnpm run dev` the docs server will start (see terminal output for the local dev URL). Open the URL in your browser to preview the site.
+
+Notes and tips
+
+- If your monorepo already has a `docs/` package, merge carefully to avoid overwriting important files.
+- Keep `fly.toml` and `Dockerfile` at the root of the `docs` package (or where the workflows expect them). If you move them, update the workflow paths accordingly.
+- Verify `pnpm-workspace.yaml` indentation and syntax — YAML parsing errors can stop workspace linking.
+- If you use a different package manager or CI provider, adapt the commands and workflow steps.
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
@@ -63,15 +63,6 @@ function resolveTagsFromSpec(spec: string) {
 	return matched.sort(semver.rcompare)
 }
 
-function hasLocalRef(ref: string) {
-	try {
-		run(`git show-ref --verify --quiet ${ref}`)
-		return true
-	} catch {
-		return false
-	}
-}
-
 function buildDocs(sourceDir: string, outDir: string) {
 	if (!existsSync(sourceDir)) {
 		throw new Error(
@@ -152,16 +143,6 @@ function buildRef(ref: string, labelForOutDir: string) {
 	}
 }
 
-function buildBranch(branch: string, labelForOutDir: string) {
-	run(`git fetch --tags --prune origin ${branch}`, {
-		cwd: workspaceRoot,
-		inherit: true,
-	})
-	const localRef = `refs/heads/${branch}`
-	const targetRef = hasLocalRef(localRef) ? localRef : `origin/${branch}`
-	return buildRef(targetRef, labelForOutDir)
-}
-
 function buildTag(tag: string) {
 	return buildRef(`refs/tags/${tag}`, tag)
 }
@@ -173,11 +154,6 @@ function getCurrentBranch(): string {
 		throw new Error("Failed to get current branch")
 	}
 }
-
-function isOnDefaultBranch(defaultBranch: string): boolean {
-	const currentBranch = getCurrentBranch()
-	return currentBranch === defaultBranch
-}
 ;(async () => {
 	const { values } = parseArgs({
 		args: process.argv.slice(2),
@@ -187,22 +163,12 @@ function isOnDefaultBranch(defaultBranch: string): boolean {
 		},
 	})
 
-	const defaultBranch = (values.branch as string | undefined)?.trim()
-	if (!defaultBranch) {
-		throw new Error(
-			`❌ Missing required --branch flag.
-   Please specify the default branch name (e.g., --branch main)
-   Example: pnpm run generate:docs --branch main`
-		)
-	}
-
 	const rawVersions = (values.versions as string | undefined)?.trim() ?? ""
 	const hasVersionsArg = rawVersions.length > 0
 
 	let builtVersions: string[] = []
 
-	const onDefaultBranch = isOnDefaultBranch(defaultBranch)
-	const currentBranchToBuild = onDefaultBranch ? defaultBranch : getCurrentBranch()
+	const currentBranchToBuild = getCurrentBranch()
 
 	// biome-ignore lint/suspicious/noConsole: keep for logging
 	console.log(chalk.cyan(`Building from branch: ${currentBranchToBuild}`))
@@ -215,27 +181,15 @@ function isOnDefaultBranch(defaultBranch: string): boolean {
 		console.log(chalk.cyan(`Building tags: ${tags.join(", ")}`))
 		for (const t of tags) buildTag(t)
 
-		if (onDefaultBranch) {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan(`Building default branch '${defaultBranch}' → current`))
-			buildBranch(defaultBranch, "current")
-		} else {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan("Building current workspace → current"))
-			buildDocs(workspaceRoot, join(outputDir, "current"))
-		}
+		// biome-ignore lint/suspicious/noConsole: keep for logging
+		console.log(chalk.cyan("Building current workspace → current"))
+		buildDocs(workspaceRoot, join(outputDir, "current"))
 
 		builtVersions = ["current", ...tags]
 	} else {
-		if (onDefaultBranch) {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan(`Building default branch '${defaultBranch}' → current`))
-			buildBranch(defaultBranch, "current")
-		} else {
-			// biome-ignore lint/suspicious/noConsole: keep for logging
-			console.log(chalk.cyan("Building current workspace → current"))
-			buildDocs(workspaceRoot, join(outputDir, "current"))
-		}
+		// biome-ignore lint/suspicious/noConsole: keep for logging
+		console.log(chalk.cyan("Building current workspace → current"))
+		buildDocs(workspaceRoot, join(outputDir, "current"))
 
 		builtVersions = ["current"]
 	}
diff --git a/vite.config.ts b/vite.config.ts
@@ -8,7 +8,7 @@ import babel from "vite-plugin-babel"
 import { iconsSpritesheet } from "vite-plugin-icons-spritesheet"
 import tsconfigPaths from "vite-tsconfig-paths"
 
-export default defineConfig(({ mode }) => ({
+export default defineConfig({
 	plugins: [
 		tailwindcss(),
 		// Run the react-compiler on .tsx files only when bundling
@@ -37,13 +37,11 @@ export default defineConfig(({ mode }) => ({
 			withTypes: true,
 			formatter: "biome",
 		}),
-		// Only load content-collections plugin in development
-		// In production, we load pre-generated docs from generated-docs/
-		...(mode === "development" ? [contentCollections()] : []),
+		contentCollections(),
 	],
 	server: {
 		open: true,
 		// biome-ignore lint/nursery/noProcessEnv: Its ok to use process.env here
 		port: Number(process.env.PORT || 4280),
 	},
-}))
+})
