Frontmatter
Per-page MDX frontmatter fields.
~ 2 min read
Frontmatter
Every .mdx file may declare frontmatter at the top:
---
title: My page
description: One-line summary
icon: book
tag: Beta
---
Body starts here. Don't repeat the title as a `# Heading` — `title` already
renders as the page H1.Frontmatter is parsed by gray-matter and validated against @tanglydocs/schema’s FrontmatterSchema. Validation is non-fatal: invalid fields surface as warnings, the page still renders.
Recognized fields
title string path Page title. Falls back to a humanized slug if omitted (guides/my-page → “My Page”). Used in the H1, sidebar entry, browser tab, and OG title. Don’t repeat the title as # Heading or <h1> in the body — tangly dev warns when it finds one.
sidebarTitle string path Override the sidebar entry title only. The H1 still uses title.
description string path Subtitle below the H1. Also used as the meta description and OG description when not overridden by seo.description.
icon string path Lucide or Font Awesome icon name. Shown in the sidebar entry and any cards that link to this page. See Icons for the alias map.
tag string path Small badge in the sidebar (e.g. “Beta”, “New”). Style is theme-dependent.
api string path Manual narrative for an OpenAPI endpoint. Tangly merges this Markdown with the auto-generated endpoint render so you can add prose around the auto-content.
openapi string path Auto-render an OpenAPI endpoint. Format: METHOD path (e.g. GET /users/{id}). Pulls from the spec configured in docs.json#api.openapi.
openapi-schema string path Render a single OpenAPI schema component. Format: #/components/schemas/<Name>.
keywords string[] path Custom meta keywords for SEO.
noindex boolean path Exclude from sitemap.xml, llms.txt, llms-full.txt, and the Pagefind search index. Page is still routable.
mode enum path default: default Page layout mode. One of:
default— sidebar + content + right-rail TOC.wide— sidebar + content (no TOC).center— centered content (no sidebar, no TOC).custom— full-width content (no chrome).
wide, center, and custom hide the right-rail TOC.
draft boolean path Hidden in build, visible in dev with a “Draft” badge. Drafts are also excluded from search and sitemap. Build-time inclusion: TANGLY_INCLUDE_DRAFTS=1 tangly build.
template string path Render through templates/<name>.astro instead of the default page shell. Resolution: <userRoot>/templates/<name>.astro → built-in template registry.
aiContext string path Extra context injected into AI-assistant queries about this page. Reserved for the upcoming chat integration.
lastUpdated boolean | string path Override the auto-derived last-updated stamp. false hides it on this page; an ISO date string (e.g. 2026-04-01) overrides the git timestamp. Default is to inherit footer.lastUpdated from docs.json.
readingTime boolean | number path Override the auto-computed reading-time. false hides it; a number (in minutes) overrides the word-count estimate. Inherits appearance.readingTime when omitted.
editUrl string path Override the edit-on-source URL for this page. Useful when a single page is canonical-sourced from a different repo than the rest of the site.
glossary boolean path default: true Disable glossary auto-linking on this page. Set to false to skip term highlighting (typically on the glossary page itself).
---
title: Release notes
lastUpdated: false
readingTime: 3
editUrl: https://github.com/owner/notes/edit/main/RELEASES.md
glossary: false
---seo object path Per-page SEO override.
title: string— overrides the OG/meta title.description: string— overrides the meta description.ogImage: string— custom Open Graph image URL.
Custom fields
FrontmatterSchema uses passthrough() — unknown fields are preserved and forwarded to the active template via frontmatter. This is how custom landing-page templates consume hero, cta, headline, etc.
---
title: Welcome
template: landing
hero:
headline: Build faster
subheadline: Markdown in, deployed site out
cta:
label: Start now
href: /quickstart
---The landing template reads frontmatter.hero and frontmatter.cta directly.
Strict parsing
import { parseFrontmatter, safeParseFrontmatter } from "@tanglydocs/schema";
const fm = parseFrontmatter(rawObject);
const result = safeParseFrontmatter(rawObject);