Lets see how updated content looks!

Learn how to customize styling, components, and features to make the documentation template your own.

Finding Customization Points

We've marked key customization points with FIXME comments throughout the codebase. Find them all:

grep -r "FIXME" --include="*.ts" --include="*.tsx" --include="*.css"

These typically take just 2 minutes to update and include:

Brand colors
Package names
Repository URLs
Site metadata

Styling Customization

Tailwind CSS Configuration

The main styles are in app/tailwind.css. This is where you'll customize:

Brand Colors:

theme {
  --color-primary-50: /* your brand color */;
  --color-primary-100: /* ... */;
  /* ... */
  --color-primary-900: /* ... */;
}

Typography:

theme {
  --font-sans: "Your Font", system-ui, sans-serif;
  --font-mono: "Your Mono Font", monospace;
}

Dark Mode: The template uses Tailwind v4's native dark mode. Customize dark theme colors in the same @theme block.

Component Styling

All components in app/components/ can be styled. Key components to customize:

Sidebar - Navigation appearance
Command K - Search modal styling
MDXWrapper - Content styling
Code blocks - Syntax highlighting theme

Adding Custom MDX Components

1. Create Your Component

Create a new component in app/components/:

// app/components/Callout.tsx
interface CalloutProps {
  type: 'info'  'warning'  'success';
  children: React.ReactNode;
}
export function Callout({ type, children }: CalloutProps) {
  return (
    <div className={`callout callout-${type}`}>
      {children}
    </div>
  );
}

2. Register in MDXContent

Find the MDXContent component and add your component:

import { Callout } from '~/components/Callout';
<MDXContent
  code={doc.body.code}
  components={{
    InfoAlert,
    WarningAlert,
    Callout,  // ← Add your component
  }}
/>

3. Use in MDX

<Callout type="success">
Your custom component is now available!
</Callout>

Modifying Routes

Routes are defined in app/routes.ts. The template uses React Router v7's route configuration.

Adding a New Top-Level Page

// app/routes.ts
import { type RouteConfig } from "@react-router/dev/routes";
export default [
  // ... existing routes
  {
    path: "/changelog",
    file: "routes/changelog.tsx",
  },
] satisfies RouteConfig;

Modifying Documentation Layout

The documentation layout is in app/routes/docs.$version.$.tsx. This handles:

Sidebar rendering
Content area
Version selection
GitHub links

Configuration Files

content-collections.ts

This file defines how your MDX files are processed:

import { defineCollection, defineConfig } from "@content-collections/core";
const docs = defineCollection({
  name: "docs",
  directory: "content",
  include: "**/*.mdx",
  schema: (z) => ({
    title: z.string(),
    summary: z.string().optional(),
    description: z.string(),
  }),
});
export default defineConfig({
  collections: [docs],
});

Customization ideas:

Add custom frontmatter fields
Add different content collections
Modify file processing

generate-docs.ts

This script handles documentation versioning. Key parts you might customize:

Git commands - Change how releases are fetched
File processing - Modify what gets copied
Version naming - Change version folder names

Adding Features

Analytics

Add analytics by modifying app/root.tsx:

// Add to <head>
<script
  async
  src="https://analytics.example.com/script.js"
  data-website-id="your-id"
/>

Custom Search

The Command K component can be extended to search external sources or add custom filters.

Add a footer, header links, or breadcrumbs by modifying the layout components.

Performance Tips

1. Optimize Images

Place images in public/ or resources/:

![Alt text](/images/diagram.png)

Use modern formats (WebP, AVIF) for better performance.

2. Code Splitting

React Router v7 automatically code-splits routes. Keep your route components focused and lean.

3. Lazy Loading

For heavy components, use React's lazy loading:

import { lazy } from 'react';
const HeavyComponent = lazy(() => import('./HeavyComponent'));

Content Tips

1. Use Descriptive Titles

Good titles improve SEO and navigation:

❌ "API"
✅ "API Reference Guide"

2. Write Clear Descriptions

The description frontmatter is used for SEO meta tags:

---
description: "Learn how to authenticate users in your app using OAuth 2.0 and JWT tokens with our authentication library."
---

3. Break Up Long Pages

Instead of one huge page, split into multiple pages in a section:

03-advanced/
 index.md
 01-caching.mdx
 02-performance.mdx
 03-security.mdx

4. Use Visual Aids

Add diagrams, screenshots, and code examples to improve understanding.

Common Customizations

Change Primary Color

Edit app/tailwind.css:

theme {
  --color-primary-500: f97316; /* Orange */
}

Update Package Name

Search and replace throughout the codebase:

grep -r "your-old-package-name" --include="*.ts" --include="*.tsx"

Modify the footer or header components to include:

GitHub
Twitter
Discord
Slack

Change Font

Add font files to resources/fonts/
Update tailwind.css:

import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
theme {
  --font-sans: "Inter", system-ui, sans-serif;
}

Development Workflow Tips

Hot Reload

The dev server supports hot module replacement. Changes to:

MDX files reload instantly
React components reload on save
Tailwind classes update live

Content Organization

Keep related files together and use consistent naming:

content/
 04-api-reference/
     index.md
     01-authentication.mdx
     02-endpoints.mdx
     03-errors.mdx

Testing

Use Vitest for testing components:

pnpm test

Add tests in __tests__/ folders alongside your components.

Troubleshooting

Content Not Showing

Check file naming follows NN-name.mdx format
Verify frontmatter is valid YAML
Run pnpm run content-collections:build to rebuild

Styling Not Applying

Check Tailwind classes are valid v4 syntax
Verify tailwind.css is imported in root.tsx
Clear browser cache

Build Errors

Check for TypeScript errors: pnpm tsc
Verify all imports are correct
Check content-collections schema matches your frontmatter

Getting Help

If you run into issues:

Check the FIXME comments for guidance
Review the sample content for examples
Reach out to the Forge 42 team

Happy documenting! 🚀