---
title: "Add a Logo and Favicon"
description: "Display your package's logo in the navbar and generate favicons automatically."
tags: [Theming, Branding]
---

# Add a Logo and Favicon

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

1. `logo.svg` or `logo.png` in the project root
2. `assets/logo.svg` or `assets/logo.png`
3. `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`:

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

You can also set extra options:

```{.yaml filename="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:

```{.yaml filename="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](../user-guide/theming.html) page in the User Guide.
