URL: /guides/customization/custom-templates

---
title: Custom page templates
description: Use a different layout for landing pages, API references, or any subset of pages.
icon: "layout-template"
---

# Custom page templates

Set `template:` in frontmatter to render a page through a custom layout:

```md
---
title: Welcome
template: landing
hero:
  headline: Build faster
  subheadline: Markdown in, deployed site out
---
```

Tangly resolves to `<userRoot>/templates/landing.astro` and renders the page through it. The MDX body (the `# Welcome` plus everything after frontmatter) becomes the template's `<slot>`.

## Template props

Templates receive the page context as props:

```ts
interface TemplateProps {
  frontmatter: Frontmatter;       // the page's frontmatter
  manifest: Manifest;             // full manifest for cross-page lookups
  page: PageEntry;                // resolved nav/sidebar/breadcrumb context
}
```

Children (the rendered MDX) come in via `<slot />`.

## Example

```tsx
---
// templates/landing.astro
import Layout from "@tanglydocs/theme-ui/Layout.astro";
import { manifest } from "virtual:tangly/manifest";

export interface Props {
  frontmatter: {
    title?: string;
    hero?: { headline: string; subheadline?: string };
    cta?: { label: string; href: string };
  };
  page: { slug: string; sidebar: any[]; tab?: { slug: string } };
}

const { frontmatter, page } = Astro.props;
---
<Layout
  config={manifest.config}
  page={page}
  navigation={manifest.navigation}
  pageTitle={frontmatter.title ?? "Untitled"}
>
  <section class="hero">
    <h1>{frontmatter.hero?.headline}</h1>
    <p>{frontmatter.hero?.subheadline}</p>
    {frontmatter.cta && (
      <a href={frontmatter.cta.href} class="cta">{frontmatter.cta.label}</a>
    )}
  </section>

  <article>
    <slot />
  </article>
</Layout>
```

## Section-level inheritance

Set `template` on a `_section.mdx` to apply it to every page in that directory subtree:

```md
---
# guides/_section.mdx
template: guide
---
```

Page-level frontmatter overrides section defaults — set `template: standard` on a specific page to opt out of the section template.

## Resolution order

1. `<userRoot>/templates/<name>.astro` — your project template.
2. Built-in template registry (currently empty; reserved for future themes).
3. Fallback to the default page shell with a warning logged.

## Hot reload

Editing a template hot-reloads any page that uses it. Adding or renaming a template invalidates the manifest and triggers a full reload.

## Use cases

- **Landing pages**: hero + CTA + featured grid instead of sidebar + content.
- **API overview**: custom endpoint catalog rendered from `manifest.pages`.
- **Marketing**: full-bleed pages with no chrome (also possible via `mode: custom` frontmatter without writing a template).
- **Status / changelog**: aggregate `changelog/*.mdx` entries into a feed.