---
title: Extending Thally
description: Thally is a docs platform you own and build on — add custom components, pages, API routes, themes, and more without forking core.
url: http://localhost:3040/guides/extending
---

# Extending Thally

Thally is a docs platform you own and build on — add custom components, pages, API routes, themes, and more without forking core.

Thally isn't a black box you configure from the outside — a Thally project is a
Next.js app **you own**. You author `src/content/`, `docs.json`, and `snippets/`;
everything under `src/app/` is a hidden runtime. That means you can add virtually
any functionality your team needs, and Thally gives you clean, update-safe surfaces
for the most common extensions so you rarely have to touch core files.

## Custom MDX components

Register your own React components once and use them in any `.mdx` page. Edit
**`src/mdx/custom-components.tsx`** — this file is yours and is never overwritten
when you update Thally.

```tsx
// src/mdx/custom-components.tsx
import type { MDXComponents } from 'mdx/types'
import type { ReactNode } from 'react'

function Highlight({ children }: { children: ReactNode }) {
  return <mark className="rounded bg-accent/15 px-1 text-foreground">{children}</mark>
}

export const customComponents: MDXComponents = {
  Highlight,
}
```

```mdx
Thally is <Highlight>yours to extend</Highlight>.
```

Your components merge **on top of** the built-ins, so you can also override a
built-in (`Note`, `Card`, `Steps`, …) by registering the same name. Components
can take props from MDX (`<PricingTable plan="pro" />`), import anything, and be
server or client components.

Look at `src/components/mdx/rich-content.tsx` to see how Thally's own components are
built — it's the best reference for writing your own.

## Custom pages and routes

Because Thally is a Next.js App Router project, any file you add under `src/app/`
becomes a route. Add a marketing page, a dashboard, an interactive playground —
anything React can do.

```tsx
// src/app/(docs)/status/page.tsx  →  /status
export default function StatusPage() {
  return <main className="mx-auto max-w-3xl p-8">Your custom page.</main>
}
```

## Custom API endpoints

Add server routes under `src/app/api/` for webhooks, form handlers, integrations,
or data your components fetch.

```ts
// src/app/api/newsletter/route.ts  →  POST /api/newsletter
import { NextResponse } from 'next/server'

export async function POST(request: Request) {
  const { email } = await request.json()
  // ...subscribe the address, call your ESP, etc.
  return NextResponse.json({ ok: true })
}
```

## Theming and brand tokens

Brand colors, fonts, and presets live in `src/data/site.ts` (`brandPresets`) and
the CSS tokens in `src/app/globals.css`. Change one preset and the whole site
reskins. See [Branding & Theming](/guides/branding-and-theming) and
[Custom Fonts](/guides/custom-fonts).

## Reusable snippets

Share MDX fragments across pages from `snippets/`, and import them anywhere. See
[Writing Content](/guides/writing-content).

## Configuration

- **`docs.json`** — navigation, tabs, API reference, i18n, redirects, and site
  options. See [Navigation](/guides/configuring-navigation).
- **`src/data/site.ts`** — site name, description, links, analytics, and brand.

## The model

| You want to… | Add / edit |
|---|---|
| A new MDX component | `src/mdx/custom-components.tsx` |
| A new page | a file under `src/app/` |
| A server endpoint | `src/app/api/<name>/route.ts` |
| New colors / fonts | `src/data/site.ts`, `src/app/globals.css` |
| Reusable content | `snippets/` |
| Navigation & config | `docs.json`, `src/data/site.ts` |

Everything else is a normal Next.js app — bring any library, integration, or
pattern you already know. Own your stack, extend it freely.