Custom page templates

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

---
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:

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

---
// 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:

---
# 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.