Configuration¶

Everything you can configure in Lumina — theme options, accent colors, and a complete reference.

Recommended Configuration¶

Most projects benefit from a few extensions and settings beyond the defaults. Here’s a practical starting point:

conf.py¶

extensions = [
    "myst_parser",           # Write docs in Markdown
    "sphinx_design",         # Cards, grids, tabs, badges
    "sphinx_copybutton",     # Copy button on code blocks
]

html_theme = "lumina"
html_theme_options = {
    "accent_color": "#10b981",                                          # Emerald (default)
    "source_repository": "https://github.com/you/your-project",        # Enables "Edit on GitHub"
    "source_branch": "main",
    "source_directory": "docs/",
}

Tip

See Custom Styling for CSS custom properties, custom fonts, and template overrides.

Theme Options Reference¶

All options go in html_theme_options in your conf.py. Every option has a sensible default, so you only need to set what you want to change.

Appearance¶

Option	Type	Default	Description
`accent_color`	string	`"#10b981"`	Primary brand color used for links, active states, and accents. Any valid CSS color.
`code_style`	string	`"default"`	Syntax highlighting preset. Sets matched Pygments styles for light and dark modes. Options: `"default"`, `"nord"`, `"one-dark"`, `"gruvbox"`, `"material"`. See Custom Styling for details.
`dark_mode_default`	string	`"auto"`	Initial color mode. `"auto"` follows system preference, `"light"` and `"dark"` force a mode.
`wide_layout`	string	`"false"`	Controls wide content layout (`60rem` instead of `48rem`). `"toggle"` shows a button in the header that lets readers switch (visible on viewports ≥1280px, persisted in browser). `"always"` forces wide mode permanently with no toggle. See Wide Layout.
`logo_only`	string	`"false"`	When `"true"`, hides the project name in the header and shows only the logo.
`light_logo`	string	`""`	Logo image for light mode (path relative to `_static`). Falls back to `html_logo`.
`dark_logo`	string	`""`	Logo image for dark mode (path relative to `_static`). When set alone, displays in both modes. Set both `light_logo` and `dark_logo` for automatic switching.
`logo_icon`	string	`""`	Use a Lucide icon as the site logo instead of an image. Pass the icon name (e.g. `"hexagon"`). Only used when no image logo is configured. When set, the browser favicon is automatically derived from the same icon and colored with `accent_color`, unless you also set Sphinx’s `html_favicon`, which takes precedence. See Icons.
`logo_icon_size`	string	`"24"`	Display size in pixels for `logo_icon`. Lucide icons are pixel-perfect at multiples of 24 (24, 48, 72, …); other sizes appear fuzzy because the 2-unit strokes can’t align to whole device pixels. Stick to 24 unless you deliberately want a larger logo.

Tip

Why 24 and not 28? Lucide icons are designed on a 24×24 grid with 2-unit-wide strokes. When a Lucide icon is rendered at a size that isn’t a clean multiple of 24, those strokes land on fractional device pixels and the browser anti-aliases them across two columns of pixels — the icon looks subtly fuzzy. Stick to 24, 48, or 72 for a crisp logo.

Announcement¶

Option	Type	Default	Description
`announcement`	string	`""`	HTML content for a dismissible banner above the header. Supports links and inline formatting. Users can dismiss it; the preference persists in `localStorage` and resets automatically when the content changes.

Navigation¶

Option	Type	Default	Description
`nav_links`	list	`[]`	Links displayed in the header navigation bar. Each item needs `title` and `url` keys. Add `"external": True` for off-site links, or `"children"` with a list of `{title, url}` items for dropdown menus.
`nav_depth`	string	`"4"`	Maximum depth of the sidebar table of contents tree. Branches are collapsible in the UI — see Navigation for details.
`show_toc`	string	`"true"`	Show or hide the right-side page table of contents.
`show_breadcrumbs`	string	`"true"`	Show or hide the breadcrumb trail above the content.
`show_prev_next`	string	`"true"`	Show or hide previous/next page navigation at the bottom.
`show_attribution`	string	`"true"`	Show or hide the “Built with Lumina” attribution link in the sidebar footer.
`show_back_to_top`	string	`"true"`	Show or hide the back-to-top button that appears when scrolling up.

