feat: part 1

.cspell.jsonc

@@ -52,6 +52,9 @@
     "contentlayer",
     "basehub",
     "segs",
-    "shadcn"
+    "shadcn",
+    "fuma",
+    "takumi",
+    "customise"
   ]
 }

.github/workflows/ci.yml

@@ -35,6 +35,19 @@ jobs:
       - name: Run Biome
         run: bun check
 
+  links:
+    name: Links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v4
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Run links check
+        run: bun ./scripts/lint.ts
+
   spelling:
     name: Spelling
     runs-on: ubuntu-latest

TODO.md

@@ -1,4 +1,15 @@
 - [] Setup Custom Themes with TweakCN
 - [] Disable OpenAPI by default and give ability to add it through ShadCN cli, same with obsidian support, and changelog
 - [] Add a documentation to customize the fumadocs layout, like notebook and docs.
-- [] Ask fuma for the HeroUI theme
+- [x] Ask fuma for the HeroUI theme
+
+- [x] Verify OG Image generation
+- [x] Verify OpenAPI
+- [x] Verify Lint Script
+- [] Verify Page Tree
+- [] Update Docs for new ways
+- search is broken
+- verify if llms.txt and middleware work
+- think about llms.txt for index page
+- add back search with ai in empty search area
+- fix search tags

bunfig.toml

@@ -0,0 +1 @@
+preload = ["./scripts/preload.ts"]

content/docs/(index)/essentials/code.mdx

@@ -130,7 +130,7 @@ import { generateFiles } from 'fumadocs-openapi';
 
 void generateFiles({
   input: ['./museum.yaml'],
-  output: './content/docs/app',
+  output: './content/docs/(index)',
 });
 ```
 

content/docs/(index)/essentials/markdown.mdx

@@ -1,7 +1,7 @@
 ---
 title: 'Markdown Syntax'
 description: 'Text, title, and styling in standard markdown'
-icon: 'LetterText'
+icon: 'TextInitial'
 ---
 
 ## Introduction

content/docs/(index)/features/async-mode.mdx

@@ -8,8 +8,6 @@ icon: Clock
 
 By default, all Markdown and MDX files must be precompiled, even when running the development server. This requirement can increase startup time for large documentation sites.
 
-To improve performance, this template enables **Async Mode** by default, allowing content files to be compiled at runtime instead.
-
 ## Constraints
 
 Async Mode introduces some limitations to MDX features:

content/docs/(index)/features/openapi.mdx

@@ -22,31 +22,27 @@ The official OpenAPI integration supports:
 
 The `generate-docs` script uses the OpenAPI schema to generate the documentation. You can change the OpenAPI schema by modifying the `openapi.json` file in `content/docs/api-reference` of your project.
 
-```ts twoslash title="scripts/generate-docs.mts"
-import * as OpenAPI from 'fumadocs-openapi';
-import { rimraf } from 'rimraf';
+```ts title="scripts/generate-docs.ts"
+import * as OpenAPI from 'fumadocs-openapi'
+import { rimraf } from 'rimraf'
+import { openapi } from './lib/openapi' // [!code highlight]
+
+const out = './content/docs/api-reference/(generated)'
 
 export async function generateDocs() {
-  await rimraf('./content/docs/api-reference', {
+  await rimraf(out, {
     filter(v) {
-      return (
-        !v.endsWith('index.mdx') &&
-        !v.endsWith('openapi.json') &&
-        !v.endsWith('openapi.yml') &&
-        !v.endsWith('meta.json')
-      );
+      return !v.endsWith('meta.json')
     },
-  });
-
-  await Promise.all([
-    OpenAPI.generateFiles({
-      input: ['./content/docs/api-reference/openapi.yml'], // [!code highlight]
-      output: './content/docs/api-reference',
-      per: 'operation',
-      includeDescription: true,
-      groupBy: 'tag',
-    }),
-  ]);
+  })
+
+  await OpenAPI.generateFiles({
+    input: openapi, // [!code highlight]
+    output: out,
+    per: 'operation',
+    includeDescription: true,
+    groupBy: 'tag',
+  })
 }
 ```
 
@@ -60,16 +56,6 @@ bun run build:pre
 
 ## Removing the OpenAPI Integration
 
-
-<Accordions type="single" defaultValue="automatic">
-<Accordion title="Automatic" id="automatic">
-  To remove the OpenAPI integration automatically, you can use the `remove-openapi` script.
-  ```bash
-  bun run remove-openapi
-  ```
-</Accordion>
-  <Accordion title="Manual" id="manual">
-
 Follow these steps to completely remove the OpenAPI integration from your project.
 
 ### 1. Update `lib/source.ts`
