# Site Identity

All core identity settings live in `settings/meta.md`. These values control your site title, brand name, description, URL, logo, and favicon. Edit any value and save — the site rebuilds automatically.

## Settings

```yaml
# settings/meta.md
---
# Site title — used in <title> tags and as fallback page title
title: My Site

# Brand name — displayed in header and footer
# Can be overridden per-location in header.md or footer.md
brandName: My Site

description: A site built with sitemd.
url: https://example.com

# Brand logo — used when brandDisplay includes "image" (see header.md)
# Place in media/ or theme/images/. SVG recommended for crisp rendering.
# Supports image modifiers: /media/logo.png +circle +bw +height:32
brandImage: /theme/images/logo.svg

# Favicon: letter (auto from title + accent), brand (uses brandImage), custom (upload)
favicon: letter
# Custom favicon source (PNG/SVG, min 512×512, place in media/favicon/)
customFavicon:
---
```

## Title

The `title` field sets your site's identity. It appears in:

- The `<title>` tag as a fallback when a page has no title
- The auto-derived `titleSuffix` (e.g. " | My Site") appended to every page title
- The auto-generated favicon letter when `favicon` is set to `letter`
- JSON-LD structured data

## Brand Name

`brandName` is the display name shown in the header and footer. It defaults to the same value as `title`, but you can set them independently — use `title` for SEO/technical purposes and `brandName` for how your brand appears visually.

`brandName` and `brandImage` also serve as defaults for the [Organization schema](/docs/seo#organization-schema) on your homepage. Override `orgName` and `orgLogo` in `settings/seo.md` if your legal entity name differs from your brand.

The header and footer can each override `brandName` with their own `brandName` field in `settings/header.md` or `settings/footer.md`.

## Description

A short summary of your site. Used as the fallback `<meta name="description">` on the homepage and in structured data.

## URL

The canonical URL of your site (e.g. `https://example.com`). Used for:

- Canonical URL generation on every page
- Open Graph `og:url` tags
- Sitemap URLs
- Structured data
- Site activation (the hostname is extracted and locked as part of the [site fingerprint](/docs/how-to-activate-site))
- Deploy target custom domain registration (e.g. Cloudflare Pages)

Leave blank during local development. Set it when you're ready to [deploy](/docs/deploy).

## Brand Image (Logo)

The `brandImage` field points to your logo file. Place it in `media/` or `theme/images/` and reference it with an absolute path:

```yaml
brandImage: /media/logo.svg
```

SVG is recommended for crisp rendering at any size. PNG and JPG also work.

The logo only appears when `brandDisplay` in `settings/header.md` or `settings/footer.md` includes "image":

| `brandDisplay` value | What it shows |
|---|---|
| `text` | Brand name only (default) |
| `image-text` | Logo left, name right |
| `text-image` | Name left, logo right |
| `image` | Logo only |

Brand images support [image modifiers](/docs/images#image-modifiers) — append them directly to the `brandImage` value:

```yaml
brandImage: /media/logo.png +circle +bw +height:32
```

Modifiers are applied everywhere the brand image appears — header, footer, and inline. See [Brand Display](/docs/brand-display) for full details on display modes, footer brand, and content variables.

The default is `/theme/images/logo.svg` — a placeholder included with every new project.

## Favicon

Your site's favicon is generated automatically on every build when [Sharp](https://sharp.pixelplumbing.com/) is installed. No design work required — every site gets a favicon out of the box.

### How does the favicon setting work?

The `favicon` setting in `settings/meta.md` controls which source is used:

| Mode | Description |
|---|---|
| `letter` | Auto-generates a letter icon from your site title's first character, colored with each theme mode's accent color (default) |
| `brand` | Uses your `brandImage` (logo) as the favicon source |
| `custom` | Uses a custom image you upload to `media/favicon/` |

### What files are generated?

Every build produces these files in your site output:

| File | Size | Purpose |
|---|---|---|
| `favicon.svg` | Vector | Primary favicon for modern browsers |
| `favicon-light.svg` | Vector | Accent color from light mode (letter mode only) |
| `favicon-dark.svg` | Vector | Accent color from dark mode (letter mode only) |
| `favicon-paper.svg` | Vector | Accent color from paper mode (letter mode only) |
| `favicon.ico` | 48×48 | Legacy browsers |
| `apple-touch-icon.png` | 180×180 | iOS home screen |

### Does the favicon change with the theme?

Yes. In `letter` mode, the favicon accent color updates live when a visitor toggles between light, dark, and paper modes. Each mode's `color-accent` from `settings/theme.md` is used — so a site with blue accents in light/dark mode and teal in paper mode will show the matching color in the browser tab.

The `.ico` and `apple-touch-icon.png` are static and use the `defaultMode` accent color.

### How do I use a custom favicon?

Set `favicon: custom` and provide the filename in `customFavicon`:

```yaml
favicon: custom
customFavicon: my-icon.svg
```

Place the source image in `media/favicon/`. PNG or SVG, minimum 512×512. The build system generates all sizes automatically.

### How do I use my logo as the favicon?

Set `favicon: brand` — the build system uses whatever `brandImage` points to:

```yaml
favicon: brand
brandImage: /media/logo.svg
```

## Settings Reference

| Setting | Default | Description |
|---|---|---|
| `title` | `My Site` | Site title for `<title>` tags, titleSuffix derivation, and structured data |
| `brandName` | same as `title` | Display name in header and footer |
| `description` | — | Site-wide meta description and structured data summary |
| `url` | — | Canonical URL — also used for activation fingerprint and deploy custom domain |
| `brandImage` | `/theme/images/logo.svg` | Logo path for brand display (supports image modifiers) |
| `favicon` | `letter` | Favicon mode: `letter` (auto from title), `brand` (uses brandImage), `custom` (upload) |
| `customFavicon` | — | Filename in `media/favicon/` (used when `favicon: custom`) |

## Related

- [Brand Display](/docs/brand-display) — display modes, image modifiers, footer brand, and content variables
- [Header](/docs/header) — brand display mode, navigation, and header-specific overrides
- [Footer](/docs/footer) — footer brand display, social links, and copyright
- [SEO](/docs/seo) — title suffix, OG images, and favicon generation details
- [Themes](/docs/themes) — accent color per mode used in auto-generated favicons