---
title: "Theming & Appearance"
guide-section: "Config & Theming"
bread-crumbs: false
tags: [Theming, Customization]
---

# Theming & Appearance

The default Great Docs site looks polished out of the box, but most projects want their
documentation to reflect their own identity. Great Docs gives you control over every visual layer of
the site: the color scheme, navbar styling, dark mode, logos, hero section, icons, and more. All of
these options live in `great-docs.yml`, so you can adjust the look without writing any CSS or
JavaScript.

This page covers the visual customization options. For functional settings (API discovery, parsers,
GitHub integration, etc.), see [Configuration](configuration.qmd).

## Dark Mode Toggle

Great Docs includes a light/dark mode toggle in the navbar. It respects the visitor's system
preference on first visit and remembers their choice in local storage for subsequent visits. The
toggle is enabled by default.

To disable the toggle, set `dark_mode_toggle` to `false` in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
dark_mode_toggle: true   # Enabled by default
```

```{.yaml filename="great-docs.yml"}
dark_mode_toggle: false  # Disable the toggle
```

When enabled, the toggle provides instant switching without a page reload. Visitors who prefer
reduced motion in their operating system settings will still see the theme change, but without the
transition animation.

## GitHub Link Style

Great Docs automatically adds a GitHub link to the navbar when it detects your repository URL. The
`github_style` option controls how that link is displayed:

```{.yaml filename="great-docs.yml"}
github_style: widget   # Default: interactive widget with stats dropdown
```

```{.yaml filename="great-docs.yml"}
github_style: icon     # Simple GitHub icon linking to the repo
```

The `widget` style shows a GitHub icon that, on hover, reveals a dropdown with live star, fork,
issue, and pull request counts. The `icon` style renders a plain GitHub icon that links directly to
the repository.

## Sidebar Filter

API reference sidebars can grow large as your package adds more exports. The sidebar filter adds a
search input at the top of the sidebar so visitors can quickly find the function or class they're
looking for. It is enabled by default and appears automatically when the sidebar has enough items.

To configure the filter in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
sidebar_filter:
  enabled: true     # Default: true
  min_items: 20     # Default: show filter when sidebar has 20+ items
```

The `min_items` threshold prevents the filter from appearing on small APIs where it would not be
useful. Set `enabled: false` to hide the filter entirely.

## Display Name

By default, Great Docs uses your package name (from `pyproject.toml`) in the navbar and page titles.
If your package name uses underscores or hyphens (e.g., `great_docs` or `great-docs`), you can set a
friendlier display name:

```{.yaml filename="great-docs.yml"}
display_name: "Great Docs"
```

This name appears in the navbar title, the hero section (if enabled), the page `<title>` tag, and
anywhere else the package name is shown to visitors.

## GitHub Link Style

A floating button appears in the bottom-right corner of the page after the visitor scrolls down,
providing a one-click way to return to the top. The button uses smooth scrolling and automatically
shifts upward when it would overlap with the prev/next page navigation links. It is enabled by
default.

```{.yaml filename="great-docs.yml"}
back_to_top: true    # Enabled by default
```

```{.yaml filename="great-docs.yml"}
back_to_top: false   # Disable the button
```

The button respects the visitor's `prefers-reduced-motion` setting: when reduced motion is
preferred, scrolling is instant rather than animated.

When `back_to_top` is enabled, a companion **On this page** button also appears on mobile
viewports (below 768 px). This round floating button sits directly above the back-to-top button
and opens a compact table-of-contents panel. Tapping a heading scrolls to that section and
dismisses the panel whereas tapping outside the panel dismisses it without navigating. The button is
hidden on tablet and desktop widths where the sidebar TOC is already visible.

## Keyboard Navigation [version-badge new 0.5]

Great Docs includes built-in keyboard shortcuts that let visitors navigate the site and access
common actions without reaching for the mouse. A small keyboard icon appears in the navbar; clicking
it (or pressing `h` / `?`) opens an overlay listing every shortcut.

### Available Shortcuts

The shortcuts are organized into three groups:

#### Navigation

