Configuration

This reference lists top-level Lotus theme fields. Use the linked configuration pages for examples and behavior details.

Config Files

Lotus automatically reads theme.config.json from the Astro project root. Use JSON when your theme configuration is plain data and you want editor completion from the schema.

{
  "$schema": "https://prosefly.dev/schema/lotus.json",
  "name": "My Docs",
  "description": "Documentation for my project.",
  "appearance": {
    "accent": "emerald"
  }
}

Register Lotus without arguments when all configuration lives in JSON:

import { defineConfig } from 'astro/config';
import lotus from '@prosefly/astro-theme-lotus';

export default defineConfig({
  integrations: [lotus()],
});

Values passed to lotus({...}) override theme.config.json. Object options such as appearance, footer, iconify, locales, markdown, source, and ui are shallow-merged; arrays such as siteNav, socials, and docsNav replace the JSON value when provided.

Component overrides are integration-only. Configure components in astro.config.ts, not in theme.config.json.

Head Entries

Use head for global tags that should appear on every page, such as Open Graph defaults, Twitter cards, verification tags, external assets, scripts, or project CSS overrides:

{
  "head": [
    { "tag": "meta", "attrs": { "property": "og:site_name", "content": "My Docs" } },
    { "tag": "meta", "attrs": { "property": "og:image", "content": "https://example.com/og.png" } },
    { "tag": "meta", "attrs": { "name": "twitter:card", "content": "summary_large_image" } },
    { "tag": "style", "src": "./src/styles/lotus.css" }
  ]
}

style.src entries are resolved from the project root and loaded after Lotus styles. Page frontmatter head entries are merged after global entries.

Options

TypeScript Options

Use defineLotusConfig() inside astro.config.ts when configuration needs TypeScript, imports, or computed values:

import { defineConfig } from 'astro/config';
import lotus, { defineLotusConfig } from '@prosefly/astro-theme-lotus';

const lotusConfig = defineLotusConfig({
  name: 'My Docs',
  description: 'Documentation for my project.',
});

export default defineConfig({
  integrations: [lotus(lotusConfig)],
});

Values passed to lotus({...}) override theme.config.json.