Add a Logo and Favicon

Display your package’s logo in the navbar and generate favicons automatically.

A logo replaces the plain-text package name in the navbar and gives your documentation site a polished, branded look. Great Docs also generates a full set of favicons from your logo image, so browser tabs and bookmarks show your package icon.

Auto-Detection

The simplest approach is to place your logo files in a conventional location. Great Docs checks these paths automatically during the build (in priority order):

logo.svg or logo.png in the project root
assets/logo.svg or assets/logo.png
docs/assets/logo.svg or docs/assets/logo.png

If it finds a logo file, no configuration is needed. Place your file and run great-docs build.

Dark-Mode Variant

For best results in both light and dark themes, provide a second logo file with -dark in the name. Place it alongside the primary logo:

my-package/
├── assets/
│   ├── logo.svg          # Used in light mode
│   └── logo-dark.svg     # Used in dark mode

The dark variant is detected automatically when it shares the same stem as the primary logo.

Explicit Configuration

If your files do not follow the naming conventions above, you can specify them directly in great-docs.yml:

great-docs.yml

logo:
  light: path/to/my-logo.svg
  dark: path/to/my-logo-dark.svg

You can also set extra options:

great-docs.yml

logo:
  light: assets/logo.svg
  dark: assets/logo-dark.svg
  alt: My Package            # Alt text for accessibility
  href: https://example.com  # Where the logo links to (defaults to site root)

logo_show_title: true         # Show the text title next to the logo

Favicon Generation

When a logo is present, Great Docs generates these favicon files during the build:

File	Purpose
`favicon.ico`	Classic favicon (16, 32, and 48px)
`favicon.svg`	Scalable icon for modern browsers
`favicon-16x16.png`	Small icon contexts
`favicon-32x32.png`	Standard tab icon
`apple-touch-icon.png`	iOS home screen (180x180)

All the necessary <link> tags are injected into every page automatically.

Dedicated Favicon

If you want a different image for the favicon (for example, a simplified lettermark instead of the full logo), set the favicon option:

great-docs.yml

favicon: assets/favicon.svg

This generates the same set of raster formats but uses your dedicated source image instead of the logo.

Tips on Logo Files

SVG is the recommended format because it scales cleanly at any size. If you use PNG, aim for at least 400px wide to look sharp on high-DPI displays.

Non-square images are handled gracefully. The favicon generator centers the image on a transparent canvas and preserves the original aspect ratio, so wide logos will not be distorted.

For the full reference on logos, favicons, and the hero section, see the Theming & Appearance page in the User Guide.