Move between pages and jump to common destinations without leaving the keyboard.

| Key | Action |
|-----|--------|
| `s` or `/` | Focus the search input |
| `[` | Go to the previous page |
| `]` | Go to the next page |
| `q` | Go to the homepage |
| `u` | Go to the User Guide |
| `r` | Go to the API Reference |
| `m` or `n` | Show/hide the floating menu overlay |

The floating menu shows the sidebar navigation on documentation pages and the navbar links on the
homepage, giving quick access to any section without scrolling.

#### Display

Control how the page looks and capture its content.

| Key | Action |
|-----|--------|
| `d` | Toggle dark mode |
| `c` | Copy the current page as Markdown (when available) |

#### General

Access help and dismiss any open overlay.

| Key | Action |
|-----|--------|
| `h` or `?` | Show/hide the keyboard shortcuts help overlay |
| `Escape` | Close the active overlay or unfocus the current element |

### Configuration

Keyboard navigation is enabled by default. To disable it:

```{.yaml filename="great-docs.yml"}
keyboard_nav: false
```

### Accessibility

Keyboard shortcuts are automatically skipped when the visitor is typing in an input field, textarea,
or content-editable element, so they never interfere with form entry or search. The help overlay
uses ARIA attributes for screen reader compatibility, and animations respect the visitor's
`prefers-reduced-motion` system setting.

## Announcement Banner

A site-wide banner can be displayed above the navbar to highlight important news, releases, or
alerts. The banner appears on every page and can optionally be dismissed by the visitor.

### Simple Form

The simplest way to add a banner is with a string value. This creates a blue, info-styled banner
that visitors can dismiss:

```{.yaml filename="great-docs.yml"}
announcement: "Version 2.0 is now available!"
```

### Full Configuration

For more control over the banner's appearance and behavior, use a dictionary with `content`, `type`,
`dismissable`, and `url` keys:

```{.yaml filename="great-docs.yml"}
announcement:
  content: "We've moved to a new domain. Please update your bookmarks!"
  type: warning        # info (default), warning, success, or danger
  dismissable: true    # Allow visitors to close the banner (default: true)
  url: https://example.com/blog/migration  # Optional: makes the text a link
```

The available banner types and their colors:

| Type | Light Mode | Dark Mode |
|------|-----------|-----------|
| `info` | Blue | Dark blue |
| `warning` | Yellow (dark text) | Dark yellow |
| `success` | Green | Dark green |
| `danger` | Red | Dark red |

### Dismiss Behavior

When `dismissable: true` (the default), visitors can click the close button to hide the banner. The
dismissal is stored in `sessionStorage`, so the banner stays hidden for the rest of the browsing
session but reappears after the browser is closed. If you change the announcement text, the new
message will appear even for visitors who dismissed the previous one.

### Disabling the Banner

To remove a previously configured banner, either set the key to `false` or remove it from the file
entirely:

```{.yaml filename="great-docs.yml"}
announcement: false
```

## Animated Gradient Presets

The announcement banner, navbar, and content area all support gradient backgrounds. The banner and
navbar use animated gradients that shift slowly across the element, creating a subtle, eye-catching
effect. The content area uses a soft radial glow at the top of each page. Each preset includes
paired light-mode and dark-mode color palettes.

### Available Presets

Great Docs ships with eight gradient presets. Each bar below shows the light-mode gradient on the
left and the dark-mode gradient on the right:

```{=html}
<style>
@media (max-width: 576px) {
  .gd-preset-desc { font-size: 0.6em; }
  .gd-preset-bar { height: 34px; font-size: 0.6em; }
}
</style>
<div style="display: flex; flex-direction: column; gap: 6px; margin: 1em 0;">
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #d0ecf9, #e0f4ff, #c5e8f7, #b8e0f5); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">sky</code><span class="gd-preset-desc">&ensp;Soft sky blues</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #023e8a, #0077b6, #005f73, #0096c7); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">sky</code><span class="gd-preset-desc">&ensp;Soft sky blues</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #ffddc1, #ffe4cc, #fdd0d8, #fbc4d4); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">peach</code><span class="gd-preset-desc">&ensp;Peach and blush</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #cc4a1a, #c7760f, #b84a5f, #a33560); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">peach</code><span class="gd-preset-desc">&ensp;Peach and blush</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #c4f0e0, #d0e8f5, #e4d4f4, #d8cef0); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">prism</code><span class="gd-preset-desc">&ensp;Mint, sky, and lavender</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #048a65, #0c6a8a, #52077d, #2a0978); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">prism</code><span class="gd-preset-desc">&ensp;Mint, sky, and lavender</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #e8d0f0, #f5d0e0, #f0d4f8, #eac8ee); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">lilac</code><span class="gd-preset-desc">&ensp;Lilac and pink</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #561e64, #8b1140, #a02db3, #6e1a7d); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">lilac</code><span class="gd-preset-desc">&ensp;Lilac and pink</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #e0e4e8, #eceff1, #dde2e6, #d5dadf); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">slate</code><span class="gd-preset-desc">&ensp;Cool grays</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #37474f, #455a64, #3e525e, #263238); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">slate</code><span class="gd-preset-desc">&ensp;Cool grays</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #ffe0c2, #ffedcc, #ffe5b4, #ffd6a8); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">honey</code><span class="gd-preset-desc">&ensp;Warm cream and apricot</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #bf360c, #e65100, #ef6c00, #b71c1c); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">honey</code><span class="gd-preset-desc">&ensp;Warm cream and apricot</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #d8daf0, #dddff5, #d4d0ee, #dad4f2); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">dusk</code><span class="gd-preset-desc">&ensp;Soft lavender-blue</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #0d1244, #141b55, #1a0f52, #261560); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">dusk</code><span class="gd-preset-desc">&ensp;Soft lavender-blue</span></div>
  </div>
  <div class="gd-preset-bar" style="display: flex; border-radius: 6px; overflow: hidden; height: 38px; font-size: 0.88em; font-weight: 500;">
    <div style="flex: 1; background: linear-gradient(-45deg, #ccece8, #d5f0ec, #c4e8e4, #d0f2ee); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #1a1a1a;"><code style="background: none; font-weight: 700; color: inherit;">mint</code><span class="gd-preset-desc">&ensp;Pale aqua</span></div>
    <div style="flex: 1; background: linear-gradient(-45deg, #00695c, #00796b, #004d40, #00897b); background-size: 400% 400%; display: flex; align-items: center; padding: 0 14px; color: #ffffff;"><code style="background: none; font-weight: 700; color: inherit;">mint</code><span class="gd-preset-desc">&ensp;Pale aqua</span></div>
  </div>
  <div style="display: flex; gap: 0; font-size: 0.75em; color: #888; margin-top: 2px;">
    <div style="flex: 1; text-align: center;">Light mode</div>
    <div style="flex: 1; text-align: center;">Dark mode</div>
  </div>
</div>
```

### Gradient on the Announcement Banner

Add a `style` key to the announcement config to apply a gradient background instead of the solid
color:

```{.yaml filename="great-docs.yml"}
announcement:
  content: "Version 2.0 is now available!"
  style: sky
```

When `style` is set, it overrides the solid-color `type` background with the animated gradient. The
`type` key is still used for semantic class names but has no visual effect on the background when a
gradient is active.

### Gradient on the Navbar

Use the top-level `navbar_style` key to apply the animated gradient to the site's top navigation
bar:

```{.yaml filename="great-docs.yml"}
navbar_style: peach
```

In dark mode, text and icons are automatically adjusted to white for readability.

### Gradient on the Content Area

Use the top-level `content_style` key to add a subtle radial glow at the top of the main content
area:

```{.yaml filename="great-docs.yml"}
content_style: lilac
```

The glow fades out smoothly and does not interfere with text or interactive elements. It uses the
same preset names as the banner and navbar gradients.

By default the glow appears on all pages. To restrict it to the homepage only, use the dictionary
form with a `pages` key:

```{.yaml filename="great-docs.yml"}
content_style:
  preset: lilac
  pages: homepage    # "all" (default) or "homepage"
```