Code Blocks¶

Option	Type	Default	Description
`code_wrap_toggle`	string	`"true"`	Show a “wrap long lines” button on every code block, next to the copy button. Per-block — turning wrap on for one block leaves others unaffected. Set `"false"` to hide the button entirely.

Images¶

Option	Type	Default	Description
`image_lightbox`	string	`"false"`	Opt-in: set to `"true"` to enable click-to-zoom on every `<img>` inside the article. Skips user-defined links wrapping images and any element with the `no-lightbox` class or `data-no-lightbox` attribute. Mermaid diagrams keep their built-in fullscreen viewer instead — opt other inline SVGs in with `data-lumina-zoom`.

Doc Sections¶

Option	Type	Default	Description
`doc_sections`	list	`[]`	Define major documentation sections with icons and colors. Adds a dropdown at the top of the sidebar that lets readers switch between sections, each with its own navigation tree. See Navigation for setup.

Reading Time¶

Option	Type	Default	Description
`show_reading_time`	string	`"false"`	Show an estimated reading time next to the breadcrumbs at the top of every page. The estimate is computed from prose word count at 200 words per minute, ignoring code blocks, images, and toctrees.

Override per page using MyST front matter:

---
reading_time: false   # Hide the badge on this page only
---

Or pin a manual value (rare — useful when the auto estimate undercounts complex content like math-heavy pages):

---
reading_time: 12      # Force "12 min read" on this page
---

Version Switcher¶

Option	Type	Default	Description
`version_switcher_json`	string	`""`	URL to a JSON file listing available documentation versions. Enables a version dropdown in the header.
`version_switcher_match`	string	`""`	The current version string to highlight in the dropdown. Should match a `version` field in the JSON.

Search¶

Option	Type	Default	Description
`search_backend`	string	`"pagefind"`	Search implementation. `"pagefind"` for Pagefind (recommended), `"sphinx"` for Sphinx built-in search.

HTTP API¶

These options control the interactive features on HTTP API endpoint pages. They require sphinxcontrib-openapi or sphinxcontrib-httpdomain. See OpenAPI for setup.

Option	Type	Default	Description
`api_base_url`	string	`""`	Default base URL for all HTTP API endpoints. Enables the “Copy as curl” button and “Try it out” panel. Individual blocks can override this with a `data-api-base-url` attribute on any ancestor element — see OpenAPI.
`try_it_out`	string	`"true"`	Set to `"false"` to hide the “Try it out” panel while keeping the “Copy as curl” button.

Source Links¶

These options enable the “Edit on GitHub” link in the table of contents sidebar.

Option	Type	Default	Description
`source_repository`	string	`""`	URL to your source repository (e.g., `https://github.com/you/project`). Required for edit links.
`source_branch`	string	`"main"`	Branch name used in edit links.
`source_directory`	string	`"docs/"`	Path to the docs directory within your repository.
`edit_uri`	string	`"edit"`	URI path component for edit links. Use `"edit"` for GitHub, `"blob"` for view-only links.

Footer & Social¶

Option	Type	Default	Description
`social_links`	list	`[]`	Icon links in the header. Each item needs `icon` and `url` keys. Supported icon: `"github"`.
`footer_text`	string	`""`	Custom text displayed in the page footer.

SEO and social previews¶

See SEO and discoverability for the full picture, including per-page front-matter overrides and the html_baseurl requirement for canonical URLs and the sitemap.

