Essentials

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.

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

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

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 controls how the page appears in autogenerated sidebar groups:

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

Use tableOfContents to hide the page TOC or change which heading levels are shown:

---
title: API Reference
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
---

---
title: Changelog
tableOfContents: false
---

Template

Use template to change the page chrome.

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

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

---
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 <head>. The shape matches Starlight’s HeadConfig entries:

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

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

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

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

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

---
title: Terms
contributors: false
---

The rendered meta area can be replaced with the PageMeta component override.

Edit this page

Last updated Jul 18, 2026