### Combining All Three

You can use the same preset or different presets for the banner, navbar, and content area. Here is
an example that mixes two presets:

```{.yaml filename="great-docs.yml"}
announcement:
  content: "New release!"
  style: sky

navbar_style: sky
content_style:
  preset: lilac
  pages: homepage
```

## Accent Color

The accent color is a site-wide tint used by shortcodes (like the `{{< hr >}}` horizontal rule),
gradient presets, and other accent-colored elements. It sets the `--gd-accent` CSS custom property,
which you can also reference in custom stylesheets.

A single string applies the same color in both light and dark mode:

```{.yaml filename="great-docs.yml"}
accent_color: "#6366f1"
```

For per-mode colors, use a dictionary:

```{.yaml filename="great-docs.yml"}
accent_color:
  light: "#6366f1"
  dark: "#818cf8"
```

If you don't set an accent color, Great Docs uses its built-in defaults.

## Navbar Color

If you prefer a solid color over an animated gradient, the `navbar_color` option sets a flat
background on the navbar with automatic contrast-aware text. Great Docs uses the
[APCA (Accessible Perceptual Contrast Algorithm)](https://github.com/Myndex/SAPC-APCA) to determine
whether white or black text provides maximum readability against your chosen background.

### Single Color for Both Modes

A plain string applies the same navbar color in both light and dark mode. Any CSS named color (e.g.,
`navy`, `tomato`, `teal`) or hex value works:

```{.yaml filename="great-docs.yml"}
navbar_color: steelblue
```

### Per-Mode Colors

Use a dictionary with `light` and `dark` keys to set different navbar colors for each mode. You can
also set only one mode, and the other keeps the default navbar styling:

```{.yaml filename="great-docs.yml"}
navbar_color:
  light: "#2c3e50"
  dark: "#1a237e"
```

### How Text Color is Chosen

You do not need to specify a text color. Great Docs automatically picks white or black text (and
adjusts icons, search button, toggle, and hover states) based on the APCA contrast algorithm. Dark
backgrounds get white text; light backgrounds get black text.

### Precedence with `navbar_style`

If both `navbar_style` (animated gradient) and `navbar_color` are set, the gradient takes precedence
and `navbar_color` is ignored. To use a solid color, remove or comment out `navbar_style`:

```{.yaml filename="great-docs.yml"}
# navbar_style: peach      # commented out, so navbar_color takes effect
navbar_color: "#2c3e50"
```

## Custom Head Content {#include-in-header}

Use `include_in_header` to inject custom HTML into the `<head>` of every page. This is useful for
adding analytics scripts, custom meta tags, external stylesheets, or any other head content that
needs to load before the page renders.

A single string is treated as inline HTML:

```{.yaml filename="great-docs.yml"}
include_in_header: '<link rel="stylesheet" href="https://example.com/custom.css">'
```

For multiple entries, use a list. Each item can be a string (inline HTML) or a dictionary with a
`text` or `file` key:

```{.yaml filename="great-docs.yml"}
include_in_header:
  - text: |
      <script>
        console.log("hello from great-docs");
      </script>
  - text: '<meta name="custom" content="value">'
  - file: custom-head.html
```

Your entries are merged with Great Docs' own head injections (Font Awesome, theme scripts, etc.) so
everything cooperates automatically.

## Logo

Great Docs can display a logo in the navbar instead of the plain-text package name. Logos are
automatically detected from conventional file locations, or you can configure them explicitly.

### Auto-Detection

If you place logo files in your project using common naming conventions, Great Docs will find and
use them automatically with no configuration needed:

```
my-package/
├── logo.svg              # Primary logo
├── assets/
│   ├── logo.svg          # Also auto-detected
│   └── logo-dark.svg     # Dark-mode variant
```

Auto-detection checks these paths in priority order:

1. `logo.svg` / `logo.png` (project root)
2. `assets/logo.svg` / `assets/logo.png`
3. `docs/assets/logo.svg` / `docs/assets/logo.png`
4. `{package_name}_logo.svg` / `{package_name}_logo.png`

If a file named `logo-dark.svg` (or `{stem}-dark.{ext}`) exists alongside the primary logo, it is
automatically used for dark mode.

### Explicit Configuration

For full control, configure the logo in `great-docs.yml`:

```{.yaml filename="great-docs.yml"}
logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg
```

You can also set additional options:

```{.yaml filename="great-docs.yml"}
logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg
  alt: My Package         # Alt text (defaults to display_name)
  href: https://example.com  # Logo link target (defaults to site root)

logo_show_title: true      # Show text title alongside logo (default: false)
```

### What Happens When a Logo Is Set

When a logo is configured (or auto-detected):

- the logo image replaces the text title in the navbar.
- a dark-mode variant is used automatically when the user switches themes.
- the text title is hidden by default (set `logo_show_title: true` to show both).
- favicons are generated automatically from the logo (see below).

## Favicon

Great Docs automatically generates a complete set of favicons for your site. If a logo is
configured, favicons are derived from it with no extra setup needed. You can also specify a
dedicated favicon image.

### Automatic Generation from Logo

When a logo is set, Great Docs generates all standard favicon formats automatically:

| File | Purpose |
|------|---------|
| `favicon.ico` | Classic favicon (16, 32, and 48px embedded) |
| `favicon.svg` | Modern browsers (SVG, infinite scaling) |
| `favicon-16x16.png` | Small icon contexts |
| `favicon-32x32.png` | Standard tab icon |
| `apple-touch-icon.png` | iOS home screen (180x180) |

These files are created in the build directory and proper `<link>` tags are injected into every
page's `<head>`.

### Dedicated Favicon

If you want a different image for your favicon (for example, a simplified icon rather than the full
logo), set the `favicon` option:

```{.yaml filename="great-docs.yml"}
favicon: assets/favicon.svg
```

This generates the same set of raster variants as the logo-based approach, but uses your dedicated
favicon source image instead. Both SVG and PNG source files are supported.

### Non-Square Source Images

Source images do not need to be perfectly square. Non-square images are automatically centered on a
transparent canvas, preserving the original aspect ratio. This means wide logos will not be
distorted; they will be padded with transparency above and below.

## Hero Section

The hero section is a prominent banner displayed at the top of the landing page, showcasing the
package logo, name, tagline, and badges. It is generated automatically when a logo is present and
gives your documentation a polished, professional look.

### Auto-Enable Behavior

The hero section auto-enables when a logo is configured (or auto-detected). No explicit
configuration is needed: if you have a logo, you get a hero. The hero displays:

- the package logo (with dark-mode support)
- the package display name
- the package description from `pyproject.toml`
- badges auto-extracted from the README (shields.io badges, etc.)

### Disabling the Hero

To disable the hero entirely (for example, if you prefer your `index.qmd` or `README.md` rendered
as-is):

```{.yaml filename="great-docs.yml"}
hero: false
```

### Customizing the Hero

Each hero component can be overridden or suppressed individually. These examples add
`enabled: true` since they have no logo configured — if you already have a logo (and
therefore an auto-enabled hero), you can omit it:

```{.yaml filename="great-docs.yml"}
hero:
  enabled: true                         # Needed here since no logo is configured
  name: "My Package"                    # Override the auto-detected name
  tagline: "A better way to build things"  # Override the description
  logo_height: 120px                    # Default: 200px
  badges: false                         # Suppress badge display
```

Set any component to `false` to suppress it:

```{.yaml filename="great-docs.yml"}
hero:
  enabled: true
  name: false              # Hide the name (logo and tagline only)
  badges: false            # No badges
```

### Hero Logo vs. Navbar Logo

By default, the hero uses the same logo as the navbar. But you may want a different image for the
hero, for example a detailed wordmark instead of a compact lettermark.

Set a separate hero logo with light/dark variants:

```{.yaml filename="great-docs.yml"}
# Navbar: compact lettermark
logo:
  light: assets/logo-lettermark.svg
  dark: assets/logo-lettermark-dark.svg

# Hero: expanded wordmark
hero:
  logo:
    light: assets/logo-wordmark.svg
    dark: assets/logo-wordmark-dark.svg
  logo_height: 150px
```

Or use a simple string for a single hero logo image:

```{.yaml filename="great-docs.yml"}
hero:
  logo: assets/hero-logo.svg
```

### Hero Logo Auto-Detection

Great Docs can also auto-detect hero-specific logo files from conventional file locations, with no
configuration needed. Place files using these naming conventions:

```
my-package/
├── assets/
│   ├── logo-hero.svg          # Hero logo (single image)
│   ├── logo-hero-light.svg    # Hero logo (light variant)
│   └── logo-hero-dark.svg     # Hero logo (dark variant)
```

Auto-detection checks these paths in priority order:

1. `logo-hero.svg` / `logo-hero.png` (project root)
2. `assets/logo-hero.svg` / `assets/logo-hero.png`
3. `logo-hero-light.svg` / `logo-hero-light.png` (project root)
4. `assets/logo-hero-light.svg` / `assets/logo-hero-light.png`

If a file named `logo-hero-dark.svg` (or `logo-hero-dark.png`) exists alongside the primary hero
logo, it is automatically used for dark mode.

When hero logo files are detected, the hero section auto-enables even if no `logo` or `hero` config
is set in `great-docs.yml`.

The full logo fallback chain for the hero is:

1. explicit `hero.logo` in `great-docs.yml`
2. auto-detected hero logo files (`logo-hero.*`)
3. explicit top-level `logo` in `great-docs.yml`
4. auto-detected navbar logo files (`logo.*`)

### Explicit Badge List

By default, badges are auto-extracted from the README. You can provide an explicit list instead:

```{.yaml filename="great-docs.yml"}
hero:
  badges:
    - alt: PyPI version
      img: https://img.shields.io/pypi/v/my-package
      url: https://pypi.org/project/my-package/
    - alt: License
      img: https://img.shields.io/badge/license-MIT-green
      url: https://opensource.org/licenses/MIT
```

### Hero Section Summary

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `hero` | `bool` / `dict` | auto | `false` to disable; `true` to force-enable; dict to customize (auto-enables with a logo) |
| `hero.name` | `str` / `false` | display name | Package name shown in hero |
| `hero.tagline` | `str` / `false` | description | Tagline shown below the name |
| `hero.logo` | `str` / `dict` / `false` | auto-detect | Hero-specific logo (can have `light`/`dark` keys); auto-detects `logo-hero.*` files |
| `hero.logo_height` | `str` | `200px` | CSS max-height for the hero logo |
| `hero.badges` | `list` / `false` | `auto` | Explicit badge list or `false` to suppress |

## Navigation Icons [version-badge new 0.5]

Add [Lucide](https://lucide.dev/) icons to navbar and sidebar entries for quick visual
identification. Great Docs ships with the complete Lucide icon set (1,900+ icons) and resolves them
to lightweight inline SVGs at build time.

### Basic Setup

Map navigation labels to Lucide icon names under `nav_icons`. Use `navbar` for the top navigation
bar and `sidebar` for left-sidebar items:

```{.yaml filename="great-docs.yml"}
nav_icons:
  navbar:
    User Guide: book-open
    Reference: code-2
  sidebar:
    Getting Started: rocket
    Configuration: settings
```

Each key is the **exact text** of the navigation label as it appears in the rendered site. The value
is any [Lucide icon name](https://lucide.dev/icons/) (lowercase, hyphenated).

### Navbar Icons

Icons in the navbar appear next to the top-level links (User Guide, Reference, Recipes, etc.):

```{.yaml filename="great-docs.yml"}
nav_icons:
  navbar:
    User Guide: book-open
    Recipes: chef-hat
    Reference: code-2
```

### Sidebar Icons

Sidebar icons appear next to items and section headers in the left navigation panel. These work for
User Guide pages, custom sections, and Reference section headings:

```{.yaml filename="great-docs.yml"}
nav_icons:
  sidebar:
    # User Guide pages
    Getting Started: rocket
    Configuration: settings
    Advanced Topics: graduation-cap
    # Reference sections
    Functions: zap
    Classes: layers
    # Custom section headers
    Tutorials: lightbulb
```

You don't need to assign an icon to every item, entries without a mapping simply display as normal
text.

### Finding Icon Names

Browse the full icon set at [lucide.dev/icons](https://lucide.dev/icons/). Use the search bar to
find icons by concept: search "chart" for data visualization icons, "file" for document icons,
"settings" for configuration icons, etc.

To list all available icon names programmatically:

```python
from great_docs._icons import list_icons

print(list_icons())  # sorted list of 1,900+ names
```

::: {.callout-tip}
### Icon Naming Tips

Lucide names are lowercase and hyphen-separated. Common patterns:

- **Actions**: `download`, `upload`, `copy`, `trash-2`
- **Objects**: `file`, `folder`, `database`, `cloud`
- **Concepts**: `settings`, `search`, `bell`, `heart`
- **Numbered variants**: `code-2`, `trash-2` (alternate designs of the same concept)
:::

### Dark Mode

Icons automatically adapt to dark mode. They use `stroke="currentColor"`, so they inherit the text
color of their navigation context (no additional configuration is needed).

## Inline Icons [version-badge new 0.6]

Beyond navbar and sidebar icons, you can place Lucide icons anywhere in your `.qmd` content using
the `icon` shortcode. Icons scale with the surrounding text, sit on the baseline, and inherit the
text color.

### Basic Usage

```{shortcodes="false"}
{{< icon heart >}}
```

This renders inline: {{< icon heart >}} (sized to match the surrounding text).

A few more examples: {{< icon rocket >}} `rocket`, {{< icon star >}} `star`, {{< icon check >}} `check`, {{< icon book-open >}} `book-open`. Icon names follow the same Lucide naming convention described above.

### Size

By default icons are `1em` tall (matching the current font size). Use `size` to specify a different
size in pixels (the value is converted to `em` units so the icon still scales with its context):

```{shortcodes="false"}
{{< icon star size="12" >}}  small
{{< icon star >}}            default (16px = 1em)
{{< icon star size="24" >}}  large
{{< icon star size="32" >}}  very large
```

Result: {{< icon star size="12" >}} small · {{< icon star >}} default · {{< icon star size="24" >}} large · {{< icon star size="32" >}} very large

### Accessibility

By default icons are decorative (`aria-hidden="true"`). When an icon conveys meaning on its own,
add a `label`:

```{shortcodes="false"}
{{< icon alert-triangle label="Warning" >}}
```

This replaces `aria-hidden` with `aria-label="Warning" role="img"`, so screen readers announce the
icon's purpose.

### In Context

Icons work in headings, callouts, lists, tables, and blockquotes:

- {{< icon file-text >}} Documentation pages
- {{< icon code-2 >}} Source code references
- {{< icon test-tube >}} Testing guides

| Status | Icon | Description |
|--------|------|-------------|
| Complete | {{< icon check-circle >}} | Feature is stable |
| In progress | {{< icon loader >}} | Under active development |
| Planned | {{< icon calendar >}} | Scheduled for a future release |

::: {.callout-tip}
## {{< icon lightbulb >}} Pro Tip
Use icons sparingly to draw attention to key information without cluttering the page.
:::

## Footer Attribution

By default, Great Docs adds a small "Site created with Great Docs" attribution line in the page
footer. To hide it:

```{.yaml filename="great-docs.yml"}
attribution: false
```

## Next Steps

Great Docs gives you control over every visual aspect of your site, from broad choices like gradient
themes and dark mode down to fine details like accent colors, icon placement, and footer
attribution. Start with the defaults and customize as your project's identity evolves.

- [Configuration](configuration.qmd) covers functional settings like API discovery, parsers, and
GitHub integration
- [Internationalization](internationalization.qmd) shows how translated labels interact with your
site's visual design
- [Custom Pages](custom-pages.qmd) explains how to add standalone HTML pages that inherit your theme
- [Horizontal Rules](horizontal-rules.qmd) demonstrates the `hr` shortcode, which uses the accent
color
