{"items":[{"title":"Configuration","description":"Reference Lotus theme configuration fields, defaults, and related docs.","href":"/docs/references/configuration/","slug":"references/configuration","section":"References","excerpt":"This reference lists top-level defineLotusConfig() fields. Use the linked configuration pages for examples and behavior details. Options Field Default See --- --- --- name 'Documen...","content":"This reference lists top-level defineLotusConfig() fields. Use the linked configuration pages for examples and behavior details. Options Field Default See --- --- --- name 'Documentation' Project description 'Project documentation.' Project logo built-in Lotus mark Project favicon none Project appearance accent: 'indigo' , gray: 'neutral' , defaultMode: 'system' , radius: 'medium' Appearance docsBase '/' Content Routing defaultLocale first configured locale Internationalization locales none Internationalization ui built-in English messages Internationalization navbar one Docs link Navbar socials Navbar themeModeControl 'segmented-control' Appearance sidebars Sidebars footer empty copyright and sections Footer search provider: 'local' Search assistant false Assistant llms true Content Routing pageActions copy, Markdown, ChatGPT, Claude Page Actions source inferred when possible Source editLink hidden Source contributors false Source components Overriding Components credits true Footer iconify default Iconify API, scan enabled Integrations markdown all transforms enabled, Expressive Code defaults Integrations Helper Use defineLotusConfig() for type inference:"},{"title":"CSS & Styling","description":"Customize Lotus with semantic tokens and scoped CSS.","href":"/docs/customization/css-styling/","slug":"customization/css-styling","section":"Guides","group":"Customization","excerpt":"Lotus styles are built on Tailwind utilities and semantic CSS variables. The theme exposes --lotus- tokens for layout and shell styling, while shared MDX components consume portabl...","content":"Lotus styles are built on Tailwind utilities and semantic CSS variables. The theme exposes --lotus- tokens for layout and shell styling, while shared MDX components consume portable --pl- variables. Theme tokens Use appearance for normal color and radius customization: Use semantic tokens only when a project needs lower-level CSS overrides for surfaces, text, or component geometry. Component bridge Lotus maps component package variables to theme variables: This keeps @prosefly/astro-components portable while letting Lotus own the site palette."},{"title":"Frontmatter","description":"Define page metadata and navigation behavior with frontmatter.","href":"/docs/essentials/frontmatter/","slug":"essentials/frontmatter","section":"Guides","group":"Essentials","excerpt":"Each docs page starts with frontmatter. Lotus keeps the shape close to Starlight so existing documentation pages are easier to migrate. Required fields title is required. It become...","content":"Each docs page starts with frontmatter. Lotus keeps the shape close to Starlight so existing documentation pages are easier to migrate. 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: 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: 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: Template Use template to change the page chrome. 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. 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: 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: 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: 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: 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: 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. 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. The rendered meta area can be replaced with the PageMeta component override."},{"title":"Icon","description":"Render inline Iconify SVG icons from a prefix and icon name.","href":"/docs/components/icon/","slug":"components/icon","section":"Components","excerpt":"Icon renders an inline SVG from Iconify data. Pass a full Iconify name in the prefix:icon format, such as lucide:star or simple-icons:github . Import Inline Usage Icons are inline...","content":"Icon renders an inline SVG from Iconify data. Pass a full Iconify name in the prefix:icon format, such as lucide:star or simple-icons:github . Import Inline Usage Icons are inline by default and inherit the surrounding text size when size , width , and height are omitted. Favorite this page GitHub links often appear next to repository metadata, external resources, or social links. Sizing Use size to set width and height together. Use width and height only when the icon intentionally needs a non-square box. 1em 18px inherited Accessible Icons Decorative icons are hidden from assistive technology by default. Add title when the icon itself communicates meaning without adjacent text. This icon has an accessible title. If visible text already explains the icon, leave title unset. Icon Sources Icon loads data from the Iconify API during server rendering or static build. Builds therefore need network access unless you provide an internal Iconify-compatible API endpoint with apiBase . When the Lotus integration is installed, it preloads static icon usage in Astro and MDX files and groups requests by Iconify prefix. For example, lucide:star , lucide:search , and lucide:copy can be fetched through one lucide request. Icons that cannot be detected statically still fall back to an individual API request. Props Prop Type Default Notes --- --- --- --- name string required Iconify name such as lucide:star . title string optional Adds an accessible SVG title and role=\"img\" . size string \\ number 1em Sets width and height together. width string \\ number size Overrides SVG width. height string \\ number size Overrides SVG height. class string optional Adds classes to the rendered SVG. focusable string 'false' Sets the SVG focusable attribute. apiBase string 'https://api.iconify.design' Iconify-compatible API endpoint. Unknown attributes are passed to the rendered SVG. Syntax Rules - Use the full prefix:icon Iconify name. - Keep icons inline with text unless a surrounding component handles layout. - Add title only when the icon has standalone meaning. - Prefer consistent icon families within the same UI region."},{"title":"Migrations","description":"Move existing documentation sites to Lotus.","href":"/docs/migrations/","slug":"migrations","excerpt":"Migration guides are source-specific. Use them when an existing documentation site already has content and navigation, but needs to move its routing, theme configuration, and MDX c...","content":"Migration guides are source-specific. Use them when an existing documentation site already has content and navigation, but needs to move its routing, theme configuration, and MDX components to Lotus. Move Starlight content, frontmatter, sidebars, i18n directories, and MDX component usage into Lotus."},{"title":"Overview","description":"Learn what Lotus provides and how the documentation theme is organized.","href":"/docs/overview/","slug":"overview","section":"Guides","group":"Getting Started","excerpt":"Lotus is an installable documentation theme for Astro v7, Tailwind CSS v4, and MDX. It provides the page shell, docs route, navigation model, theme tokens, and shared MDX component...","content":"Lotus is an installable documentation theme for Astro v7, Tailwind CSS v4, and MDX. It provides the page shell, docs route, navigation model, theme tokens, and shared MDX components needed to start a project documentation site without rebuilding the chrome from scratch. What Lotus includes Render a responsive header, docs subnav, sidebar, article layout, table of contents, page metadata, and footer from theme configuration. Generate docs pages, Markdown source routes, search indexes, localized URLs, and route-prefixed docs from Astro content collection entries. Use the built-in client-side search dialog and generated JSON index, or replace the search UI with a component override. Configure accent colors, gray scales, radius, color mode, fonts, and lower level CSS tokens for deeper styling control. Compose pages with callouts, cards, steps, tabs, accordions, file trees, badges, and Iconify icons from @prosefly/astro-components . Replace shell slots such as search, navbar, page header, page actions, contributors, and previous or next navigation when configuration is not enough. How the docs tree works Lotus reads MDX entries from the docs content collection, then injects page, Markdown source, and search routes under docsBase . With the default docsBase: '/' , Lotus generates: - / and nested docs pages - / .md Markdown source routes - /search.json search index data The sidebars config decides which sidebar and subnav section owns each page. For locale directories, route prefixes, and fallback behavior, see Internationalization. For loader base, docsBase, and slug behavior, see Content Routing. First steps 1. Install the theme. Add Lotus, then register the integration in astro.config.ts . Install @prosefly/astro-components directly when your own content imports shared MDX components. Install Lotus 2. Configure routes and locales. Decide where docs are mounted and how localized content directories map to public URLs. Review content routing 3. Build the docs shell. Set project identity, appearance, navbar links, sidebars, footer links, page actions, and search behavior. Configure the project 4. Write content. Add frontmatter, Markdown, images, code blocks, and shared MDX components to replace the demo pages with project documentation. Review authoring essentials 5. Customize when configuration is not enough. Use CSS tokens for visual changes and component overrides for shell markup or behavior changes. Customize Lotus"},{"title":"Project","description":"Configure site identity, logo assets, and favicon links.","href":"/docs/configuration/project/","slug":"configuration/project","section":"Guides","group":"Getting Started","excerpt":"Project settings describe the documentation site itself. Keep this page for identity fields that affect metadata, branding, and browser chrome. Routing, i18n, source links, and con...","content":"Project settings describe the documentation site itself. Keep this page for identity fields that affect metadata, branding, and browser chrome. Routing, i18n, source links, and contributors are separate configuration topics. See Content Routing, Internationalization, and Source. Name name is the public product or project name. Lotus uses it for the site title, header brand text, footer brand text, and schema.org metadata. Page titles are composed from the page frontmatter title and this name. Description description is the default site description. Pages can still override it with frontmatter. Lotus uses this value for the default and structured data. Logo logo is optional. If it is omitted, Lotus renders the built-in Lotus mark. By default, Lotus treats the logo as a mark and renders it next to name . Use a string when one mark asset works in every theme mode. Use an object when light and dark mode need different mark assets. If your logo asset already includes the project name, set variant: 'lockup' . Lotus will render the image by itself and skip the extra name text. The default variant is mark . href controls the brand link target. If omitted, the brand links to / . For local assets in public/ , Lotus reads the image dimensions during the Astro config setup step and renders width and height attributes automatically. Add width and height only for remote logo URLs or custom paths Lotus cannot read from public/ . Favicon Use a string for the common single favicon case. Use an object or array when a project needs multiple favicon links. Each object renders as a in the document head. Supported fields are href , rel , type , sizes , media , and color ."},{"title":"Badge","description":"Add compact inline labels for status, metadata, and version hints.","href":"/docs/components/badge/","slug":"components/badge","section":"Components","excerpt":"Badge is an inline label. Use it inside prose, headings, cards, and compact UI where a short status or metadata value needs to sit next to surrounding text. Import Inline Usage Bad...","content":"Badge is an inline label. Use it inside prose, headings, cards, and compact UI where a short status or metadata value needs to sit next to surrounding text. Import Inline Usage Badges are designed to stay on the same baseline as text. They should not create a new layout section on their own. Lotus components are published from @prosefly/astro-components New , and can be used independently from the Lotus theme Stable . Common Patterns Use badges for short labels that support nearby content. Status The search dialog Ready supports keyboard navigation, while page actions Experimental may change before the first release. Version Hints Install Lotus with Astro v7 and Tailwind CSS v4 . Heading Metadata Package Exports Public API The package exports components from @prosefly/astro-components through a single entrypoint. Variants Use variant to change the visual weight of the badge. Solid Soft Subtle Outline Colors Use semantic colors when the badge communicates state. Use neutral for plain metadata. Neutral Accent Success Warning Danger Props Prop Type Default Notes --- --- --- --- variant 'solid' \\ 'soft' \\ 'subtle' \\ 'outline' 'soft' Selects the visual treatment. color 'neutral' \\ 'accent' \\ 'success' \\ 'warning' \\ 'danger' 'neutral' Selects the semantic color. class string optional Adds classes to the outer span . Badge also passes unknown attributes to the outer span , so you can add attributes such as title , aria-label , or data- when needed. Syntax Rules - Keep badge text short, usually one to three words. - Use badges inline with nearby text instead of as standalone blocks. - Do not use badges as buttons or navigation controls. - Prefer soft or subtle for documentation content; reserve solid for high-emphasis status labels."},{"title":"Content Routing","description":"Configure docsLoader, docsSchema, docsBase, slugs, and generated routes.","href":"/docs/configuration/content-routing/","slug":"configuration/content-routing","section":"Guides","group":"Getting Started","excerpt":"Lotus routes are built from two inputs: - The content collection entry IDs produced by docsLoader - The public route prefix configured with docsBase Keep routing decisions here. Lo...","content":"Lotus routes are built from two inputs: - The content collection entry IDs produced by docsLoader - The public route prefix configured with docsBase Keep routing decisions here. Locale directories and UI translation behavior are covered in Internationalization. Collection Setup The default loader reads MDX files from src/content/docs : Without i18n, src/content/docs/installation.mdx has the entry ID installation , and src/content/docs/components/icon.mdx has the entry ID components/icon . - src - content - docs - index.mdx / - installation.mdx /installation/ - components - icon.mdx /components/icon/ For localized docs, locales. .directory is relative to src/content/docs . It strips the locale directory before Lotus matches sidebar string items and autogenerated directories. See Internationalization. Custom Loader Base docsLoader() defaults to src/content/docs , but it still accepts base when you intentionally want a different collection root. With this setup, src/content/docs/en/installation.mdx has the entry ID docs/en/installation , while src/content/index.mdx has the entry ID index . For most sites, keep the default loader and create non-docs pages with Astro's normal src/pages routing. Docs Base docsBase controls where Lotus injects the page, Markdown, and search routes. The default is / , matching Starlight's route model: src/content/docs is the content collection root, not a public URL prefix. With the default docsBase: '/' and the default loader: Entry ID Page URL Markdown URL --- --- --- index / /index.md installation /installation/ /installation.md components/icon /components/icon/ /components/icon.md The search index follows the same base. With the default route base, it is available at /search.json . Set docsBase when the project also has a marketing site, app routes, or other pages outside the documentation. With docsBase: '/docs' and the default loader: Entry ID Page URL Markdown URL --- --- --- index /docs/ /docs/index.md installation /docs/installation/ /docs/installation.md components/icon /docs/components/icon/ /docs/components/icon.md The prefixed search index is /docs/search.json . LLMs Files Lotus generates /llms.txt by default. It lists the default locale docs as Markdown links, grouped by sidebar section. Disable the route with: Generate a full-text companion at /llms-full.txt with: /llms.txt and /llms-full.txt are site-level discovery files, so they do not move under docsBase . Site Homepage The docs collection index entry always renders at the current docsBase . With the default docsBase: '/' , src/content/docs/index.mdx is the site homepage. With docsBase: '/docs' , the same entry renders at /docs/ . For a custom marketing homepage, keep the site homepage outside the docs collection and create it with Astro's normal file-based routing. You can reuse Lotus page primitives on custom pages: For a docs-only site, keep the default docsBase: '/' and put the docs homepage at src/content/docs/index.mdx . - src - content - docs - index.mdx docs homepage at / - installation.mdx /installation/ Slug Overrides Use frontmatter slug when a page needs a public path that differs from its entry ID: With docsBase: '/docs' , that page renders at /docs/reference/cli/ and /docs/reference/cli.md . Slug overrides affect public URLs. Sidebar ownership still depends on entry IDs, so sidebars should reference the content entry, not the slug override. Schema Extensions Use docsSchema( extend ) when a project needs additional frontmatter fields: The extension is merged into the base Lotus docs schema. Existing Lotus fields such as title , sidebar , tableOfContents , template , pagefind , and draft remain available."},{"title":"Design System","description":"Understand the design model behind Lotus.","href":"/docs/references/design-system/","slug":"references/design-system","section":"References","excerpt":"Lotus uses a compact design system for documentation sites. It is intentionally token-driven, but the public configuration stays small: users choose the accent, neutral scale, colo...","content":"Lotus uses a compact design system for documentation sites. It is intentionally token-driven, but the public configuration stays small: users choose the accent, neutral scale, color mode, and radius, while the theme derives the rest. This keeps common customization simple and leaves advanced brand work to CSS token overrides. Layers Lotus has three design layers: 1. Tailwind provides layout utilities, responsive behavior, and base color scales. 2. Lotus maps those primitives into semantic --lotus- tokens for the docs shell, prose, and layout. 3. Shared MDX components read portable --pl- tokens, which Lotus maps to the active Lotus theme. The important boundary is that application layout belongs to Lotus, while MDX components stay portable enough to work outside this theme. Appearance The public appearance API controls theme direction. These settings become document attributes: Config Attribute Purpose --- --- --- accent data-accent=\"indigo\" Selects the interactive color family. gray data-gray=\"neutral\" Selects the neutral color family. defaultMode data-theme=\"system\" Selects light, dark, or system mode. radius data-radius=\"medium\" Selects the shared shape scale. background and text are not separate appearance fields. They are derived from the chosen gray scale and color mode, along with surface , borders, code colors, muted text, and heading text. Allowing them to be configured independently would make contrast and dark mode harder to reason about. Color Strategy Lotus uses semantic color names in components instead of raw palette steps. Components ask for roles such as background, surface, text, border, and accent. The selected appearance decides what those roles mean in light and dark mode. The neutral scale is selected with appearance.gray . The accent scale is selected with appearance.accent . Built-in accent colors use Tailwind color steps; custom hex accents are converted into light and dark OKLCH values. The result is a stable component API: Shape Radius is global, but components can cap it when a full radius would damage the shape. Buttons, badges, and small controls can follow radius: 'full' ; larger surfaces such as dropdowns, cards, tabs, and code blocks use capped values so they remain readable. This gives the site a consistent shape language without making every component look like a pill. Typography Lotus does not load web fonts by default. It exposes font tokens and starts with system font stacks. Projects that want Inter, JetBrains Mono, or a brand font can load those fonts in their app and override the font tokens. Typography inside Markdown is styled through .lotus-prose . That layer controls the reading rhythm, heading scale, lists, tables, blockquotes, footnotes, code, and common inline HTML elements such as kbd , mark , and abbr . Layout The docs shell uses fixed layout tokens for the sticky header, subnav, sidebar, main content column, and table of contents. Content width is a theme decision, not something authors should tune per Markdown page. This is why prose width, sidebar width, and TOC width live in theme tokens rather than frontmatter. Customization Use appearance for normal theme choices: - Accent color. - Neutral gray family. - Initial color mode. - Radius style. Use CSS token overrides for brand-level control. When overriding core colors, treat background , surface , text , muted text , borders, and code colors as a set. Changing only one of them usually creates contrast or dark mode issues. For the complete token API, see Theme Tokens."},{"title":"Installation","description":"Start a Lotus documentation site from the starter template or add Lotus to an existing Astro project.","href":"/docs/installation/","slug":"installation","section":"Guides","group":"Getting Started","excerpt":"Start from the Lotus starter template for a new documentation site, or install Lotus manually when you already have an Astro project. Starter Template Use the starter when you want...","content":"Start from the Lotus starter template for a new documentation site, or install Lotus manually when you already have an Astro project. Starter Template Use the starter when you want the fastest path to a working site. The template source is available at prosefly/astro-template-lotus-starter. After the site is running, replace the example content and update src/theme.config.ts with your project name, navigation, sidebar structure, appearance, footer, and source repository. Manual Setup Use manual setup when your project already exists or when you want to introduce Lotus one piece at a time. 1. Install Lotus. Add the theme package to your Astro project. Install @prosefly/astro-components directly when your own MDX or Astro files import shared components such as cards, steps, tabs, callouts, badges, or file trees. 2. Register the integration. Configure Astro with the Lotus integration. 3. Create the theme config. Start with project identity and a minimal sidebar. Set docsBase: '/docs' when the Astro project already has a site home page and docs should live under /docs/ . 4. Register the docs collection. Create src/content.config.ts and use the loader and schema from Lotus. 5. Add the first docs page. Lotus reads from src/content/docs by default. 6. Start development. Next Steps - Review Project Configuration to define the site identity, navigation, sidebars, footer, and source repository. - Review Content Routing before moving docs under a route prefix or changing the docs loader base. - Run pnpm check before shipping changes. It validates content collections, MDX imports, Astro components, and TypeScript."},{"title":"Markdown Syntax","description":"Reference the core Markdown patterns supported inside Lotus docs.","href":"/docs/essentials/markdown-syntax/","slug":"essentials/markdown-syntax","section":"Guides","group":"Essentials","excerpt":"Lotus uses Astro content collections and MDX, so standard Markdown remains the default authoring format for most docs pages. Headings Use headings to create page structure and tabl...","content":"Lotus uses Astro content collections and MDX, so standard Markdown remains the default authoring format for most docs pages. Headings Use headings to create page structure and table-of-contents anchors. Add a custom heading ID when a translated or edited heading needs a stable URL hash. Lotus removes the marker from the rendered heading, uses manual-setup for the heading id , and keeps table-of-contents links in sync. Do not add a top-level Heading at the start of the MDX body. Lotus renders the page title from frontmatter in the layout. Paragraphs Separate paragraphs with a blank line. Line breaks inside a paragraph are collapsed by default. Use a blank line when you want a new paragraph. Emphasis Use emphasis for inline stress and strong emphasis for important terms. Links Use inline links for most references. Reference-style links are useful when the same URL appears repeatedly. Images Images use the same bracket syntax as links, with a leading ! . Use meaningful alt text. If the image is decorative, keep the alt text empty. See Images for galleries, figures, captions, raw img , and iframe embeds. Lists Unordered lists use - , , or + . Lotus examples prefer - . Ordered lists use numbers. Nested lists are indented by two or four spaces. Task Lists Task lists are supported through GitHub Flavored Markdown. Blockquotes Use blockquotes for quoted material or important contextual notes. Inline Code Use backticks for inline code, commands, file names, and identifiers. Code Blocks Use fenced code blocks for longer snippets. Add a language name when possible. ts Lotus uses Expressive Code for fenced code blocks by default. See Code Blocks for titles, highlighted lines, copy buttons, package-manager tabs, and configuration. Tables Tables are supported for compact reference material. Horizontal Rules Use a horizontal rule to separate large sections. Escaping Characters Use a backslash when Markdown punctuation should render literally. Raw HTML And MDX MDX allows HTML elements and imported Astro components in the same file. Prefer Markdown syntax for prose and MDX components for reusable UI patterns."},{"title":"Project Structure","description":"Choose a Lotus project layout based on routing, localization, and customization needs.","href":"/docs/recipes/project-structure/","slug":"recipes/project-structure","section":"Recipes","excerpt":"Lotus does not require one fixed directory layout. Start with the smallest structure that matches the site, then add locale, custom pages, or override folders only when the project...","content":"Lotus does not require one fixed directory layout. Start with the smallest structure that matches the site, then add locale, custom pages, or override folders only when the project needs them. Docs Only Use this for a documentation-only site where every page lives under the docs route. - astro.config.ts registers the Lotus integration - src - content.config.ts registers the docs collection - theme.config.ts stores Lotus theme config - content - docs - index.mdx docs homepage - overview.mdx - installation.mdx - configuration - project.mdx - public - favicon.svg Keep the default loader base and the default docsBase: '/' . Docs At Root Use this for a documentation-only site. It matches Lotus defaults and does not need an explicit docsBase . - astro.config.ts registers the Lotus integration - src - content.config.ts registers the docs collection - theme.config.ts uses the default docsBase: '/' - content - docs - index.mdx homepage at / - installation.mdx - components - icon.mdx - public - favicon.svg With this setup, installation.mdx renders at /installation/ , and its Markdown route is /installation.md . Homepage + Docs Use this when the site needs a top-level marketing or product homepage at / and documentation under /docs . - astro.config.ts registers the Lotus integration - src - content.config.ts registers the docs collection - theme.config.ts sets docsBase: '/docs' - pages - index.astro site homepage at / - content - docs - index.mdx docs homepage at /docs/ - overview.mdx - installation.mdx - public - logo.svg - favicon.svg This structure keeps docsLoader() focused on src/content/docs . Use the exported Lotus layouts when the custom homepage should share the same header, footer, tokens, and theme initialization as the docs pages. Localized Docs Use this when each locale has its own content directory. - src - content.config.ts registers the docs collection - theme.config.ts maps locale directories - content - docs - en - index.mdx - overview.mdx - configuration - project.mdx - zh-cn - index.mdx - overview.mdx - configuration - project.mdx Sidebar strings stay locale-neutral. Reference configuration/project , not en/configuration/project . With Overrides Use this when the project replaces shell components or adds local UI around the Lotus theme. - src - content.config.ts - theme.config.ts references local override paths - content - docs - index.mdx - overview.mdx - components - lotus - HeaderSocialIcons.astro - PageActions.astro - SearchDialog.astro - styles - lotus.css optional custom CSS tokens - public - logo.svg - favicon.svg Keep local overrides outside src/content so content remains portable and route-focused. 1. Pick the route model first. Decide whether docs live under /docs or / , and whether the site has a separate homepage. 2. Add locale directories only when translations exist. A single-language site can use src/content/docs . A localized site should move pages under directories such as src/content/docs/en and src/content/docs/zh-cn . 3. Keep content, theme config, and overrides separate. Put content in src/content , site configuration in src/theme.config.ts , and local shell overrides in src/components . See Content Routing and Internationalization for route and locale behavior."},{"title":"Starlight","description":"Move existing Starlight content into Lotus with compatible frontmatter and MDX patterns.","href":"/docs/migrations/starlight/","slug":"migrations/starlight","section":"Guides","group":"Migrations","excerpt":"Use this migration when an existing Astro Starlight site already has docs content, localized directories, sidebar configuration, and Starlight MDX components. Lotus keeps several a...","content":"Use this migration when an existing Astro Starlight site already has docs content, localized directories, sidebar configuration, and Starlight MDX components. Lotus keeps several authoring patterns close to Starlight: frontmatter fields, Steps , FileTree , localized directories, and sidebar-style content organization. The main migration work is moving configuration into Lotus and replacing Starlight-specific component imports. 1. Move content into the Lotus docs collection. Register docsLoader() and docsSchema() in src/content.config.ts . 2. Keep compatible frontmatter. Fields such as title , description , slug , sidebar , tableOfContents , prev , next , pagefind , and draft are accepted. 3. Rebuild sidebars in theme.config.ts . Lotus owns sidebar structure from themeConfig.sidebars . Use string items, groups, links, and autogenerate.directory entries. 4. Replace Starlight-only components. Use @prosefly/astro-components for Steps , FileTree , Tabs , cards, callouts, accordions, badges, and icons. 5. Configure i18n explicitly. Use locales and defaultLocale to map locale directories to public route prefixes. See Frontmatter for accepted page fields and Sidebars for navigation structure. AI-assisted Migration Prompt Use this prompt with Codex or another code-aware AI assistant when you want it to migrate an existing Starlight project automatically. Run it from the project root so the assistant can inspect package.json , Astro config, content collections, docs files, and theme configuration. Treat the AI output as a migration draft. Review the diff, run the checks, and verify the site locally before publishing. After the AI finishes, compare its changes with the Lotus pages for Content Routing, Internationalization, Sidebars, and Overriding Components."},{"title":"Theme Components","description":"Reuse public Lotus theme components inside local overrides.","href":"/docs/customization/theme-components/","slug":"customization/theme-components","section":"Guides","group":"Customization","excerpt":"Lotus exports composable theme components from @prosefly/astro-theme-lotus/components . Use them when an override should wrap or rearrange the default behavior instead of replacing...","content":"Lotus exports composable theme components from @prosefly/astro-theme-lotus/components . Use them when an override should wrap or rearrange the default behavior instead of replacing it from scratch. These exports come from Lotus' components/theme layer. They are reusable building blocks, not the internal page chrome. Lotus does not export components/layout , components/defaults , or components/ui . For custom Astro pages that need a full page shell, use @prosefly/astro-theme-lotus/layouts instead. See Page Layouts. An override slot and a public component can have different names. For example, the shell slot is HeaderNavbar , while the reusable public component is NavbarLinks . Public Exports Export Purpose --- --- AppearancePalette Complete appearance palette control. AppearancePaletteContent Palette popover content without the trigger wrapper. Assistant Hosted assistant widget loader. AssistantTrigger Ask AI trigger button shown near search. CodeBlock Static Shiki-highlighted code block for custom pages. Contributors Contributors block below docs content. Credits Built with Lotus footer credit. EditThisPage Edit link used by the page aside. FooterLinks Footer link sections rendered from footer.sections . LanguageSelect Locale selector for configured locales. LotusMark Built-in Lotus logo mark. NavbarLinks Header navbar links and action buttons. PageActions Copy, Markdown, and assistant page actions. PageAside Right sidebar content with table of contents and edit link. PageHeader Page title area with description and actions. PageMeta Last updated and contributors area below docs content. PageNavigation Previous and next page links. SearchDialog Complete search trigger and dialog. SearchDialogContent Search dialog body and client behavior. SearchDialogTrigger Search trigger buttons. SiteBrand Brand logo link. SocialIcons Social icon list. ThemeModeButton Icon button for cycling or selecting theme mode. ThemeModeSegmentedControl Segmented light, dark, and system control. ThemeModeSelect Select control for theme mode. ThemeModeSwitch Default header theme control. These exports are package-level building blocks. The theme shell imports override points through internal virtual modules, so importing public components inside an override does not recursively import the override file. Use the public export when you want the package implementation: Use the virtual module only when one override needs to call another override slot and preserve the user's configured replacement: Wrapping Search Use the smaller search components when the trigger and dialog content need to live in different places: Wrapping Page Actions Use this pattern when a project wants a different container or placement while keeping the default copy, Markdown, ChatGPT, and Claude behavior. Highlighting Code Use CodeBlock on custom Astro pages that are not rendered from Markdown. Markdown fenced code blocks still use the configured Markdown and Expressive Code pipeline. Reusing Theme Mode Controls All theme mode controls use the same lotus-theme local storage key and update the document data-theme attribute. Pair With Overrides Use the components configuration to replace shell-owned slots: Slot names are configured with names like HeaderNavbar and HeaderSocialIcons . Public imports use names like NavbarLinks and SocialIcons . See Overriding Components for the complete override list and path resolution rules."},{"title":"Admonitions","description":"Author notes, tips, warnings, and danger messages with Markdown directives.","href":"/docs/essentials/admonitions/","slug":"essentials/admonitions","section":"Guides","group":"Essentials","excerpt":"Use admonitions when a short block of content needs to stand out from normal prose without switching to component syntax. Lotus supports Markdown directives for note , tip , warnin...","content":"Use admonitions when a short block of content needs to stand out from normal prose without switching to component syntax. Lotus supports Markdown directives for note , tip , warning , caution , and danger . The directives render through the same callout system used by the Callout component. Basic Syntax Use three colons, the admonition type, an optional title in brackets, then close the block with another three colons. :::tip Use the starter template Start with the starter when you want the fastest path to a working docs site. ::: Types Choose the type that matches the intent of the message. :::note Note Use notes for neutral context, implementation details, and caveats. ::: :::tip Tip Use tips for recommended workflows, shortcuts, and smoother paths through a task. ::: :::warning Warning Use warnings when a choice can cause confusing behavior, broken output, or extra setup work. ::: :::danger Danger Use danger messages for destructive actions, security-sensitive steps, and irreversible changes. ::: Starlight Compatibility Lotus also accepts caution for Starlight compatibility. It renders as a warning-style admonition. :::caution Check before deploying Review environment variables before publishing the site. ::: When To Use Components Use directives for normal documentation prose. Use the Callout component when a page already uses MDX components or when you need component props directly."},{"title":"Callout","description":"Highlight notes, tips, warnings, and destructive guidance inside documentation.","href":"/docs/components/callout/","slug":"components/callout","section":"Components","excerpt":"Use Callout when a paragraph needs more attention than normal prose but should still stay inside the reading flow. For Markdown directive syntax such as :::tip , see Admonitions. I...","content":"Use Callout when a paragraph needs more attention than normal prose but should still stay inside the reading flow. For Markdown directive syntax such as :::tip , see Admonitions. Import Basic Usage When title is omitted, the callout renders as a compact inline message with an icon and body content. When using a hosted coding plan, follow the tutorial before configuring a dedicated endpoint. With Title Add title when the message needs a short heading. The icon and title share the first row, while the content appears below. The note variant is a safe default for implementation details, caveats, and editorial guidance. Variants Use type to match the intent of the message. Use notes for neutral context, implementation details, and caveats that do not require immediate action. Use tips for recommended workflows, shortcuts, or patterns that help readers complete a task more smoothly. Use warnings when a choice can cause confusing behavior, broken output, or additional setup work. Use danger callouts for destructive actions, security-sensitive steps, or irreversible changes. Rich Content Callouts accept normal MDX content. Include the smallest working command first: Then explain optional configuration after the command. Props Prop Type Default Notes --- --- --- --- title string none Optional heading shown above the body content. type 'note' \\ 'tip' \\ 'warning' \\ 'danger' 'note' Changes the icon, color, border, and background treatment. Behavior Callouts are static content containers. They do not collapse, dismiss, or add client-side behavior."},{"title":"Internationalization","description":"Configure locale directories, localized routes, fallbacks, and UI translations.","href":"/docs/configuration/i18n/","slug":"configuration/i18n","section":"Guides","group":"Getting Started","excerpt":"Lotus follows Starlight's i18n model: each locale has a key, a label, a language tag, an optional text direction, and a content directory. The special root locale renders without a...","content":"Lotus follows Starlight's i18n model: each locale has a key, a label, a language tag, an optional text direction, and a content directory. The special root locale renders without a locale prefix. The root locale is the default unprefixed locale. It renders at /docs/... , not /docs/root/... . With the default docsLoader() , this config makes English files live in src/content/docs/en/ while rendering at /docs/overview/ . Simplified Chinese files live in src/content/docs/zh-cn/ and render at /docs/zh-cn/overview/ . - src - content - docs - en - index.mdx /docs/ - overview.mdx /docs/overview/ - zh-cn - index.mdx /docs/zh-cn/ - overview.mdx /docs/zh-cn/overview/ Locale Keys And Prefixes Locale keys control route prefixes. root has no prefix; every other key is used as the first segment after docsBase . Locale key Directory Page URL --- --- --- root en /docs/overview/ zh-cn zh-cn /docs/zh-cn/overview/ Use lowercase locale keys for predictable URLs. Use lang for the HTML language tag when the browser-facing value needs casing such as zh-CN . Lotus sets the page from each locale. If dir is omitted, common RTL language codes such as ar , fa , he , and ur are inferred from lang or the locale key. Set dir explicitly when a locale needs to override that default. Directory Mapping locales. .directory strips the locale directory before Lotus matches sidebar string items and autogenerate.directory values. For example, src/content/docs/en/configuration/project.mdx and src/content/docs/zh-cn/configuration/project.mdx are both referenced as configuration/project in sidebars . - docs - en - configuration - project.mdx referenced as configuration/project - zh-cn - configuration - project.mdx referenced as configuration/project See Content Routing for the full route generation model. Fallbacks If a non-default locale does not include a page, Lotus can fall back to the default locale entry. This keeps partially translated sites navigable while translations are still in progress. Fallback pages keep the target locale route, but source-aware features such as edit links and contributors still point to the source file that actually rendered. See Source for source path behavior. UI Translations Lotus includes template translations for common documentation site locales. These strings cover shell UI such as search, theme mode controls, table of contents, page actions, edit links, mobile docs navigation, and the 404 page. Built-in messages currently cover: Locale Language --- --- en English zh-cn Simplified Chinese zh-tw Traditional Chinese ja Japanese ko Korean fr French de German es Spanish pt-br Brazilian Portuguese it Italian ru Russian ar Arabic Use ui to override built-in strings for a locale. Keys can match either the locale key or the locale language code. Custom locales fall back to the default locale and then to English. Config Labels Labels written in theme.config.ts are project content, not built-in UI messages. Add translations next to the label when the same config item should render differently per locale. The same pattern is supported by navbar items, social links, sidebar sections, sidebar groups, and sidebar link items. Page links generated from content use the localized page frontmatter instead. Translator API Lotus provides the resolved translator as Astro.locals.t for theme components and local overrides. The translator follows Starlight's shape. Use t(key, values) to render a string, t.all() to read the resolved UI dictionary, t.exists(key) to check whether a key exists, t.dir() to get the current locale's text direction, and t.locale() to read the resolved Lotus locale object."},{"title":"Overriding Components","description":"Replace Lotus shell components when a project needs custom behavior.","href":"/docs/customization/overriding-components/","slug":"customization/overriding-components","section":"Guides","group":"Customization","excerpt":"Component overrides replace specific pieces of the Lotus documentation shell. Use them when configuration and CSS tokens are not enough because the rendered markup, placement, or b...","content":"Component overrides replace specific pieces of the Lotus documentation shell. Use them when configuration and CSS tokens are not enough because the rendered markup, placement, or behavior needs to change. Overrides are configured in src/theme.config.ts through the components object: Paths are resolved from the project root. They can be relative paths like ./src/components/lotus/SearchDialog.astro or absolute file-system paths. How Overrides Work Lotus separates shell structure from reusable components: Layer Role Public API --- --- --- components/layout Internal page chrome such as header, footer, sidebars, and TOC. No components/defaults Default implementations for override slots. No components/theme Reusable theme components used by defaults and local overrides. Yes components/ui Low-level internal controls. No The shell renders override slots through virtual modules. A default slot usually delegates to a public theme component: For example, the main header renders the HeaderNavbar slot. The default HeaderNavbar implementation delegates to the public NavbarLinks component. When To Override Start with normal theme configuration for content, labels, links, actions, sidebars, footer sections, color mode, accent color, gray scale, and radius. Use CSS tokens for fonts and visual tuning. Use a component override when the project needs to: - Replace the search UI with another search provider. - Change the header brand markup. - Move, hide, or restyle page actions beyond what pageActions supports. - Replace the page contributors block. - Replace previous and next page navigation. - Use custom theme mode control markup beyond themeModeControl . - Change the navbar or social-link rendering while keeping the same config data. - Change footer link rendering while keeping footer.sections as the source data. Override Points Override point names are slot names, not always public component export names. Use these names in themeConfig.components . Name Where It Renders Props Passed By Lotus --- --- --- Assistant Global assistant widget area near the end of . none SiteBrand Main header brand link. none HeaderNavbar Desktop header navbar and mobile menu navbar. currentPath?: string , mobile?: boolean HeaderSocialIcons Desktop header social area and mobile menu social area. mobile?: boolean FooterLinks Footer link grid. none SearchDialog Main header search trigger and dialog. none ThemeSwitch Desktop header and mobile menu theme mode area. none PageHeader Docs article title area. title , description? , sectionTitle? , pageActions , pageUrl , markdownUrl , currentLocale PageActions Action control inside PageHeader . actions , title , pageUrl , markdownUrl , currentLocale? PageAside Right sidebar content and mobile page tools. headings , editUrl , title , pageUrl , markdownUrl , currentSlug , currentLocale , tableOfContents? PageMeta Last updated and contributors between docs content and previous/next navigation. contributors , lastUpdated , title , currentLocale PageNavigation Previous and next links below docs content. navigation , currentLocale? Only these names are supported by the components config. Other components can still be imported from @prosefly/astro-theme-lotus/components , but importing a component does not make it an override point. Slot And Export Names Common slot and export pairs: Override Slot Public Component To Reuse --- --- HeaderNavbar NavbarLinks HeaderSocialIcons SocialIcons FooterLinks FooterLinks ThemeSwitch ThemeModeButton , ThemeModeSegmentedControl , ThemeModeSelect , or ThemeModeSwitch for custom compositions SearchDialog SearchDialog , SearchDialogTrigger , SearchDialogContent PageActions PageActions PageAside PageAside , EditThisPage PageHeader PageHeader PageMeta PageMeta , Contributors PageNavigation PageNavigation SiteBrand SiteBrand Use a public component import when you want the package implementation: Use a virtual module only when one override needs to call another override slot and preserve the user's configured replacement: Minimal Override Use themeModeControl before overriding ThemeSwitch if a project only needs one of the built-in controls. Create a local Astro component: Register it: Lotus now renders this file anywhere the shell asks for SearchDialog . Props And Translations Astro.props contains the props Lotus passes to that override point. Forward those props when reusing a public theme component so built-in behavior keeps working. Lotus also provides the resolved UI translator on Astro.locals.t . Use it when visible shell text should follow the current locale. See Internationalization for the translator API. Recipes For complete examples, see Override Shell Components. Debugging If an override does not appear: - Confirm the key matches one of the supported override point names exactly. - Confirm the file path is relative to the project root. - Restart the dev server after changing src/theme.config.ts . - Check that the override file has a default Astro component export, which is what .astro files provide by default. - Forward Astro.props when reusing a public theme component."},{"title":"Theme Tokens","description":"Reference the CSS tokens exposed by Lotus and Prosefly components.","href":"/docs/references/theme-tokens/","slug":"references/theme-tokens","section":"References","excerpt":"Lotus exposes CSS tokens for theme colors, typography, shape, layout, prose, and the Prosefly component bridge. Use these tokens when a project needs deeper styling control than ap...","content":"Lotus exposes CSS tokens for theme colors, typography, shape, layout, prose, and the Prosefly component bridge. Use these tokens when a project needs deeper styling control than appearance provides. Color Palettes Tailwind colors are exposed through @theme static aliases so they are available even when no utility class references them directly. Token pattern Purpose --- --- --lotus-color-slate-50 ... --lotus-color-slate-950 Slate neutral palette. --lotus-color-zinc-50 ... --lotus-color-zinc-950 Zinc neutral palette. --lotus-color-neutral-50 ... --lotus-color-neutral-950 Neutral palette. --lotus-color-stone-50 ... --lotus-color-stone-950 Stone neutral palette. --lotus-color-red-400 , --lotus-color-red-600 Red accent steps. --lotus-color-orange-400 , --lotus-color-orange-600 Orange accent steps. --lotus-color-amber-400 , --lotus-color-amber-600 Amber accent steps. --lotus-color-yellow-400 , --lotus-color-yellow-600 Yellow accent steps. --lotus-color-lime-400 , --lotus-color-lime-600 Lime accent steps. --lotus-color-green-400 , --lotus-color-green-600 Green accent steps. --lotus-color-emerald-400 , --lotus-color-emerald-600 Emerald accent steps. --lotus-color-teal-400 , --lotus-color-teal-600 Teal accent steps. --lotus-color-cyan-400 , --lotus-color-cyan-600 Cyan accent steps. --lotus-color-sky-400 , --lotus-color-sky-600 Sky accent steps. --lotus-color-blue-400 , --lotus-color-blue-600 Blue accent steps. --lotus-color-indigo-400 , --lotus-color-indigo-600 Indigo accent steps. --lotus-color-violet-400 , --lotus-color-violet-600 Violet accent steps. --lotus-color-purple-400 , --lotus-color-purple-600 Purple accent steps. --lotus-color-fuchsia-400 , --lotus-color-fuchsia-600 Fuchsia accent steps. --lotus-color-pink-400 , --lotus-color-pink-600 Pink accent steps. --lotus-color-rose-400 , --lotus-color-rose-600 Rose accent steps. Gray Scale appearance.gray maps one neutral palette into the shared --lotus-gray- scale. Token Purpose --- --- --lotus-gray-50 ... --lotus-gray-950 Active neutral scale for the current gray setting. Supported gray settings are slate , zinc , neutral , and stone . Semantic Colors These are the main tokens components should use. Token Purpose --- --- --lotus-background Page and shell background. --lotus-surface Subtle panels, hover backgrounds, and neutral soft UI. --lotus-text-strong Headings, labels, active text, and high-emphasis UI. --lotus-text Body copy and default foreground. --lotus-text-muted Secondary text, inactive navigation, captions, and helper copy. --lotus-border-muted Default component borders. --lotus-border-subtle Low-emphasis dividers and sticky chrome borders. --lotus-border-hover Stronger border state for hoverable controls. --lotus-code-background Inline code and plain code block background. --lotus-code-border Plain code block border. Light mode derives text from darker gray steps. Dark mode switches these tokens to lighter gray steps and darker surfaces. Accent Colors Token Purpose --- --- --lotus-accent-light Accent value used in light mode. --lotus-accent-dark Accent value used in dark mode. --lotus-accent Active accent for the current mode. --lotus-accent-soft Low-emphasis active and hover background. --lotus-accent-contrast Text on solid accent backgrounds. Built-in accents use Tailwind 600 in light mode and 400 in dark mode. Custom hex accents are converted to light and dark OKLCH values. Radius Token Purpose --- --- --lotus-radius-sm Inline code, small focus targets, and compact controls. --lotus-radius-md Buttons, nav items, sidebar items, and form-like controls. --lotus-radius-lg Cards, callouts, dropdowns, and larger surfaces. --lotus-radius-full Badges, circular buttons, and round markers. data-radius controls these values. Supported settings are none , small , medium , large , and full . Typography Token Purpose --- --- --lotus-system-sans Built-in system sans fallback stack. --lotus-system-mono Built-in system mono fallback stack. --lotus-font-sans Active sans font stack. --lotus-font-mono Active mono font stack. --default-font-family Tailwind default font family bridge. --default-mono-font-family Tailwind default mono font family bridge. --default-font-feature-settings Default sans feature settings. --default-mono-font-feature-settings Default mono feature settings. Lotus does not load web fonts by default. Override --lotus-font-sans and --lotus-font-mono after loading project fonts. Layout Token Purpose --- --- --lotus-header-height Main header height. --lotus-subnav-height Docs subnav height. --lotus-docs-chrome-height Combined sticky header and subnav offset. --lotus-sidebar-width Desktop sidebar column width. --lotus-toc-width Desktop table-of-contents column width. --lotus-content-width Main content column max width. These tokens are used by sticky offsets, responsive grid columns, sidebar scrolling, and table-of-contents positioning. Prose .lotus-prose defines extra tokens for Markdown content. Token Purpose --- --- --lotus-prose-font-body Body font inside prose. --lotus-prose-font-heading Heading font inside prose. --lotus-prose-font-mono Mono font inside prose. --lotus-prose-surface-radius Radius for code blocks, images, and media. --lotus-prose-size Base prose font size. --lotus-prose-leading Body line height. --lotus-prose-flow Default vertical spacing between prose blocks. --lotus-prose-heading-leading Heading line height. --lotus-prose-border Blockquote, table, rule, and footnote borders. --lotus-prose-marker List marker color. --lotus-prose-row-background Reserved row surface color for dense content. Expressive Code Lotus maps Expressive Code UI values to theme tokens through the integration config and prose CSS. Token or value Lotus source --- --- borderRadius var(--lotus-radius-lg) borderColor var(--lotus-code-border) codeBackground var(--lotus-code-background) codeForeground var(--lotus-text) codeFontFamily var(--lotus-font-mono) uiFontFamily var(--lotus-font-sans) focusBorder var(--lotus-accent) --ec-brdRad var(--lotus-prose-surface-radius) --ec-frm-frameBoxShdCssVal none --ec-frm-inlBtnBg var(--lotus-surface) --ec-frm-inlBtnBrd var(--lotus-border-muted) --ec-frm-inlBtnFg var(--lotus-text-muted) Prosefly Bridge Shared MDX components from @prosefly/astro-components read --pl- tokens. Lotus maps those tokens to its semantic layer. Prosefly token Lotus mapping --- --- --pl-background --lotus-background --pl-surface --lotus-surface --pl-text-strong --lotus-text-strong --pl-text --lotus-text --pl-text-muted --lotus-text-muted --pl-border-muted --lotus-border-muted --pl-border-subtle --lotus-border-subtle --pl-border-hover --lotus-border-hover --pl-accent --lotus-accent --pl-accent-soft --lotus-accent-soft --pl-accent-contrast --lotus-accent-contrast --pl-info --lotus-info --pl-info-ink --lotus-info-ink --pl-info-soft --lotus-info-soft --pl-info-contrast --lotus-info-contrast --pl-success --lotus-success --pl-success-ink --lotus-success-ink --pl-success-soft --lotus-success-soft --pl-success-contrast --lotus-success-contrast --pl-warning --lotus-warning --pl-warning-ink --lotus-warning-ink --pl-warning-soft --lotus-warning-soft --pl-warning-contrast --lotus-warning-contrast --pl-danger --lotus-danger --pl-danger-ink --lotus-danger-ink --pl-danger-soft --lotus-danger-soft --pl-danger-contrast --lotus-danger-contrast --pl-radius-sm --lotus-radius-sm --pl-radius-md --lotus-radius-md --pl-radius-lg --lotus-radius-lg --pl-radius-full --lotus-radius-full Component-Local Tokens Some MDX components define local tokens for their internal layout. Token Owner Purpose --- --- --- --pl-steps-start Steps Counter start offset. --pl-steps-bullet-size Steps Marker size. --pl-steps-bullet-margin Steps Gap below each marker before the connector line. --pl-steps-line Steps Connector line color. --pl-steps-marker-background Steps Marker background. --pl-steps-marker-foreground Steps Marker text color. --pl-file-tree-border FileTree File tree outer border color. --pl-file-tree-line FileTree Nested guide line color. Component-local tokens are implementation details. Prefer the semantic tokens above unless a component explicitly documents an override. Overriding Tokens Override tokens in project CSS when appearance is not enough. Update related tokens together. Background, surface, text, muted text, borders, and code colors should be treated as a set."},{"title":"Appearance","description":"Configure color, theme mode, radius, and font tokens.","href":"/docs/configuration/appearance/","slug":"configuration/appearance","section":"Guides","group":"Getting Started","excerpt":"appearance controls the document attributes and design tokens used by Lotus layouts and Prosefly MDX components. Default Mode defaultMode controls the initial color mode. Supported...","content":"appearance controls the document attributes and design tokens used by Lotus layouts and Prosefly MDX components. Default Mode defaultMode controls the initial color mode. Supported values are light , dark , and system . The system mode follows prefers-color-scheme until the visitor chooses a mode in the theme switch. Theme Mode Control themeModeControl chooses the built-in control shown in the header and mobile menu. Value Behavior --- --- segmented-control Shows system, light, and dark as separate icon buttons. button Shows one button that cycles through system, light, and dark. select Shows a select or dropdown with text labels. switch Shows a compact light/dark switch. false Hides the control. appearance.defaultMode still applies when the control is hidden. Override ThemeSwitch only when a project needs custom markup or placement beyond these built-in controls. Accent accent controls links, active navigation, focus rings, and primary UI. Built-in accents are based on Tailwind color scales: Custom hex colors are also supported. Lotus converts custom colors into light and dark accent variables. Gray gray selects the neutral scale used for text, borders, surfaces, dividers, and code backgrounds. Supported values are slate , zinc , neutral , and stone . Lotus renders this as a document attribute such as data-gray=\"neutral\" and maps semantic tokens like --lotus-text , --lotus-text-muted , --lotus-background , and --lotus-surface from that scale. Background and Text Background and text colors are not separate appearance fields. Lotus derives them from the selected gray scale and color mode, then exposes the result as CSS variables. Use CSS variable overrides when a project needs brand-level background or text colors. The preset chooser below applies the generated variables to the current while you preview a combination, but it does not store the selection: Preset names are descriptive examples, not Lotus API values. Copy the generated CSS variables instead of depending on the preset labels. The most important variables are: Variable Purpose --- --- --lotus-background Page and shell background. --lotus-surface Subtle panels, hover states, and soft UI. --lotus-code-background Inline code and plain code block background. --lotus-text-strong Headings, labels, and active text. --lotus-text Body copy and default foreground. --lotus-text-muted Secondary text, captions, and inactive navigation. --lotus-text-subtle Lower-emphasis helper text. --lotus-border-muted Normal control and panel borders. --lotus-border-subtle Low-emphasis dividers and separators. --lotus-border-hover Stronger borders for hover and focus-adjacent states. Override these tokens together. Changing only --lotus-background or only --lotus-text usually creates contrast, hover, border, or code-block issues. Radius radius controls the shared shape language. Supported values are none , small , medium , large , and full . Most compact controls follow the selected radius. Large surfaces such as code blocks and dropdown panels cap their radius so full does not produce pill-like containers. Fonts Lotus does not load web fonts by default. It exposes font tokens that can be overridden by project CSS. The default stacks are system sans and system mono."},{"title":"Cards","description":"Group related links and summaries with outline documentation cards.","href":"/docs/components/cards/","slug":"components/cards","section":"Components","excerpt":"Use CardGrid and Card for compact next-step links, feature summaries, and related resources. Cards use an outline style by default; linked cards add a soft hover background. Import...","content":"Use CardGrid and Card for compact next-step links, feature summaries, and related resources. Cards use an outline style by default; linked cards add a soft hover background. Import Example Review theme settings, typography tokens, and navigation structure before customizing the theme. Compose documentation pages with callouts, steps, tabs, file trees, and other shared MDX components. Open the Lotus repository in a new tab. A card does not need a title or link. Use this for short contextual notes inside a grid. Outline Style Cards are transparent by default. Only cards with href get hover styling. This card is not interactive, so it keeps the same outline treatment on hover. This card has a destination, so it gets a soft hover background. Props CardGrid Prop Type Default Notes --- --- --- --- None — — Creates a one-column mobile grid that expands to two columns on medium screens. Card Prop Type Default Notes --- --- --- --- title string optional Heading rendered at the top of the card. href string optional When provided, the card renders as an anchor. external boolean false Opens linked cards in a new tab with rel=\"noreferrer\" . icon string optional Iconify icon name rendered before the content. Notes Cards are intentionally lightweight. Keep content short and use one destination per linked card."},{"title":"Deployment","description":"Deploy Lotus to any static host supported by Astro output.","href":"/docs/deployment/","slug":"deployment","section":"Guides","group":"Getting Started","excerpt":"Lotus builds to static output, so deployment works anywhere Astro static sites are supported. Build before deploying 1. Run a production build locally. 2. Verify the generated outp...","content":"Lotus builds to static output, so deployment works anywhere Astro static sites are supported. Build before deploying 1. Run a production build locally. 2. Verify the generated output. Confirm that docs pages, MDX imports, search routes, and localized pages all render cleanly. 3. Publish dist/ . Deploy the generated static output to the host. Common static hosts Vercel Use the default Astro static build settings. The generated dist/ directory is what Vercel publishes. Netlify Point the build command to npm run build and publish the dist/ directory. Cloudflare Pages Use the same static output flow: install dependencies, run npm run build , and publish dist/ . Static host If the host can serve files from dist/ , Lotus can be deployed there. No server-side runtime is required for the first release."},{"title":"Images","description":"Author images, galleries, figures, and iframe embeds in Lotus docs.","href":"/docs/essentials/images/","slug":"essentials/images","section":"Guides","group":"Essentials","excerpt":"Lotus supports standard Markdown images, raw HTML images, figures with captions, image galleries, and iframe embeds written directly in MDX content. Markdown Images Use standard Ma...","content":"Lotus supports standard Markdown images, raw HTML images, figures with captions, image galleries, and iframe embeds written directly in MDX content. Markdown Images Use standard Markdown image syntax for most content images. Always write meaningful alt text for content images. If an image is purely decorative, keep the alt text empty. Local Images Use root-relative paths for images in public/ . Use imported images when the project wants Astro's asset pipeline. Image Galleries When a paragraph contains only images, Lotus converts that paragraph into a horizontal image gallery with previous and next controls. The gallery transform only runs when the paragraph contains images and whitespace. If text appears in the same paragraph, Lotus keeps it as normal inline content. Figures Use raw HTML when an image needs a caption. Captions can contain regular MDX text. MDX may wrap this content in a paragraph, and Lotus styles that case correctly. Raw HTML Images Use raw when you need attributes that Markdown syntax does not expose. Lotus styles raw images the same way it styles Markdown images. Iframe Embeds Users can write raw iframes directly in MDX. Lotus applies prose spacing, border, radius, and responsive sizing. Generic iframe content \" title=\"Generic iframe example\" width=\"640\" Video embeds from YouTube and Vimeo are rendered responsively with a 16 / 9 aspect ratio. Styling Behavior Lotus prose applies these defaults: - Images, videos, and iframes inherit the prose radius. - Images and iframes never exceed the content column width. - Image-only paragraphs are converted into .pl-image-gallery . - Multi-image galleries use horizontal scroll snap with overlay controls. - Gallery items calculate a shared height from image ratios and available width. - Multi-image galleries show the current image plus a preview of the next image. - figcaption uses muted text and handles nested paragraphs."},{"title":"Override Shell Components","description":"Copy complete examples for common Lotus component overrides.","href":"/docs/recipes/override-shell-components/","slug":"recipes/override-shell-components","section":"Recipes","excerpt":"Use these recipes after reviewing Overriding Components. Each example replaces one shell slot through themeConfig.components . Override Patterns Replace Use this when the default s...","content":"Use these recipes after reviewing Overriding Components. Each example replaces one shell slot through themeConfig.components . Override Patterns Replace Use this when the default slot behavior is not useful for the project. Reuse public Use this when the package default behavior is correct and only the wrapper or placement changes. Call slot Use this when one override should respect another configured override. Reuse Page Actions This override keeps the default copy, Markdown, ChatGPT, Claude, and custom actions, but changes the surrounding container. Custom Header Social Area This override keeps the configured social icons, replaces the default theme control, and still works in both desktop and mobile header contexts. HeaderSocialIcons receives mobile because Lotus uses the same override in the desktop header and mobile menu. Custom Page Header This override changes the page title layout while keeping the configured PageActions override point inside it. Use virtual:prosefly/lotus/components/PageActions inside a shell override when the override should respect another local PageActions override. Use the public @prosefly/astro-theme-lotus/components export when you specifically want the package theme component and do not want to recurse through the override slot."},{"title":"Page Layouts","description":"Build custom Astro pages with Lotus layout exports.","href":"/docs/customization/page-layouts/","slug":"customization/page-layouts","section":"Guides","group":"Customization","excerpt":"Lotus exports page-level layout primitives from @prosefly/astro-theme-lotus/layouts . Use them for custom Astro routes such as pricing pages, changelogs, landing pages, legal pages...","content":"Lotus exports page-level layout primitives from @prosefly/astro-theme-lotus/layouts . Use them for custom Astro routes such as pricing pages, changelogs, landing pages, legal pages, and other pages that should share the same theme shell without using the docs sidebar layout. Exports Export Purpose --- --- BaseLayout Document shell with Lotus styles, appearance attributes, metadata, favicon, JSON-LD, and assistant widget support. SiteHeader Site header with brand, search, navbar, socials, language selector, theme switch, and mobile menu. SiteFooter Footer shell using the configured brand, copyright, credits, and footer links. PageContainer Responsive max-width container with Lotus horizontal page padding. PageSection Page section wrapper with configurable vertical spacing and optional container. SplashLayout Complete splash page layout with site header, hero area, content section, and footer. TextLayout Complete centered prose layout for terms, privacy, and other plain text pages. DocsLayout is intentionally not exported. It depends on generated docs context, sidebar navigation, table of contents, contributors, and pagination. Header Controls SiteHeader is a standalone shell header for custom pages. It accepts page-level switches for pages that share Lotus branding and navigation but do not need the full docs header behavior. Use these props for template pages such as blogs, marketing pages, and custom dashboards. They do not change the global Lotus config. Pricing Page Use BaseLayout when the page needs a custom composition: Splash Page Use SplashLayout when the page matches the built-in hero plus content shape: Text Page Use TextLayout for standalone prose: Blog Pages New in 0.3.0 Blog collections belong in your project, not in Lotus config. Use Lotus layouts and the exported Prose component to keep posts visually consistent with docs pages."},{"title":"Typography","description":"Review the default prose scale, spacing, and markdown element styles.","href":"/docs/references/typography/","slug":"references/typography","section":"References","excerpt":"This page collects supported Markdown patterns in one place so typography changes can be reviewed without jumping between feature pages. It intentionally uses mostly plain content...","content":"This page collects supported Markdown patterns in one place so typography changes can be reviewed without jumping between feature pages. It intentionally uses mostly plain content elements rather than custom layout components. Lotus prose is tuned for documentation pages with side navigation and a table of contents. Body text should feel readable beside dense navigation, while headings should mark sections without becoming page-level display type. Headings The page title above is rendered from frontmatter as the document h1 . Content headings start at h2 so the table of contents and page outline stay stable. Heading Level Three Subsections are smaller than section headings but still need enough weight for long technical pages. Use them for focused topics, configuration groups, or steps inside a larger section. Heading Level Four Small headings are useful inside dense references, especially before short paragraphs or lists. Heading Level Five Fifth-level headings should stay compact and should not break the reading flow. Heading Level Six Sixth-level headings are available for rare deep reference pages. Paragraphs And Line Breaks Paragraphs are separated by a blank line. The spacing between paragraphs should be clear enough for scanning but compact enough that a medium-length guide still feels continuous. This paragraph contains a hard line break after the first sentence.\\ The second line should stay visually connected to the first line. Emphasis Use strong text when a term needs emphasis. Use italic text sparingly for phrasing, citations, or quoted labels. You can combine both as strong italic text when the content really needs that treatment. GitHub Flavored Markdown also supports strikethrough text for removed or obsolete values. Links Inline links such as the installation guide should remain visible without pulling too much attention away from the sentence. Reference-style links are useful when the same URL appears repeatedly. This sentence links to the Astro documentation astro-docs . astro-docs : https://docs.astro.build/ Footnotes Footnotes are useful for small clarifications that should not interrupt the main paragraph flow. ^theme-note ^theme-note : This footnote checks the spacing and link-back style generated by the Markdown renderer. Inline Code Inline code like docsBase , themeConfig.sidebars , src/theme.config.ts , and --lotus-text-muted should sit comfortably inside a line of prose without changing the paragraph rhythm. Lists Use unordered lists for related notes or capabilities: - Configure project metadata, favicon, footer links, and appearance tokens. - Author pages with MDX and the default documentation layout. - Override selected theme components when a project needs custom behavior. Use ordered lists for procedural content: 1. Install the theme package and Astro integration. 2. Add documentation content under the configured docs collection. 3. Start the dev server and review the generated navigation. Nested lists should stay compact: - Appearance - Accent color - Gray scale - Radius - Navigation - Navbar links - Sidebar groups - Footer sections Task lists are supported through GitHub Flavored Markdown: - x Create the docs structure - x Configure MDX and Expressive Code - Publish the package Blockquote Documentation typography should make structure obvious without forcing every section to become a visual component. Blockquotes can contain more than one paragraph. The first paragraph introduces the quoted idea. The second paragraph should keep the same muted tone and left rule. Code Blocks Fenced code blocks render with Expressive Code by default. Plain text blocks are also supported. Package Manager Commands Shell blocks that contain package-manager install commands can be converted to package-manager tabs by the Lotus markdown integration. Python package manager commands are supported too. Images Images should keep their aspect ratio, fit the content column, and inherit the prose radius. Captions should use muted text and compact spacing. Unsplash images make the typography page useful for reviewing media spacing, border radius, captions, and dark-mode contrast. Tables Tables are supported for compact reference material. Element Purpose Visual target --- --- --- Paragraph Main reading text Comfortable line height and steady rhythm Heading 2 Major content section Compact but easy to scan Heading 3 Subsection Clear hierarchy without oversized type Inline code Token or API name Visible, but not visually heavy Table Reference data Dense enough for repeated scanning Long tables should stay readable on narrow screens. Option Default Description --- --- --- appearance.accent 'indigo' Sets the main accent color used by links, active navigation, and focused controls. appearance.gray 'neutral' Selects the neutral gray scale used by text, borders, surfaces, and muted UI. appearance.radius 'medium' Controls the global corner style while allowing fixed components to cap extreme values. Horizontal Rule Content above the rule should feel related to the page. Content below the rule should read as a separate closing block. Final paragraphs can be used to check the visual relationship between body copy, rules, and following content. Escaped Characters Escaped Markdown punctuation should render literally: \\ This text is not emphasized.\\ \\ This text is not inline code.\\ Raw HTML And MDX MDX allows HTML elements inside Markdown content. Keyboard labels such as Ctrl + K should align with surrounding text. Inline HTML like highlighted text , API , and small text should inherit the surrounding prose rhythm. Inserted text can use underlined additions , while deleted text can use removed phrases . Math and technical notation can use subscript and superscript inline: H 2 O and x 2 . Program output can use 200 OK , variables can use request , short quotes can use semantic tokens keep components stable , and citations can use Lotus Design Notes ."},{"title":"Changelog","description":"Track Lotus releases, user-facing changes, and upgrade notes.","href":"/docs/changelog/","slug":"changelog","section":"Guides","group":"Getting Started","excerpt":"Review Lotus releases to understand what changed, what was fixed, and whether an upgrade affects your documentation site. View published tags, generated release notes, and release...","content":"Review Lotus releases to understand what changed, what was fixed, and whether an upgrade affects your documentation site. View published tags, generated release notes, and release assets. Check the published package version and package metadata. 0.4.0 2026-07-19 - Enabled Prosefly callout directives from @prosefly/astro-components . - Updated @prosefly/astro-components to ^0.3.0 . - Grouped Markdown-related integration options under markdown ; top-level expressiveCode , calloutDirectives , and packageManagerTabs are removed. - Added themeModeControl for choosing the built-in theme mode control without overriding ThemeSwitch . - Fixed the standalone SiteHeader mobile menu alignment when search and assistant triggers are disabled. 0.3.1 2026-07-19 - Added llms config for disabling /llms.txt or generating /llms-full.txt . - Pagefind indexing attributes are now emitted only when the Pagefind search provider is enabled. 0.3.0 2026-07-19 - Added SSR heading anchors for h2 , h3 , and h4 . - Added a CodeBlock export for Shiki-highlighted code on custom pages. - Added a Prose export for custom pages. - Added Markdown alternate links to docs page metadata. - Added an automatically generated /llms.txt endpoint for AI-readable docs discovery. - Added semantic status color tokens for info , success , warning , and danger . - Updated @prosefly/astro-components to 0.2.1 . - Reworked SiteHeader into a standalone site header. - Fixed prose links inside headings. - Improved heading anchor styling on mobile. - Fixed docs content width so page actions no longer overlap the table of contents on wide screens. 0.2.0 2026-07-18 - Added built-in UI translations for Traditional Chinese, Japanese, Korean, French, German, Spanish, Brazilian Portuguese, Italian, Russian, and Arabic. - Added RTL direction inference for common RTL locales such as Arabic, Persian, Hebrew, and Urdu. - Added RTL-aware shell behavior for the header, dropdowns, mobile docs menu, sidebar, table of contents, page actions, and previous/next page navigation. - Added sidebar diagnostics for missing entries, empty autogenerated directories, duplicate sections, and duplicate page ownership. - Enhanced sidebar generation with autogenerate.structure , autogenerate.depth , and autogenerate.exclude . - Refactored sidebar generation into focused resolver, autogenerate, index, and diagnostics modules. - Simplified docs homepage routing: docsBase now controls where docs render, and setting docsBase: '/docs' leaves / available for a custom homepage. - Removed the separate homepage config option. - Removed source.contentRoot ; edit links and contributor source paths now use the content entry file path directly. - Updated the release workflow to generate GitHub release notes automatically. - Improved ARIA state, focus handling, and keyboard behavior for dropdowns, local search, mobile docs navigation, and page actions. - Fixed deployed page action URLs so generated assistant links do not keep a local development origin. - Improved mobile clipboard handling for Copy page. - Added high fetch priority to the header logo image. - Kept code, keyboard, and sample text left-to-right inside RTL prose content. 0.1.1 2026-07-17 - Fixed a Tailwind CSS issue in the package release. 0.1.0 2026-07-17 - Initial release of @prosefly/astro-theme-lotus ."},{"title":"Code Blocks","description":"Author syntax-highlighted code blocks, titles, highlights, and command examples.","href":"/docs/essentials/code-blocks/","slug":"essentials/code-blocks","section":"Guides","group":"Essentials","excerpt":"Lotus renders fenced code blocks with Expressive Code by default. Use this page for day-to-day authoring patterns. See Expressive Code for advanced markers, diffs, line numbers, an...","content":"Lotus renders fenced code blocks with Expressive Code by default. Use this page for day-to-day authoring patterns. See Expressive Code for advanced markers, diffs, line numbers, and integration options. Basic Syntax Use triple backticks and include a language name. ts Common language names include ts , tsx , js , astro , css , html , json , md , mdx , sh , and bash . Titles And Frames Add title to show a file name in an editor-style frame. ts title=\"src/theme.config.ts\" docsBase: '/docs', ) Shell languages render as terminal frames automatically. You can still add a custom title. sh title=\"Install Lotus\" pnpm add @prosefly/astro-theme-lotus Use frame=\"none\" when a snippet should stay minimal. ts frame=\"none\" Highlighted Lines Use line or start-end to mark important lines. Multiple selectors can be combined with commas. ts 2,5-7 title=\"src/theme.config.ts\" docsBase: '/docs', appearance: accent: 'indigo', gray: 'neutral', radius: 'medium', , ) Package Manager Tabs Shell code blocks that contain npm package-manager commands are converted to synced package-manager tabs automatically. The transform also handles related npm commands in the same block, such as npm run dev , npm create ... , npm dlx ... , and npx ... . Python install commands are converted to synced pip , uv , poetry , and pdm tabs. Disable automatic package-manager tabs when you want npm or pip commands to render as plain code blocks. Word Wrap Use wrap for long lines that should stay inside the content column. ts wrap title=\"src/copy.ts\""},{"title":"Expressive Code","description":"Reference advanced code block markers, diffs, line numbers, and configuration.","href":"/docs/references/expressive-code/","slug":"references/expressive-code","section":"References","excerpt":"Lotus enables Expressive Code by default. Use this reference when a page needs more than a basic fenced code block. Configuration Disable Expressive Code entirely when a site shoul...","content":"Lotus enables Expressive Code by default. Use this reference when a page needs more than a basic fenced code block. Configuration Disable Expressive Code entirely when a site should use Astro's built-in Shiki renderer instead. Pass Expressive Code options through the Lotus integration when you need to change the default themes or block behavior. Inserted And Deleted Lines Use ins= ... and del= ... for changed lines. Plain ... remains a neutral highlight. ts del= 2 ins= 3-6 8 title=\"src/theme.config.ts\" navigation: label: 'Docs', href: '/docs/' , navbar: label: 'Docs', href: '/docs/' , label: 'Dashboard', href: '/app/', variant: 'soft' , , pageActions: , ) Inline Markers Mark text inside a line with quoted strings or regular expressions. Prefix the marker with ins= , del= , or mark= to choose the marker type. ts \"docsBase\" ins=\"'/docs'\" del=\"'/documentation'\" title=\"src/theme.config.ts\" docsBase: '/docs', previousBase: '/documentation', ) Regular expressions are useful when the exact value changes across examples. ts /variant: ' ^' +'/ title=\"src/theme.config.ts\" label: 'Dashboard', href: '/app/', variant: 'soft' , label: 'Login', href: '/login/', variant: 'outline' , Diff Blocks Use the diff language for compact before-and-after examples. diff - navigation: label: 'Docs', href: '/docs/' + navbar: label: 'Docs', href: '/docs/' Use lang=\"...\" when you want diff markers and syntax highlighting for the underlying language. diff lang=\"ts\" title=\"src/theme.config.ts\" - navigation: label: 'Docs', href: '/docs/' , + navbar: label: 'Docs', href: '/docs/' , ) Line Numbers Lotus includes Expressive Code's line number plugin, but keeps line numbers off by default. Add showLineNumbers to a block when line references matter. ts showLineNumbers title=\"src/content.config.ts\" const docs = defineCollection( loader: docsLoader(), ); Use startLineNumber for snippets taken from the middle of a file. ts showLineNumbers startLineNumber=24 27 title=\"src/theme.config.ts\" appearance: accent: 'indigo', gray: 'neutral', radius: 'medium', , Hanging Indent Use hangingIndent with wrap to keep wrapped lines easier to scan. ts wrap hangingIndent=2 title=\"src/sidebar.ts\""},{"title":"Navbar","description":"Configure header navigation, action links, social icons, and localized labels.","href":"/docs/configuration/navbar/","slug":"configuration/navbar","section":"Guides","group":"Getting Started","excerpt":"The header is built from two config arrays: - navbar renders text links and action-style links. - socials renders compact icon-only links after the navbar. Use navbar for primary d...","content":"The header is built from two config arrays: - navbar renders text links and action-style links. - socials renders compact icon-only links after the navbar. Use navbar for primary destinations such as Docs, Blog, Pricing, or an app link. Use socials for external community and repository links. Navbar Items Every navbar item needs a label and href . Internal links are localized automatically when they point into the docs route. For example, /docs/configuration/project/ can become /docs/zh-cn/configuration/project/ in the Simplified Chinese locale. Add external: true for links that should open in a new tab. Action Links Set variant when a navbar item should read as a call to action instead of a plain text link. Supported variants: Variant Use it for --- --- text Normal navigation links. This is the default. soft Secondary actions that should have a filled surface. outline Secondary actions that need more boundary than soft . solid Primary actions such as \"Get started\" or \"Dashboard\". color can be neutral or accent . Use accent sparingly for the primary action in the header. Icons Navbar action links support trailingIcon . Use full Iconify names such as lucide:chevron-right , or supported Lotus aliases such as external . The public navbar config is optimized for text links and trailing action icons. If a project needs leading icons, badges, or custom layout, override HeaderNavbar and reuse the configured navbar data. Social Links socials renders compact icon links next to the navbar on desktop and inside the mobile menu on small screens. Social links require icon . Icon values can be full Iconify names or Lotus aliases such as github , x , discord , and external . Translated Labels Use translations when the same link should have locale-specific labels. The fallback label is label . Translation keys match Lotus locale keys. Mobile Behavior On desktop, the header renders navbar links, social links, search, language select, and the theme switch inline. On mobile: - Search stays in the compact header. - Navbar links, action links, socials, language select, and the theme switch move into the mobile menu. - Action links render full width so they remain easy to tap. Custom Rendering Use config first. Override components only when the markup or placement needs to change. Need Override --- --- Custom navbar markup HeaderNavbar Custom social link area HeaderSocialIcons Custom brand link SiteBrand Custom theme switch markup or placement ThemeSwitch or HeaderSocialIcons See Overriding Components for the override contract."},{"title":"Steps","description":"Structure procedural content with numbered markers and a vertical guide.","href":"/docs/components/steps/","slug":"components/steps","section":"Components","excerpt":"Use Steps for installation flows, migration guides, and setup tasks where each instruction should be easy to scan as part of a sequence. Import Basic Usage Steps uses the same synt...","content":"Use Steps for installation flows, migration guides, and setup tasks where each instruction should be easy to scan as part of a sequence. Import Basic Usage Steps uses the same syntax as Starlight: wrap a single ordered Markdown list inside the component. 1. Install the package. Add Lotus and the shared MDX components to your Astro project. 2. Configure the integration. Register the Lotus integration in astro.config.mjs and point it at your docs content. 3. Start writing docs. Create MDX pages, add frontmatter, and organize them with sidebars . Rich Content Each list item can contain paragraphs, nested lists, inline code, and fenced code blocks. 1. Create a docs page. Add an MDX file under your docs collection. 2. Add sidebar metadata. Use frontmatter when the page needs local ordering. - sidebar.order controls position inside generated sidebar groups. - sidebar.label can override the navigation label. 3. Verify the page. Run pnpm check to catch invalid MDX, missing imports, and type errors. Continue Numbering Use the standard ordered-list start value when a procedure continues from an earlier sequence. 4. Review the generated route. Open the page in your browser and confirm the content, sidebar, and table of contents all match the expected location. 5. Publish the docs. Build the site and deploy the generated Astro output. Syntax Rules - The direct content of Steps must be exactly one ordered Markdown list. - Keep a blank line after and before so MDX parses the list as Markdown. - Do not place headings, paragraphs, or multiple lists next to the root list inside Steps . - Nested content belongs inside a list item, indented under that item. Props Steps does not accept component props. Numbering, spacing, marker colors, and the guide line are handled by the component CSS and Lotus design tokens."},{"title":"Troubleshooting","description":"Diagnose common Lotus setup, routing, MDX, search, i18n, and override issues.","href":"/docs/troubleshooting/","slug":"troubleshooting","section":"Guides","group":"Getting Started","excerpt":"Start with pnpm run check . It validates content collections, MDX imports, Astro components, and TypeScript before a production build. A docs page does not appear in the sidebar Co...","content":"Start with pnpm run check . It validates content collections, MDX imports, Astro components, and TypeScript before a production build. A docs page does not appear in the sidebar Confirm the page is in the docs collection, is not draft: true in production, and is matched by either a sidebar string item or an autogenerate.directory entry. In i18n projects, sidebar values are locale-neutral, so use configuration/project , not en/configuration/project . A generated route is not the URL I expected Check docsBase , locale directory , and frontmatter slug . slug changes the public URL, but sidebar ownership still follows the content entry ID. The search index returns 404 Confirm docsBase and the active locale. With the default docsBase: '/' , the root search index is /search.json . With docsBase: '/docs' , it is /docs/search.json ; localized indexes include the locale prefix, such as /docs/zh-cn/search.json . Icons do not render Use full Iconify names such as lucide:search or configure aliases where supported. If an icon name is built dynamically, add it to iconify.preload because static scanning cannot detect it. A component override does not apply Confirm the key matches a supported override slot exactly, the path is relative to the project root, and the dev server was restarted after editing src/theme.config.ts . A translated page falls back to English Add the matching file under the locale directory. Fallback pages keep the target locale route but use the default-locale source file for edit links and contributors."},{"title":"Sidebars","description":"Configure docs sections, subnav items, sidebar groups, and generated entries.","href":"/docs/configuration/sidebars/","slug":"configuration/sidebars","section":"Guides","group":"Getting Started","excerpt":"sidebars defines the documentation information architecture. Each top-level sidebar becomes a docs subnav item, and its items define the sidebar shown for that section. Sections To...","content":"sidebars defines the documentation information architecture. Each top-level sidebar becomes a docs subnav item, and its items define the sidebar shown for that section. Sections Top-level sidebar objects support label , optional slug , optional icon , optional translations , and items . slug is optional. If omitted, Lotus derives it from the label. Add a slug when the visible label and stable section id should differ. String Items String items reference content collection entry IDs. With the default docsLoader() base, those IDs are relative to src/content/docs . 'installation' resolves to src/content/docs/installation.mdx in a monolingual site, or to the current locale's installation.mdx in an i18n site. For this example site, root English content lives in src/content/docs/en/ , but the sidebar still references it as installation . Link Items Use link items for internal or external links that are not generated from docs content. Link items support icons and badges for status labels, API methods, or other compact metadata. Use a trailing badge for status labels such as beta or new. Use a leading badge for API endpoints where the badge is part of the scanned label. String badges render as trailing neutral badges. Badges support position: 'leading' 'trailing' , variant: 'solid' 'soft' 'subtle' 'outline' , and color: 'neutral' 'accent' 'info' 'success' 'warning' 'danger' . Groups Groups create nested sidebar sections. They can be collapsed by default. Localized Labels Use translations for labels owned by theme.config.ts . This includes top-level sidebar labels, group labels, and link item labels. String items and autogenerated entries use the localized page's frontmatter instead. For example, overview displays the Chinese page title when src/content/docs/zh-cn/overview.mdx exists. Autogenerated Directories Use autogenerate to include entries from a directory. The directory value follows the same locale-neutral rule. In this example site, components matches src/content/docs/en/components for root English pages and src/content/docs/zh-cn/components for Simplified Chinese pages. Autogenerated entries are sorted by sidebar.order frontmatter, then by title. By default, Lotus renders autogenerated entries as a flat list and includes all descendants under the directory. Add options when a directory needs tighter control. Option Default Description --- --- --- directory required Locale-neutral docs directory to read from. structure 'flat' Use 'tree' to preserve nested folders as collapsible sidebar groups. depth all descendants Maximum depth to include relative to directory . For directory: '' , the default is direct children only. exclude none Glob pattern or array of patterns matched against both the full slug and the slug relative to directory . Supports and . Page Ownership Lotus determines a page's active docs section from sidebars . A page belongs to the first top-level sidebar that lists it directly or includes it through an autogenerated directory."},{"title":"Tabs","description":"Present parallel examples as one selectable set of tab panels.","href":"/docs/components/tabs/","slug":"components/tabs","section":"Components","excerpt":"Use Tabs when readers need to switch between equivalent examples, such as package managers, frameworks, output formats, or preview/code views. Import Basic Usage The syntax follows...","content":"Use Tabs when readers need to switch between equivalent examples, such as package managers, frameworks, output formats, or preview/code views. Import Basic Usage The syntax follows Starlight: place one or more TabItem components directly inside Tabs . Tabs can contain prose, lists, links, and other MDX content. - Keep each panel focused on the same task. - Use short labels so the tab list stays compact on mobile. With Icons Add icon to a TabItem with any Iconify icon name. When a group has icons, the active tab icon appears at the start of the tab header. sh pnpm install @prosefly/astro-components sh npm install @prosefly/astro-components Copy Code Set copy on Tabs when each panel contains a code block and the active panel should be copyable from the tab header. The copy button reads the first code block in the active panel. Synced Groups Groups with the same syncKey share the selected label. This is useful for package manager examples repeated across a page. Use matching labels across synced groups. syncKey stores the selected label in localStorage , so the reader's choice can persist across navigation. Custom Values Use value when a tab needs a stable internal value that differs from its visible label. defaultValue can match either label or value . Props Tabs Prop Type Default Notes --- --- --- --- copy boolean \\ string false Shows a copy button for the first code block in the active panel. defaultValue string first tab Initial active tab. Matches either TabItem.label or TabItem.value . syncKey string optional Syncs the active label across tab groups with the same key. TabItem Prop Type Default Notes --- --- --- --- label string required Visible tab label. Also used for syncing when value is omitted. value string label Stable value for defaultValue and internal tab state. icon string optional Iconify icon name shown as the active panel icon. Syntax Rules - Tabs must contain only direct TabItem children. - Each TabItem must have a label . - Put Markdown content inside each TabItem ; do not put loose Markdown between tab items. - Use concise labels so the tab list remains easy to scan on small screens."},{"title":"Accordion","description":"Hide and reveal related documentation sections with accessible disclosure controls.","href":"/docs/components/accordion/","slug":"components/accordion","section":"Components","excerpt":"Use accordions for FAQ sections, optional explanations, and long reference pages where readers should be able to reveal details without leaving the current flow. Import Basic Usage...","content":"Use accordions for FAQ sections, optional explanations, and long reference pages where readers should be able to reveal details without leaving the current flow. Import Basic Usage The syntax follows Fumadocs: wrap one or more AccordionItem components in Accordions . Lotus is an Astro documentation theme with a configurable docs shell, routing integration, design tokens, and shared MDX components. Yes. The MDX components live in @prosefly/astro-components and use Prosefly CSS tokens, so they can be reused by other Astro themes. No. Items render as native details and summary elements with a small script for grouped behavior. Rich Content Accordion content can contain paragraphs, lists, links, inline code, and fenced code blocks. Most projects use a small set of configuration files. - astro.config.mjs registers the integration. - src/theme.config.ts configures the docs theme. - src/content.config.ts defines content collections. Multiple Items By default, opening one item closes the other items in the same group. Add multiple when readers should be able to keep several answers open. Write docs as MDX files in your configured docs collection. Use sidebars and navbar to define how readers move through the docs. Use appearance to configure accent color, gray scale, radius, and default color mode. Default Values Use defaultValue on the group when the open item should be controlled from the parent. The value matches each item's value , or id , or title . Configure the docs base path and route behavior. Configure navbar links, sidebar groups, and page actions. When multiple is enabled, defaultValue can be an array. Linkable Items Add an id to make an item addressable by URL hash. When the page loads with a matching hash, the item opens automatically. Navigate to linkable-answer to open this item directly. An item's value defaults to its id when present, otherwise to its title . Disabled Items Use disabled for unavailable or intentionally locked content. This section can be opened. This content is rendered, but the trigger cannot open the item. Props Accordions Prop Type Default Notes --- --- --- --- multiple boolean false Allows more than one item to stay open. defaultValue string \\ string optional Opens matching item values on page load. AccordionItem Prop Type Default Notes --- --- --- --- title string required Trigger text shown in the accordion summary. id string optional Adds a hash target and becomes the default value . value string id ?? title Stable value used by Accordions defaultValue . defaultOpen boolean false Renders the item open before group behavior runs. open boolean defaultOpen Sets the native details open state. disabled boolean false Prevents opening or closing the item through the trigger. Syntax Rules - Accordions should contain direct AccordionItem children. - Each AccordionItem must have a title . - Use value when the visible title may change but stored defaults should stay stable. - Use multiple before opening several items by default."},{"title":"Footer","description":"Configure copyright text and grouped footer links.","href":"/docs/configuration/footer/","slug":"configuration/footer","section":"Guides","group":"Getting Started","excerpt":"footer controls the lower site chrome. Credits Lotus shows a small Built with Lotus credit in the footer by default. Disable it with the top-level credits option. Copyright copyrig...","content":"footer controls the lower site chrome. Credits Lotus shows a small Built with Lotus credit in the footer by default. Disable it with the top-level credits option. Copyright copyright renders under the footer brand. Sections sections is an ordered list of link groups. Each link supports label , href , and optional external . Empty Footer Links Set sections to an empty array when the footer should only show the brand and copyright."},{"title":"File Tree","description":"Display directory structures with collapsible folders and inline file metadata.","href":"/docs/components/file-tree/","slug":"components/file-tree","section":"Components","excerpt":"Use FileTree to show project structure, package exports, documentation folders, or any directory layout where hierarchy matters more than long prose. Import Basic Usage The syntax...","content":"Use FileTree to show project structure, package exports, documentation folders, or any directory layout where hierarchy matters more than long prose. Import Basic Usage The syntax follows Starlight: wrap a single unordered Markdown list inside FileTree . - astro.config.mjs - package.json - src - content - docs - index.mdx - components/ - theme.config.ts - public/ Directories An item becomes a directory when it has nested children. You can also add a trailing / to mark an empty directory. - src - components - Callout.astro - Tabs.astro - content/ - public/ Directories render as native disclosure controls, so readers can collapse and expand sections of the tree. Comments Add a comment by writing text after the file or directory name. Comments can use inline Markdown. - astro.config.mjs registers the Lotus integration - src - theme.config.ts the main theme configuration file - content contains the docs collection - docs generated from themeConfig.sidebars - packages - astro-components shared MDX components - astro-theme-lotus theme integration and layouts Highlight Entries Make a file or directory name bold to highlight the important entry. The highlight covers the file or directory icon and name; comments stay outside the highlighted area. - packages - astro-components - src - mdx - FileTree.astro - rehype-file-tree.ts - Tabs.astro - astro-theme-lotus Placeholders Use ... or … when a tree intentionally omits files. - src - components - Callout.astro - Steps.astro - … - content - docs - overview.mdx - … Special Names Wrap file names in backticks when they contain spaces, leading underscores, or characters that Markdown may treat as formatting. - init .py - README copy.md - theme.config.ts highlighted with code formatting - docs - getting started.mdx - faq?.mdx File Icons File icons are selected from the file name or extension. By default, FileTree uses simple Lucide file and folder icons. - component.astro code file - config.yaml config file - tokens.css stylesheet - logo.svg image asset - notes.md text content - archive.zip generic file Use iconSet=\"vscode-icons\" for richer file-type icons. - astro.config.mjs - package.json - tsconfig.json - src - components - Header.astro - SearchDialog.ts - content - docs - overview.mdx - images.md - styles - app.css - public - logo.svg Props Prop Type Default --- --- --- iconSet 'lucide' \\ 'vscode-icons' 'lucide' Syntax Rules - The direct content of FileTree must be exactly one unordered Markdown list. - Keep a blank line after and before so MDX parses the list as Markdown. - Use nested list items for directory contents. - Use bold text to highlight an entry name. - Put comments after the name on the same list item. - Use ... or … for omitted files."},{"title":"Page Actions","description":"Configure copy, Markdown, and AI actions shown near the page title.","href":"/docs/configuration/page-actions/","slug":"configuration/page-actions","section":"Guides","group":"Getting Started","excerpt":"pageActions controls the compact action button shown near the documentation page title. Set it to an empty array to disable the control. Built-In Actions Lotus includes four built-...","content":"pageActions controls the compact action button shown near the documentation page title. Set it to an empty array to disable the control. Built-In Actions Lotus includes four built-in action types. Type Behavior --- --- copy-page Fetches the generated .md route and copies Markdown to the clipboard. view-markdown Opens the generated .md route. open-chatgpt Opens ChatGPT with the current page URL. open-claude Opens Claude with the current page URL. Built-in labels and icons can be overridden. Custom Actions Custom actions use label , icon , href , and optional external . Custom href values can use page variables. Variable Value --- --- title Page title url Current page URL markdownUrl Generated Markdown URL encodedTitle URL-encoded page title encodedUrl URL-encoded page URL encodedMarkdownUrl URL-encoded Markdown URL Layout The first action is shown as an outline button. Remaining actions live in the dropdown opened by the chevron."},{"title":"Search","description":"Configure the built-in search dialog and generated search index.","href":"/docs/configuration/search/","slug":"configuration/search","section":"Guides","group":"Getting Started","excerpt":"Lotus includes a provider-based search dialog. The default provider is local , which uses a generated JSON index and searches entirely in the browser. This is the default, so most...","content":"Lotus includes a provider-based search dialog. The default provider is local , which uses a generated JSON index and searches entirely in the browser. This is the default, so most projects do not need to set search explicitly. Disable the default search trigger and dialog with: The default header reads this setting and omits the search UI when search is disabled. Providers Lotus supports the built-in local provider, Pagefind, and Algolia DocSearch. Local The local provider generates a small JSON index during the Astro build and searches it entirely in the browser. Pagefind Use Pagefind when a site has enough content that a dedicated static search index is a better fit than shipping one JSON file. When enabled, Lotus runs Pagefind after astro build , indexes the generated HTML, and writes the browser bundle and index files to /pagefind/ . outputSubdir changes the generated output folder. excludeSelectors appends selectors to the default ignored chrome selectors. rootSelector can be set for advanced Pagefind setups, but most Lotus sites should rely on the built-in data-pagefind-body and data-pagefind-ignore markers. DocSearch DocSearch is loaded from the official CDN only when the provider is enabled. The default Lotus search trigger opens the DocSearch modal through the DocSearch JavaScript API. For localized DocSearch indexes, indexName can be a map keyed by Lotus locale keys or language tags: DocSearch crawling and indexing are outside Lotus. Use a search-only API key in client config, never an admin key. Use searchParameters to scope results by language, version, or any facet produced by your crawler. Set cssUrl or jsUrl to self-host the DocSearch assets instead of loading them from jsDelivr. Local Search With the default docsBase: '/' , the search index is available at /search.json . When docsBase is /docs , the index is available at /docs/search.json . Search Dialog The default header includes a search trigger. Opening it loads the generated index on demand and searches page title, description, section, sidebar group, excerpt, and stripped page content. Results are scored locally in the browser. The highest-scoring results appear first, with keyboard support for moving through results and opening the active result. Search Index Each indexed item includes: Field Source --- --- title Page frontmatter title description Page frontmatter description href Generated docs URL slug Entry slug or slug override section Owning top-level sidebar label group Owning sidebar group label excerpt Short text excerpt from the page body content Searchable text extracted from MDX The index strips code fences, imports, exports, MDX tags, image syntax, and most Markdown punctuation before storing searchable content. Excluding Pages Use pagefind: false to exclude a page from the generated search index: The field name is kept for Starlight compatibility. In Lotus it controls the built-in search.json output. When the active provider is Pagefind, Lotus also uses this field to decide whether the rendered page receives Pagefind indexing attributes. Draft pages are also excluded from production search results because draft: true excludes them from production builds. Custom Search UI Override SearchDialog when the default trigger or dialog needs project specific behavior: The theme package also exports smaller building blocks: The built-in content component renders the active provider shell. For local search it emits data-lotus-search-provider and data-lotus-search-index . For Pagefind search it also emits data-lotus-pagefind-bundle , and the page layout adds Pagefind indexing attributes. For DocSearch, it emits a DocSearch container and loads the CDN assets on demand. Limits The built-in search is designed for documentation sites that can ship a static JSON index. Start there, then switch to a dedicated provider only when content volume or language requirements demand it. Lotus search is intentionally lightweight. It does not provide stemming, language-aware tokenization, typo correction, or server-side ranking. Use a dedicated search service when a large documentation site needs those features."},{"title":"Source","description":"Configure source repositories, edit links, and page contributors.","href":"/docs/configuration/source/","slug":"configuration/source","section":"Guides","group":"Getting Started","excerpt":"source describes where documentation files live in version control. Lotus uses it for features that need to map a rendered page back to its source file, such as edit links and cont...","content":"source describes where documentation files live in version control. Lotus uses it for features that need to map a rendered page back to its source file, such as edit links and contributors. Lotus reads the source file path from Astro's content entry metadata, so this configuration only needs repository information. Repository fields accept either repository shorthand or a full repository URL. Repository Providers When source is omitted, Lotus tries to infer the repository provider and URL from git config --get remote.origin.url . This supports common GitHub, GitLab, and Codeberg remotes, including SSH remotes such as git@github.com:owner/repo.git . Lotus does not infer the branch from git. Set source.branch when links should point somewhere other than main . GitHub GitLab Codeberg Repository fields can also use full repository URLs when shorthand is not enough. Edit Links Set editLink: true to generate \"Edit this page\" links from source . Lotus uses each entry's real filePath to build the edit URL for the configured repository provider. You do not need to repeat the docsLoader( base ) directory in source configuration. For src/content/docs/en/overview.mdx , Lotus generates: Use an object when edit links need a custom URL pattern. The object inherits source.branch , so only the pattern needs to be different. Patterns can use path , encodedPath , and branch . Object values can also override the shared provider fields when a project has unusual repository layout. Set editLink: false or omit editLink to hide generated edit links. Contributors Lotus can show page contributors above the previous and next links. Contributors use the same entry file path as edit links. Lotus reads per-page contributors from local git log , then enriches matching users with GitHub avatars and profile links when source.github is configured. The GitHub lookup uses the repository contributors endpoint once per repository, not once per page. Lotus also loads GitHub user profiles for the first 10 non-excluded repository contributors so it can match local git author names against GitHub public emails and full names. Contributors that cannot be matched to GitHub fall back to Gravatar URLs for local git email addresses. Set contributors to an object when you want to limit or filter the rendered list. Use githubProfileLimit to change how many GitHub user profiles Lotus requests for full-name matching. Set it to 0 to skip full-name matching. Set avatar: 'gravatar' when you always want local git history and Gravatar, without calling the GitHub API. Set avatar: 'github' when you always want to query GitHub repository contributors for avatars and profile links. contributors.github can still override the shared source.github field for unusual cases. Lotus uses GITHUB TOKEN or GH TOKEN automatically when either environment variable is present. If the GitHub request fails, Lotus falls back to local git history so static builds can still finish. Localized Content Edit links and contributor paths use the actual source file path, not the localized route. If a localized page falls back to default-locale content, its edit link and contributor query point to the default-locale source file. For src/content/docs/en/overview.mdx , Lotus uses the source path src/content/docs/en/overview.mdx , even though the root English locale renders at /docs/overview/ ."},{"title":"Assistant","description":"Configure hosted Ask AI widgets for documentation.","href":"/docs/configuration/assistant/","slug":"configuration/assistant","section":"Guides","group":"Getting Started","excerpt":"Lotus can load hosted Ask AI widgets for documentation sites. The theme does not implement retrieval, model routing, or chat protocols. Providers such as Inkeep and kapa.ai own the...","content":"Lotus can load hosted Ask AI widgets for documentation sites. The theme does not implement retrieval, model routing, or chat protocols. Providers such as Inkeep and kapa.ai own the index, answer quality, citations, analytics, and widget UI. When an assistant provider is configured, Lotus adds an AI trigger button next to the header search trigger. The search trigger becomes slightly narrower on desktop so search and Ask AI read as one compact control group. Assistant widgets are disabled by default. Inkeep Use Inkeep when you want a hosted chat button backed by an Inkeep assistant. Lotus loads the Inkeep browser script only when this provider is enabled and initializes Inkeep.ModalSearchAndChat . The modal is connected to the header AI trigger with modalSettings.triggerSelector , and the default base settings sync with Lotus' data-theme attribute so the widget follows light and dark mode. Additional Inkeep settings can be passed through: Use scriptUrl to pin or self-host the Inkeep script. Kapa Use kapa.ai when you already have a Kapa Website Widget integration. Lotus renders Kapa's widget script only when this provider is enabled. The default Kapa launcher is hidden, and the header AI trigger opens Kapa in Ask AI mode through data-modal-override-open-selector-ask-ai . The websiteId value is the Kapa Website ID, which Kapa also labels as the Integration ID in the dashboard. Pass extra widget attributes with attributes : Use scriptUrl to self-host or pin the Kapa widget bundle. Custom Use custom when the project wants to own the full assistant integration. Then override Assistant : The default custom provider renders nothing. This keeps Lotus out of API keys, RAG pipelines, model gateways, and provider-specific chat protocols."},{"title":"Integrations","description":"Configure Iconify preloading, Expressive Code, callout directives, and package manager tabs.","href":"/docs/configuration/integrations/","slug":"configuration/integrations","section":"Guides","group":"Getting Started","excerpt":"Lotus includes integrations for icons, syntax highlighting, callout directives, image galleries, and package-manager command tabs. Preload icon data used by the theme, MDX componen...","content":"Lotus includes integrations for icons, syntax highlighting, callout directives, image galleries, and package-manager command tabs. Preload icon data used by the theme, MDX components, theme config, and static Icon usage. Render syntax-highlighted code blocks with frames, copy buttons, markers, and theme-aware styling. Turn recognized npm and Python install commands into synchronized tabbed command blocks. Write admonitions with Markdown directive syntax such as :::tip . Transform Markdown image-only paragraphs into responsive gallery figures. Iconify Lotus installs the @prosefly/astro-components/icon integration internally. It preloads icons used by Lotus, icons used by Prosefly components, theme config icons, and static usage in Astro and MDX files. Use preload for icons that cannot be detected statically. Set scan: false when a project wants only explicit preload names. Expressive Code Expressive Code is enabled by default. Lotus configures light and dark Shiki themes, line numbers, copy button styling, and code frame styling to match the theme tokens. Disable Expressive Code when a project should use Astro's built-in Shiki renderer. Package Manager Tabs Lotus enables the Prosefly package-manager tabs remark plugin by default. It turns recognized install commands into tabbed command blocks. Set markdown.packageManagerTabs to false to keep package-manager commands as normal code blocks. Callout Directives Lotus enables the Prosefly callout directive remark plugin by default. This adds Starlight-style admonition syntax for note , tip , warning , caution , and danger . See Admonitions for authoring syntax and usage guidance. Set markdown.calloutDirectives to false to keep Markdown directives untouched. Image Galleries Lotus also installs the Prosefly image gallery rehype plugin. Paragraphs that contain only Markdown images are transformed into responsive gallery figures. See Images for authoring details. Disable the transform when a project wants image-only paragraphs to stay as normal Markdown output. Component Overrides Use components to replace selected Lotus theme components. See Overriding Components for the complete override surface and examples."},{"title":"Start building with Lotus","description":"Install Lotus, configure the docs shell, and start writing Astro documentation.","href":"/docs","slug":"index","excerpt":"Choose Your Path Start from the Lotus starter template when you want a working Astro docs site with the theme already wired up. Install Lotus manually, register the integration, an...","content":"Choose Your Path Start from the Lotus starter template when you want a working Astro docs site with the theme already wired up. Install Lotus manually, register the integration, and connect your docs content collection. Set project identity, docs routing, navigation, sidebars, footer links, search, source links, and page actions. Learn frontmatter, Markdown, images, code blocks, and MDX authoring patterns for Lotus pages. Tune appearance, CSS tokens, layouts, and shell component overrides when configuration is not enough. Move existing Starlight content, sidebars, i18n directories, and MDX component usage into Lotus. Reference Links - Read Overview for the high-level model. - Visit Project Structure for a task-oriented setup guide. - Check Changelog before upgrading Lotus."}]}