@@ -96,7 +82,7 @@ export const source = loader({
 
 Delete the `lib/openapi.ts` file:
 
-```tsx twoslash title="- lib/openapi.ts"
+```ts twoslash title="lib/openapi.ts"
 import { createOpenAPI } from 'fumadocs-openapi/server' /* [!code --] */
 
 export const openapi = createOpenAPI({ /* [!code --] */
@@ -148,11 +134,11 @@ rm -rf content/docs/api-reference
 
 ### 4. Clean up build scripts
 
-#### `scripts/generate-docs.mts`
+#### `scripts/generate-docs.ts`
 
 Remove the OpenAPI generation logic:
 
-```tsx title="scripts/generate-docs.mts"
+```tsx title="scripts/generate-docs.ts"
 import * as OpenAPI from 'fumadocs-openapi' /* [!code --] */
 import { rimraf } from 'rimraf' /* [!code --] */
 import { openapi } from '@/lib/openapi' /* [!code --] */
@@ -172,11 +158,11 @@ export async function generateDocs() { /* [!code --] */
 } /* [!code --] */
 ```
 
-#### `scripts/pre-build.mts`
+#### `scripts/pre-build.ts`
 
 Remove the reference to `generateDocs`:
 
-```tsx title="scripts/pre-build.mts"
+```tsx title="scripts/pre-build.ts"
 import { generateDocs } from './generate-docs.mjs' /* [!code --] */
 
 async function main() {
@@ -256,6 +242,3 @@ bun remove fumadocs-openapi
 ```
 
 After completing these steps, all OpenAPI functionality will be removed from your Fumadocs setup.
-
-</Accordion>
-</Accordions>

content/docs/(index)/guides/customizing-the-layout.mdx

@@ -18,11 +18,11 @@ Fumadocs provides ready-to-use layouts. Let's go through them.
 
 ### 1.1. Docs Layout
 
+![Docs Layout](/docs/docs.png)
+
 The **Docs Layout** is the default option.  
 It's a clean, simple layout optimized for technical documentation.
 
-![Docs Layout](https://fumadocs.dev/_next/static/media/main.e7ce885e.png)
-
 To use this layout, update your `layout.tsx` file in `src/docs/layout.tsx`:
 
 ```tsx
@@ -36,11 +36,11 @@ import { DocsLayout } from 'fumadocs-ui/layouts/docs'
 The **Notebook Layout** is a more compact variation of the Docs Layout.
 It supports three different design modes:
 
-> **Note:** Nav Mode (1.2.3) is enabled in this template.
+> **Note:** [Nav Mode (1.2.3)](#123-nav-mode) + Solar Theme is enabled in this template.
 
 #### 1.2.1. Default Design
 
-![Notebook Layout](https://fumadocs.dev/_next/static/media/notebook.71f6ca16.png)
+![Notebook Layout](/docs/notebook.png)
 
 * The context switcher is integrated directly into the sidebar.
 * You can switch between contexts (e.g., framework docs, API reference) without leaving the navigation area.
@@ -63,7 +63,7 @@ export default function Layout({ children }: { children: ReactNode }) {
 
 #### 1.2.2. Tab Mode
 
-![Notebook Layout](https://fumadocs.dev/_next/static/media/notebook-tab-mode.48be7f0c.png)
+![Tab Mode](/docs/notebook-tab-mode.png)
 
 * The context switcher appears as horizontal tabs at the top of the documentation page.
 * Each tab represents a different context (e.g., *Framework, Core, MDX, CLI, OpenAPI Example*).
@@ -90,7 +90,7 @@ export default function Layout({ children }: { children: ReactNode }) {
 
 #### 1.2.3. Nav Mode
 
-![Notebook Layout](https://fumadocs.dev/_next/static/media/notebook-nav-mode.6fdd6fb4.png)
+![Nav Mode](/docs/notebook-nav-mode.png)
 
 * Both the search bar and context switcher move into a global navigation area above the sidebar and main content.
 * This creates a header-like navigation where search and context switching are the primary controls.

content/docs/(index)/guides/using-custom-themes.mdx

@@ -0,0 +1,146 @@
+---
+title: Using Custom Themes
+description: 'Learn how to use custom themes in Fumadocs'
+icon: Palette
+---
+
+## Introduction
+
+Fumadocs provides multiple ways to theme your docs. This guide walks you through using the built-in themes and customizing the design system.
+
+## 1. Setup
+
+Fumadocs UI ships with ready-to-use themes and a Tailwind CSS preset.
+
+Only Tailwind CSS v4 is supported. Import the preset and a theme stylesheet in your `styles/globals.css` file:
+
+```css title="globals.css"
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';
+```
+
+> **Note:** If you're using Shadcn UI, use the `shadcn` preset to have Fumadocs UI adopt your Shadcn theme.
+
+```css title="globals.css (shadcn)"
+@import 'tailwindcss';
+@import 'fumadocs-ui/css/shadcn.css';
+@import 'fumadocs-ui/css/preset.css';
+```
+
+## 2. Preflight Changes
+
+Using the preset or pre-built stylesheet will change default border, text, and background colors.
+
+## 3. Light/Dark Modes
+
+Light/dark modes are supported via [`next-themes`](https://github.com/pacocoursey/next-themes) and included in the Root Provider.
+
+> **Note:** See [Root Provider](https://fumadocs.dev/docs/ui/layouts/root-provider#theme-provider) for details.
+
+## 4. Colors
+
+### 4.1. Theme Gallery
+
+Pick a built-in theme by importing its stylesheet:
+
+```css title="tailwind.css"
+@import 'fumadocs-ui/css/<theme>.css';
+@import 'fumadocs-ui/css/preset.css';
+```
+
+<Tabs items={['neutral', 'black', 'vitepress', 'dusk', 'catppuccin', 'ocean', 'purple', 'solar']}>
+
+    <Tab value='neutral'>
+
+![Neutral](https://fumadocs.dev/themes/neutral.png)
+
+    </Tab>
+
+    <Tab value='black'>
+
+![Black](https://fumadocs.dev/themes/black.png)
+
+    </Tab>
+
+    <Tab value='vitepress'>
+
+![Vitepress](https://fumadocs.dev/themes/vitepress.png)
+
+    </Tab>
+
+    <Tab value='dusk'>
+
+![Dusk](https://fumadocs.dev/themes/dusk.png)
+
+    </Tab>
+
+    <Tab value='Catppuccin'>
+
+![Catppuccin](https://fumadocs.dev/themes/catppuccin.png)
+
+    </Tab>
+
+    <Tab value='ocean'>
+
+![Ocean](https://fumadocs.dev/themes/ocean.png)
+
+    </Tab>
+
+    <Tab value='purple'>
+
+![Purple](https://fumadocs.dev/themes/purple.png)
+
+    </Tab>
+
+  <Tab value='solar'>
+
+    ![Solar](https://fumadocs.dev/themes/solar.png)
+
+  </Tab>
+
+</Tabs>
+
+### 4.2. Custom Theme
+
+Customize the design system colors with CSS variables:
+
+```css title="global.css"
+@theme {
+  --color-fd-background: hsl(0, 0%, 96%);
+  --color-fd-foreground: hsl(0, 0%, 3.9%);
+  --color-fd-muted: hsl(0, 0%, 96.1%);
+  --color-fd-muted-foreground: hsl(0, 0%, 45.1%);
+  --color-fd-popover: hsl(0, 0%, 98%);
+  --color-fd-popover-foreground: hsl(0, 0%, 15.1%);
+  --color-fd-card: hsl(0, 0%, 94.7%);
+  --color-fd-card-foreground: hsl(0, 0%, 3.9%);
+  --color-fd-border: hsla(0, 0%, 80%, 50%);
+  --color-fd-primary: hsl(0, 0%, 9%);
+  --color-fd-primary-foreground: hsl(0, 0%, 98%);
+  --color-fd-secondary: hsl(0, 0%, 93.1%);
+  --color-fd-secondary-foreground: hsl(0, 0%, 9%);
+  --color-fd-accent: hsla(0, 0%, 82%, 50%);
+  --color-fd-accent-foreground: hsl(0, 0%, 9%);
+  --color-fd-ring: hsl(0, 0%, 63.9%);
+}
+
+.dark {
+  --color-fd-background: hsl(0, 0%, 7.04%);
+  --color-fd-foreground: hsl(0, 0%, 92%);
+  --color-fd-muted: hsl(0, 0%, 12.9%);
+  --color-fd-muted-foreground: hsla(0, 0%, 70%, 0.8);
+  --color-fd-popover: hsl(0, 0%, 11.6%);
+  --color-fd-popover-foreground: hsl(0, 0%, 86.9%);
+  --color-fd-card: hsl(0, 0%, 9.8%);
+  --color-fd-card-foreground: hsl(0, 0%, 98%);
+  --color-fd-border: hsla(0, 0%, 40%, 20%);
+  --color-fd-primary: hsl(0, 0%, 98%);
+  --color-fd-primary-foreground: hsl(0, 0%, 9%);
+  --color-fd-secondary: hsl(0, 0%, 12.9%);
+  --color-fd-secondary-foreground: hsl(0, 0%, 92%);
+  --color-fd-accent: hsla(0, 0%, 40.9%, 30%);
+  --color-fd-accent-foreground: hsl(0, 0%, 90%);
+  --color-fd-ring: hsl(0, 0%, 54.9%);
+}
+```