---
title: Extend Thally
description: Add custom MDX components, reusable content, branding, and site configuration through supported project files.
url: https://pr-7-a9c4e9fe1b6c.thally.app/guides/extending
---

# Extend Thally

Add custom MDX components, reusable content, branding, and site configuration through supported project files.

Extend a Thally site through the files your project owns. These supported
surfaces stay separate from the framework that renders the site, so normal
updates do not overwrite your content or configuration.

## Add a custom MDX component

Register a React component in `src/mdx/custom-components.tsx`, then use it in
any MDX page.

#### Register the component

```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,
}
```

#### Use it in a page

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

Custom components can accept props, compose built-in MDX components, and use
dependencies installed in your project. Keep secrets and privileged server
operations out of reader-facing components.

## Add pages and reusable content

- Add documentation pages under `src/content/` and register them in
  `docs.json`.
- Put shared MDX fragments in `snippets/` and import them from any page.
- Store public images and downloads in `public/`.

See [Create and edit pages](/guides/writing-content) and [Reuse content with
snippets](/guides/reusable-snippets) for working examples.

## Customize the site

| You want to change | Supported file |
| --- | --- |
| Navigation, tabs, redirects, and optional features | `docs.json` |
| Product name, links, and brand defaults | `src/data/site.ts` |
| Page content and frontmatter | `src/content/**/*.mdx` |
| Custom MDX components | `src/mdx/custom-components.tsx` |
| Shared content | `snippets/` |
| Images, logos, and downloads | `public/` |

Use [Brand and theme](/guides/branding-and-theming),
[Navigation](/guides/configuring-navigation), and the [`docs.json`
reference](/guides/docs-json-reference) before adding custom code. A supported
setting is easier for your team to maintain.

## Stay inside the supported boundary

Application routes, rendering components, and build internals outside the
files above belong to the Thally framework. Do not edit them to add a custom
page, endpoint, or theme. Those changes can be replaced by a framework update
and are not portable across Thally projects.

If the supported extension surfaces do not cover your use case, open a feature
request in the [Thally repository](https://github.com/thallylabs/thally) with
the user outcome you need.

## Verify the extension

Run the local preview and documentation checks:

```bash
npm run dev
npx thally check
npm run build
```

Open every page that uses the extension and verify it on mobile and desktop.