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.

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:

great-docs.yml
dark_mode_toggle: true   # Enabled by default
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.

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:

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.

Keyboard Navigation New in 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:

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:

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:

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:

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:

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:

sky Soft sky blues
sky Soft sky blues
peach Peach and blush
peach Peach and blush
prism Mint, sky, and lavender
prism Mint, sky, and lavender
lilac Lilac and pink
lilac Lilac and pink
slate Cool grays
slate Cool grays
honey Warm cream and apricot
honey Warm cream and apricot
dusk Soft lavender-blue
dusk Soft lavender-blue
mint Pale aqua
mint Pale aqua
Light mode
Dark mode

Gradient on the Announcement Banner

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

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:

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:

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:

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:

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 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:

great-docs.yml
accent_color: "#6366f1"

For per-mode colors, use a dictionary:

great-docs.yml
accent_color:
  light: "#6366f1"
  dark: "#818cf8"

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

Custom Head Content

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:

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:

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.

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.

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:

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):

great-docs.yml
hero: false

Customizing the Hero

Each hero component can be overridden or suppressed individually:

great-docs.yml
hero:
  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:

great-docs.yml
hero:
  name: false              # Hide the name (logo and tagline only)
  badges: false            # No badges

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:

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 or {} to enable; dict to customize
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

Inline Icons New in 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

{{< icon heart >}}

This renders inline: (sized to match the surrounding text).

A few more examples: rocket, star, check, 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):

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

Result: small · default · large · very large

Accessibility

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

{{< 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:

  • Documentation pages
  • Source code references
  • Testing guides
Status Icon Description
Complete

Feature is stable
In progress

Under active development
Planned

Scheduled for a future release
Tip Pro Tip

Use icons sparingly to draw attention to key information without cluttering the page.

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 covers functional settings like API discovery, parsers, and GitHub integration
  • Internationalization shows how translated labels interact with your site’s visual design
  • Custom Pages explains how to add standalone HTML pages that inherit your theme
  • Horizontal Rules demonstrates the hr shortcode, which uses the accent color