docs for docs-template and small improvements

.github/workflows/build-documentation.yml

@@ -31,3 +31,25 @@ jobs:
       - name: Generate docs
         working-directory: docs
         run: pnpm run generate:docs
+
+
+  deploy:
+    name: 🚀 Deploy Release
+    needs: [build-docs]
+    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.ref_name }}
+          env_vars: |
+            APP_ENV=production
+            GITHUB_OWNER=${{ github.repository_owner }}
+            GITHUB_REPO=${{ github.event.repository.name }}
+            GITHUB_REPO_URL=https://github.com/${{ github.repository }}

README.md

@@ -4,6 +4,9 @@ This template is designed to support a flexible content structure using `.md` an
 
 The project is built using the [@forge-42/base-stack](https://github.com/forge-42/base-stack) and leverages the [content-collections](https://github.com/sdorra/content-collections).
 
+> **Note**:
+> We added a few `FIXME` comments in the codebase as notes to you. These simply mark small places where we expect you to make changes. Nothing major — it should only take you 2 minutes to go through them.
+
 
 ## Documentation Template Structure Overview
 

app/components/code-block/code-block-elements.tsx

@@ -57,7 +57,7 @@ export const PreElement = ({ lines, className = "", ...props }: PreElementProps)
 	<pre
 		{...props}
 		className={cn(
-			"relative overflow-x-auto rounded-lg border border-[var(--color-border)] bg-[var(--color-code-block-bg)] py-4 font-mono text-[var(--color-code-block-text)] text-xs leading-relaxed sm:text-sm md:text-base",
+			"scrollbar scrollbar-thin relative overflow-x-auto rounded-lg border border-[var(--color-border)] bg-[var(--color-code-block-bg)] py-4 font-mono text-[var(--color-code-block-text)] text-xs leading-relaxed sm:text-sm md:text-base [&::-webkit-scrollbar-thumb:hover]:cursor-pointer",
 			className
 		)}
 	>

app/components/code-block/code-block-syntax-highlighter.ts

@@ -13,6 +13,8 @@ const MASTER_REGEX = new RegExp(
 		"//.*?(?=\\n|$)",
 		// multi-line comment
 		"/\\*[\\s\\S]*?\\*/",
+		// hash comment at start of line
+		"^\\s*#.*$",
 		// strings
 		"(['\"])(?:(?!\\1)[^\\\\]|\\\\.)*\\1",
 		// numbers
@@ -101,7 +103,7 @@ const isKeyword = (value: string) => KEYWORDS.includes(value)
 const isOperator = (value: string) => OPERATORS.includes(value)
 const isFunction = (value: string) => /^[A-Z]/.test(value)
 const isWhitespace = (value: string) => /^\s/.test(value)
-const isComment = (value: string) => value.startsWith("//") || value.startsWith("/*")
+const isComment = (v: string) => v.startsWith("//") || v.startsWith("/*") || /^\s*#/.test(v)
 const isString = (value: string) => /^['"`]/.test(value)
 const isNumber = (value: string) => /^\d/.test(value)
 const isIdentifier = (value: string) => /^[a-zA-Z_$]/.test(value)

app/components/code-block/code-block.tsx

@@ -12,7 +12,7 @@ export const CodeBlock = ({ children, className = "", ...props }: CodeBlockProps
 	const lines = processLines(code)
 
 	return (
-		<div className="group relative">
+		<div className="group relative ">
 			<PreElement lines={lines} className={className} {...props} />
 			<CopyButton lines={lines} />
 		</div>

app/components/logo.tsx

@@ -1,8 +1,14 @@
 import type { ReactNode } from "react"
+import { href, useNavigate } from "react-router"
 
 export const Logo = ({ children }: { children: ReactNode }) => {
+	const navigate = useNavigate()
 	return (
-		<div className="relative block font-semibold font-space text-[var(--color-text-active)] text-lg md:text-2xl xl:text-3xl">
+		// biome-ignore lint/a11y/useKeyWithClickEvents: we don't need keyboard access for this
+		<div
+			onClick={() => navigate(href("/:version?/home"))}
+			className="relative block font-semibold font-space text-[var(--color-text-active)] text-lg md:text-2xl xl:text-3xl"
+		>
 			{children}
 		</div>
 	)

app/components/page-mdx-article.tsx

@@ -4,7 +4,7 @@ import { MDXWrapper } from "./mdx-wrapper"
 
 export default function PageMdxArticle({ page }: { page: Page }) {
 	return (
-		<article className="prose prose-invert w-full min-w-0 max-w-4xl flex-grow px-3 py-3 prose-headings:text-[var(--color-text-active)] prose-p:text-[var(--color-text-active)] text-sm leading-6 sm:text-base md:px-6 md:py-4 md:text-lg">
+		<article className="prose prose-invert w-full min-w-0 max-w-4xl flex-grow px-3 py-3 prose-headings:text-[var(--color-text-active)] prose-p:text-[var(--color-text-active)] text-sm leading-6 sm:text-base md:px-6 md:py-4 md:text-lg xl:leading-8">
 			<header className=" border-[var(--color-border)] border-b">
 				<Title className="mt-0 font-bold text-[var(--color-text-heading)]" as="h1">
 					{page.title}

app/components/table-of-content.tsx

@@ -1,4 +1,4 @@
-import { useCallback } from "react"
+import { useCallback, useEffect, useRef } from "react"
 import { Link, useLocation, useNavigate } from "react-router"
 import { useActiveHeadingId } from "~/hooks/use-active-heading-id"
 import type { HeadingItem } from "~/utils/extract-heading-tree-from-mdx"
@@ -48,10 +48,11 @@ const TocItem = ({ item, depth = 0, activeId, onItemClick }: TocItemProps) => {
 		<div>
 			<Link
 				to={`#${item.slug}`}
-				style={{ paddingLeft }}
 				className={className}
 				onClick={handleClick}
 				aria-current={isActive && "location"}
+				data-toc-slug={item.slug}
+				style={{ paddingLeft, scrollMarginTop: 8 }}
 			>
 				{item.title}
 			</Link>
@@ -66,12 +67,6 @@ const TocItem = ({ item, depth = 0, activeId, onItemClick }: TocItemProps) => {
 	)
 }
 
-const TableOfContentsHeader = () => (
-	<h2 className="mb-4 border-[var(--color-border)] border-b pb-2 font-semibold text-[var(--color-text-active)] text-base">
-		On this page
-	</h2>
-)
-
 const Navigation = ({
 	items,
 	activeId,
@@ -80,14 +75,49 @@ const Navigation = ({
 	items: HeadingItem[]
 	activeId: string | null
 	onItemClick: (slug: string) => Promise<void>
-}) => (
-	<nav aria-label="Table of contents" className="-mr-4 max-h-[calc(100vh-var(--header-height))] overflow-y-auto pr-4">
-		<div className="space-y-1 pb-2">
-			{items.map((item) => (
-				<TocItem key={item.slug} item={item} activeId={activeId} onItemClick={onItemClick} />
-			))}
-		</div>
-	</nav>
+}) => {
+	const navRef = useRef<HTMLDivElement>(null)
+
+	useEffect(() => {
+		if (!activeId) return
+		const nav = navRef.current
+		if (!nav) return
+
+		const el = nav.querySelector<HTMLElement>(`[data-toc-slug="${CSS.escape(activeId)}"]`)
+		if (!el) return
+
+		const padding = 24
+		const elTop = el.offsetTop
+		const elBottom = elTop + el.offsetHeight
+		const viewTop = nav.scrollTop
+		const viewBottom = viewTop + nav.clientHeight
+
+		if (elTop < viewTop + padding) {
+			nav.scrollTo({ top: Math.max(elTop - padding, 0), behavior: "smooth" })
+		} else if (elBottom > viewBottom - padding) {
+			nav.scrollTo({ top: elBottom - nav.clientHeight + padding, behavior: "smooth" })
+		}
+	}, [activeId])
+
+	return (
+		<nav
+			ref={navRef}
+			aria-label="Table of contents"
+			className="-mr-4 max-h[calc(100vh-var(--header-height))] overflow-y-auto pr-4"
+		>
+			<div className="space-y-1 pb-2">
+				{items.map((item) => (
+					<TocItem key={item.slug} item={item} activeId={activeId} onItemClick={onItemClick} />
+				))}
+			</div>
+		</nav>
+	)
+}
+
+const TableOfContentsHeader = () => (
+	<h2 className="mb-4 border-[var(--color-border)] border-b pb-2 font-semibold text-[var(--color-text-active)] text-base">
+		On this page
+	</h2>
 )
 
 export const TableOfContents = ({ items }: TableOfContentsProps) => {

app/routes/documentation-homepage.tsx

@@ -13,7 +13,8 @@ export const meta = ({ data }: Route.MetaArgs) => {
 	return generateMetaFields({
 		domain,
 		path: `/${version}/home`,
-		title: `${title} · Package Name`,
+		// FIXME Change "Docs Template" to your package name
+		title: `${title} · Docs Template`,
 		description,
 	})
 }

app/routes/documentation-layout.tsx

@@ -24,8 +24,8 @@ export default function DocumentationLayout({ loaderData }: Route.ComponentProps
 			<Header>
 				<div className="flex items-start gap-3">
 					<Logo>
-						{/* Replace with your Logo */}
-						<span className="p-0">REACT ROUTER DEVTOOLS</span>
+						{/* FIXME Replace with your Logo */}
+						<span className="p-0">DOCS-TEMPLATE</span>
 					</Logo>
 				</div>
 				<div className="inline-flex items-center gap-2 xl:gap-3">
@@ -42,7 +42,7 @@ export default function DocumentationLayout({ loaderData }: Route.ComponentProps
 					<Outlet />
 				</main>
 			</div>
-			{/* You can add custom footer component here */}
+			{/* FIXME You can add custom footer component here */}
 		</div>
 	)
 }

app/routes/documentation-page.tsx

@@ -20,8 +20,8 @@ export const meta = ({ data }: Route.MetaArgs) => {
 	return generateMetaFields({
 		domain,
 		path: fullPath,
-		// change "Package Name" to your package name
-		title: `${page.title} · Package Name`,
+		// FIXME change "Docs Template" to your package name
+		title: `${page.title} · Docs Template`,
 		description: page.description,
 	})
 }
@@ -48,7 +48,7 @@ export default function DocumentationPage({ loaderData }: Route.ComponentProps)
 	const toc = extractHeadingTreeFromMarkdown(page.rawMdx)
 
 	return (
-		<div className="flex min-h-screen flex-row">
+		<div className="flex min-h-screen flex-row ">
 			<div className="mx-auto flex w-full max-w-screen-4xl flex-col gap-4 pt-4 lg:gap-8 xl:pt-0">
 				<PageMdxArticle page={page} />
 				<PageNavigation previous={previous} next={next} />