Option	Type	Default	Description
`og_image`	string	`""`	Default Open Graph / Twitter image. Filename in `_static/` (e.g. `og-card.png`) or an absolute URL. Falls back to `html_logo` when unset and the logo is a raster format.
`og_image_alt`	string	`""`	Alt text for the default `og_image`.
`og_image_width`	string	`""`	Width in pixels of `og_image`. Emit `1200` for the standard social card to help Facebook, LinkedIn, and Slack render it without flicker.
`og_image_height`	string	`""`	Height in pixels of `og_image`. Pair with `og_image_width` (`630` for the standard 1200×630 social card).
`publisher_logo`	string	`""`	Square-ish raster logo used in `TechArticle` JSON-LD `publisher.logo`. Filename in `_static/` or absolute URL. Distinct from `og_image` because Google requires the publisher logo to be near-square (a 1200×630 banner disqualifies the page from Rich Results). Falls back to `html_logo` when raster.
`twitter_site`	string	`""`	Twitter/X handle (with or without leading `@`). Falls back to a Twitter/X entry in `social_links` when unset.
`seo_keywords`	string	`""`	Sitewide `<meta name="keywords">` value. Page-level `keywords` front matter overrides this.
`disable_seo`	string	`"false"`	Set to `"true"` to suppress all SEO metadata, JSON-LD, sitemap generation, and `robots.txt`.

Accent Colors¶

The accent_color option controls links, active navigation items, buttons, and other interactive elements. It applies to both light and dark modes automatically.

Here are some well-tested color choices:

Color	Hex	Best for
Emerald	`#10b981`	Default. Clean and professional.
Blue	`#3b82f6`	Traditional documentation feel.
Violet	`#8b5cf6`	Creative and modern projects.
Rose	`#f43f5e`	Bold, attention-grabbing.
Amber	`#f59e0b`	Warm, energetic. Ensure contrast on light backgrounds.
Teal	`#14b8a6`	Calm, technical feel.

Warning

Choose a color with sufficient contrast against both light and dark backgrounds. Avoid very light colors (pastels) — they become unreadable on white backgrounds.

Full Configuration Example¶

Here’s a conf.py using every theme option:

conf.py — Complete theme configuration¶

html_theme = "lumina"
html_theme_options = {
    # Appearance
    "accent_color": "#10b981",
    "dark_mode_default": "auto",
    "logo_only": "false",
    "light_logo": "logo-light.svg",
    "dark_logo": "logo-dark.svg",

    # Announcement
    "announcement": 'New in v2.0 — <a href="/changelog">see what changed</a>!',

    # Navigation
    "nav_links": [
        {"title": "Guide", "url": "getting-started"},
        {
            "title": "Reference",
            "children": [
                {"title": "Typography", "url": "reference/typography"},
                {"title": "Code Blocks", "url": "reference/code-blocks"},
            ],
        },
        {"title": "GitHub", "url": "https://github.com/you/project", "external": True},
    ],
    "nav_depth": "4",
    "show_toc": "true",
    "show_breadcrumbs": "true",
    "show_prev_next": "true",
    "show_attribution": "true",
    "show_back_to_top": "true",

    # Code blocks
    "code_wrap_toggle": "true",

    # Images
    "image_lightbox": "false",

    # Reading time
    "show_reading_time": "false",

    # Doc sections
    "doc_sections": [
        {
            "name": "User Documentation",
            "description": "Installation, guides & reference",
            "icon": "book-open",
            "color": "#10b981",
            "default": True,
            "link": "getting-started/index",
        },
        {
            "path": "contributing",
            "name": "Developer Documentation",
            "description": "Architecture & development",
            "icon": "code",
            "color": "#8b5cf6",
        },
    ],

    # Version switcher
    "version_switcher_json": "https://example.com/versions.json",
    "version_switcher_match": "1.17",

    # Search
    "search_backend": "pagefind",

    # HTTP API interactive features
    "api_base_url": "https://api.example.com/v1",
    "try_it_out": "true",

    # Source links (enables "Edit on GitHub")
    "source_repository": "https://github.com/you/project",
    "source_branch": "main",
    "source_directory": "docs/",
    "edit_uri": "edit",

    # Footer & social
    "social_links": [
        {"icon": "github", "url": "https://github.com/you/project"},
    ],
    "footer_text": "Built with Sphinx and Lumina.",
}

Next Steps¶

Custom Styling

Go deeper with CSS custom properties, custom fonts, syntax highlighting themes, and template overrides.

Custom Styling