Project Structure

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.tsregisters the Lotus integration
• Directory src

  • content.config.tsregisters the docs collection
  • theme.config.tsstores Lotus theme config
  • Directory content

    • Directory docs

      • index.mdxdocs homepage
      • overview.mdx
      • installation.mdx
      • Directory configuration

        • project.mdx
• Directory 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.tsregisters the Lotus integration
• Directory src

  • content.config.tsregisters the docs collection
  • theme.config.tsuses the default docsBase: '/'
  • Directory content

    • Directory docs

      • index.mdxhomepage at /
      • installation.mdx
      • Directory components

        • icon.mdx
• Directory 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.tsregisters the Lotus integration
• Directory src

  • content.config.tsregisters the docs collection
  • theme.config.tssets docsBase: '/docs'
  • Directory pages

    • index.astrosite homepage at /
  • Directory content

    • Directory docs

      • index.mdxdocs homepage at /docs/
      • overview.mdx
      • installation.mdx
• Directory 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.

• Directory src

  • content.config.tsregisters the docs collection
  • theme.config.tsmaps locale directories
  • Directory content

    • Directory docs

      • Directory en

        • index.mdx
        • overview.mdx
        • Directory configuration

          • project.mdx
      • Directory zh-cn

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

• Directory src

  • content.config.ts
  • theme.config.tsreferences local override paths
  • Directory content

    • Directory docs

      • index.mdx
      • overview.mdx
  • Directory components

    • Directory lotus

      • HeaderSocialIcons.astro
      • PageActions.astro
      • SearchDialog.astro
  • Directory styles

    • lotus.cssoptional custom CSS tokens
• Directory 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.