---
title: Customization
description: Extend Thally with custom components, layout tokens, and new pages.
url: http://localhost:3040/customization
---

# Customization

Extend Thally with custom components, layout tokens, and new pages.

Thally is designed to be extended. Every part of the UI is built with composable components and shared layout tokens.

## Layout tokens

Spacing, panel styles, and typography are centralized in `src/config/layout.ts`:

```ts
export const layout = {
  pagePadding: 'px-4 sm:px-6 lg:px-12',
  panel: 'rounded-xl border border-border/40 bg-muted',
}
```

Update these values to restyle the entire shell without touching individual components.

## Adding custom components

Create new components in `src/components/` and use them directly in MDX files. Thally automatically makes common components available in all MDX content.

To register a new MDX component, add it to the components map in `src/components/mdx/mdx-components.tsx`:

```ts
import { MyWidget } from '@/components/mdx/my-widget'

const components: MDXComponents = {
  // ...existing components
  MyWidget: (props) => <MyWidget {...props} />,
}
```

### Built-in MDX components

Full documentation for every component lives in the **Components** tab. A quick reference:

| Component | Purpose |
| --- | --- |
| `` / `<Tip>` / `<Warning>` / `<Info>` | Styled callout blocks |
| `` | Multi-language tabbed code blocks |
| `` / `` | Numbered step-by-step guides |
| `` / `` | Content tabs for platform variants |
| `` / `` | Clickable card grids |
| `<Tile>` / `<TileGroup>` | Larger image-capable feature cards |
| `` | Styled image wrapper with click-to-zoom |
| `` | Collapsible content sections |
| `` | Inline hover tooltip |
| `` | Multi-column layout grid |
| `<Panel>` | Neutral bordered container |
| `<Badge>` | Inline status/version label |
| `<Update>` | Changelog entry block |
| `<Tree>` / `<Folder>` / `<File>` | Interactive file-system tree |
| `<Mermaid>` | Inline Mermaid diagrams |
| `<View>` | Sandboxed iframe embed |
| `<Color>` | Color swatch with hex value |
| `<Prompt>` / `<PromptUser>` / `<PromptAssistant>` | Terminal / AI prompt blocks |
| `<ResponseField>` | API response property documentation |
| `<ParamField>` | API request parameter documentation |
| `<Expandable>` | Collapsible nested property reveal |
| `<RequestExample>` / `<ResponseExample>` | Labeled HTTP request/response code blocks |

## Site configuration options

The `siteConfig` object in `src/data/site.ts` controls many features beyond branding:

| Field | Purpose |
| --- | --- |
| `name` | Site name in header, OG images, and metadata |
| `description` | Default meta description |
| `repoUrl` | Enables "Edit on GitHub" links on every page |
| `links` | Header navigation links (Support, GitHub, CTA) |
| `brand` / `brandPreset` | Color theme for light and dark modes |
| `ogImage` | Customize dynamic OG image colors, fonts, and branding |
| `analytics` | Plug in Google Analytics, Plausible, or PostHog |
| `versions` | Enable the version switcher dropdown in the top bar |

`name`, `description`, `repoUrl`, and the brand/theme fields can also be changed live from the [admin dashboard](/guides/admin-dashboard) — the values in `site.ts` act as the committed defaults.

## Section primitives

Use the built-in layout helpers from `src/components/layout/sections.tsx`:

- **`PageContainer`** — consistent page-level padding
- **`ContentStack`** — vertical spacing for content sections
- **`Panel`** / **`MutedPanel`** — styled card containers

These helpers consume the layout tokens, so changing a token updates every section that uses it.

This is example content that ships with the Thally template. Replace it with your own product documentation.