# 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:
```python
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/",
}
```
## 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. On/off options take `"true"` and `"false"`, or Python’s `True` and `False`.
### 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"`, `"lumina"`. See [Custom Styling](../guides/custom-styling.html.md) 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](../guides/wide-layout.html.md). |
| `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](https://lucide.dev/icons/) 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](../guides/icons.html.md). |
| `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. |
### 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. A `url` is a document name such as `getting-started`, resolved from the current page, or a full URL. Add `"external": True` to open a link in a new tab, 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](../guides/navigation.html.md) 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. It is never shown on the root page; hide it on any other page with `hide_breadcrumbs: true` in the front matter. |
| `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 | `"false"` | Set `"true"` to 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. Code never wraps until a reader turns it on. |
### Images
| Option | Type | Default | Description |
|------------------|--------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `image_lightbox` | string | `"false"` | Opt-in: set to `"true"` to enable click-to-zoom on every `` 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](../guides/navigation.html.md) for setup. |
### Reading Time
| Option | Type | Default | Description |
|---------------------|--------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `show_reading_time` | string | `"false"` | Show an estimated reading time with a clock icon below the introductory paragraph, or below the title when there is no introduction. The estimate uses prose word count at 200 words per minute, ignoring code blocks, images, and toctrees. |
Override per page using MyST front matter:
```yaml
---
reading_time: false # Hide reading time on this page only
---
```
Or pin a manual value (rare — useful when the auto estimate undercounts complex content like math-heavy pages):
```yaml
---
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. On Read the Docs the dropdown appears without it, filled from your project’s versions; see [Read the Docs](../guides/read-the-docs.html.md). |
| `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 | `"auto"` | Search implementation. `"auto"` uses Pagefind when the `pagefind` extra is installed and Sphinx built-in search otherwise; `"pagefind"` or `"sphinx"` forces one. See [Search](../guides/search.html.md). |
### API display
Python, JavaScript, and HTTP API definitions start collapsed. Readers can open a signature or use **Expand all** and **Collapse all**.
Set `api_expanded` to `"true"` to show every definition on page load. This does not open the separate **Try it out** request forms.
```python
html_theme_options = {
"api_expanded": "true", # Default: "false"
}
```
Direct links reveal the target definition and its parents. Without JavaScript, all documentation stays visible.
### HTTP API
These options control the interactive features on HTTP API endpoint pages. They require `sphinxcontrib-openapi` or `sphinxcontrib-httpdomain`. See [OpenAPI](../extensions/openapi.html.md) for setup, authentication, and compatibility limits. Readers can edit the server URL in each request panel; credentials stay in page memory and are scoped to the full API base URL.
| 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](../extensions/openapi.html.md). |
| `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](../guides/seo.html.md) 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 `` 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.
Choose a color to preview it on this page. The preview resets when you leave or reload.
Try in conf.py: "accent_color": "#10b981"
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. |
| Burnt Orange | `#ea580c` | Warm and grounded, with stronger contrast than amber 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:
```python
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 — see what changed!',
# 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": "false",
# 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
Go deeper with CSS custom properties, custom fonts, syntax highlighting themes, and template overrides.