# Frontmatter Define page metadata and navigation behavior with frontmatter. Each docs page starts with frontmatter. Lotus keeps the shape close to Starlight so existing documentation pages are easier to migrate. ```md --- title: Installation description: Install Lotus and register the integration. sidebar: order: 2 --- ``` ## Required fields `title` is required. It becomes the page heading in the docs layout and the default label used by autogenerated sidebar navigation. `description` is optional. It appears under the title and is used as page metadata. ## Slug Use `slug` when the public URL should differ from the file path: ```md --- title: CLI slug: reference/cli --- ``` Without `slug`, Lotus uses the content entry ID. `slug` also affects the generated Markdown source route, so the example above would render at `/docs/reference/cli/` and `/docs/reference/cli.md`. ## Sidebar ownership Page ownership comes from `themeConfig.sidebars`: if a page is listed directly or matched by an autogenerated directory, that top-level sidebar owns the page and appears in the docs subnav. ## Sidebar `sidebar` controls how the page appears in autogenerated sidebar groups: ```md --- title: Configuration sidebar: label: Configure Lotus order: 3 hidden: false --- ``` `sidebar.label` overrides the sidebar label. `sidebar.order` controls sort order; lower numbers appear first. `sidebar.hidden: true` excludes the page from autogenerated groups. The older top-level `order` field is still accepted as a shorthand, but new content should prefer `sidebar.order`. `sidebar.badge`, `sidebar.attrs`, and similar compatibility fields are accepted by the schema, but the current Lotus sidebar UI does not render them yet. ## Table of contents Use `tableOfContents` to hide the page TOC or change which heading levels are shown: ```md --- title: API Reference tableOfContents: minHeadingLevel: 2 maxHeadingLevel: 4 --- ``` ```md --- title: Changelog tableOfContents: false --- ``` ## Template Use `template` to change the page chrome. ```md --- title: Privacy Policy description: How this project handles data. template: text sidebar: hidden: true pagefind: false --- ``` `template: doc` is the default documentation layout with subnav, sidebar, content column, table of contents, page actions, and previous/next links. `template: splash` renders a site header, centered hero, optional hero actions, optional hero visual, content section, and footer. It is intended for home pages, product overview pages, and other pages that introduce a documentation site without the docs sidebar chrome. ```md --- title: Acme Docs description: Documentation for Acme products. template: splash tableOfContents: false hero: title: Acme Docs tagline: Guides, API references, and examples for building with Acme. image: file: /images/docs-preview.png alt: Acme documentation interface actions: - text: Get started link: /docs/overview/ variant: primary icon: lucide:chevron-right - text: API reference link: /docs/reference/ variant: secondary --- ``` `template: text` renders a plain text page with the site header, centered prose, and footer. It is intended for pages like terms, privacy policies, and other standalone legal or informational text. ## Structured data Lotus automatically renders schema.org JSON-LD for docs pages. The generated graph includes `WebSite`, `WebPage`, `TechArticle`, and `BreadcrumbList` data. `title` and `description` are used for page names and summaries, sidebar ownership is used for breadcrumbs and article sections, and `lastUpdated` is used as `dateModified` when it is a date. When `lastUpdated` is omitted, Lotus reads the source file's modification time from the content entry `filePath`. The resolved date is rendered in the page meta area and used for structured data. Use `lastUpdated` to override the file timestamp: ```md --- title: Installation lastUpdated: 2026-07-17 --- ``` Set `lastUpdated: false` to hide the visible timestamp and omit `dateModified`. ## Head Use `head` to add page-specific tags to the document ``. The shape matches Starlight's `HeadConfig` entries: ```md --- title: Open Graph Example head: - tag: title content: Custom browser title - tag: meta attrs: property: og:image content: https://example.com/og.png - tag: script attrs: defer: true src: https://example.com/analytics.js --- ``` Lotus merges these entries with the default page head. Later entries replace matching defaults for: - `title` - `meta` entries with the same `name`, `property`, or `http-equiv` - `link rel="canonical"` - `link rel="sitemap"` Other entries are appended. This means a frontmatter `head` entry can override the generated browser title or description meta tag for one page without replacing the rest of the default metadata. ## Previous and next Lotus generates previous and next links from the current sidebar order. Override them with Starlight-style `prev` and `next` fields: ```md --- title: Installation prev: false next: label: Configure the theme link: /docs/configuration/project/ --- ``` A string changes only the label. `false` hides that side of the pagination. ## Search and drafts Use `pagefind: false` to exclude a page from the generated Lotus search index: ```md --- title: Internal Notes pagefind: false --- ``` The field name is kept for Starlight compatibility. In Lotus, it controls inclusion in the built-in `search.json` output. Use `draft: true` to exclude a page from production builds while keeping it available in development: ```md --- title: Upcoming Feature draft: true --- ``` ## Accepted but not yet rendered Lotus accepts several Starlight-style fields for schema compatibility, but the current UI does not render them yet: - `banner` These fields are safe to keep during migrations, but they should not be treated as active Lotus UI features until the theme starts consuming them. ## Edit Link Lotus can generate edit links from `themeConfig.editLink` by replacing the configured pattern's `{path}` placeholder with the source content path. Use frontmatter `editUrl` only when a page needs to override or disable the generated link. ```md --- title: Overview editUrl: https://github.com/prosefly/astro-theme-lotus/edit/main/src/content/docs/en/overview.mdx --- ``` Set `editUrl: false` to hide the link for a page. The rendered page tools area can be replaced with the `PageAside` component override. ## Contributors When `themeConfig.contributors` is enabled, Lotus infers page contributors from the source file history. Set `contributors: false` on pages that should not show the contributors block. ```md --- title: Terms contributors: false --- ``` The rendered meta area can be replaced with the `PageMeta` component override.