Content Routing

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:

import { defineCollection } from 'astro:content';
import { docsLoader, docsSchema } from '@prosefly/astro-theme-lotus/content';

const docs = defineCollection({
  loader: docsLoader(),
  schema: docsSchema(),
});

export const collections = { 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.

• Directory src

  • Directory content

    • Directory docs

      • index.mdx/
      • installation.mdx/installation/
      • Directory 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.

const docs = defineCollection({
  loader: docsLoader({
    base: './src/content',
  }),
  schema: docsSchema(),
});

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:

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.

export default defineLotusConfig({
  docsBase: '/docs',
});

With docsBase: '/docs' and the default loader:

The prefixed search index is /docs/search.json.

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.

src/
  pages/
    index.astro          -> /
  content/
    docs/
      index.mdx          -> /docs/
      installation.mdx   -> /docs/installation/

You can reuse Lotus page primitives on custom pages:

---
import {
  BaseLayout,
  PageSection,
  SiteFooter,
  SiteHeader,
} from '@prosefly/astro-theme-lotus/layouts';
---

<BaseLayout title="Home">
  <SiteHeader currentPath="/" />
  <main>
    <PageSection>
      <h1>Product documentation</h1>
    </PageSection>
  </main>
  <SiteFooter />
</BaseLayout>

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            -> /
    installation.mdx     -> /installation/

• Directory src

  • Directory content

    • Directory docs

      • index.mdxdocs homepage at /
      • installation.mdx/installation/

Slug Overrides

Use frontmatter slug when a page needs a public path that differs from its entry ID:

---
title: CLI Reference
slug: reference/cli
---

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:

import { z } from 'astro/zod';

const docs = defineCollection({
  loader: docsLoader(),
  schema: docsSchema({
    extend: z.object({
      product: z.string().optional(),
    }),
  }),
});

The extension is merged into the base Lotus docs schema. Existing Lotus fields such as title, sidebar, tableOfContents, template, pagefind, and draft remain available.