Logo and favicon

The logo and favicon fields in docs.json point at image files committed to your docs repo. Bloques serves them from your site's domain, so private repos work without making the files public.

Logo

Set logo to the path of an image in your repo. It replaces the site name in the top-left of the navbar.

{
  "logo": "/logo.svg"
}

Paths resolve from the repo root. /logo.svg, logo.svg, and ./logo.svg all point at the same file.

Light and dark variants

Most logos need a second version for dark mode. Pass an object instead of a string:

{
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  }
}

The light logo renders in light mode, dark in dark mode. The swap is pure CSS, so the correct logo shows on first paint. Omit dark to use the same image in both modes.

Link target

The logo links to your site's home page. Point it somewhere else with href:

{
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg",
    "href": "https://acme.com"
  }
}

Sizing

Bloques renders the logo 24 pixels tall and scales the width to match, up to 160 pixels. Export your file at 2× (48 pixels tall) or use an SVG so it stays sharp on high-density screens.

Your site name still reaches screen readers and search engines — Bloques uses it as the logo's alt text.

Favicon

Set favicon to the icon shown in the browser tab.

{
  "favicon": "/favicon.png"
}

Favicons take the same light and dark object form as logo:

{
  "favicon": {
    "light": "/favicon/light.png",
    "dark": "/favicon/dark.png"
  }
}

Browsers pick the variant that matches the reader's system theme. Support varies by browser — Safari and Chrome honor it, older browsers fall back to light.

Supported formats

png, jpg, jpeg, gif, webp, avif, svg, ico, and bmp.

SVG is the best choice for logos — one file covers every screen density. Use PNG for favicons, since some browsers reject SVG icons.

Bloques ignores paths that point outside the repo or at a non-image file, and renders the site name instead.

External URLs

An absolute https:// URL works and Bloques serves it untouched:

{
  "logo": "https://cdn.acme.com/logo.svg"
}

Files in your repo are the better default — they're versioned with your docs and stay available if the CDN goes down.

Limitations

• No upload. Logos come from your repo. Commit the file, then reference it.
• Previews read the default branch. A logo committed to a branch renders broken in live preview until you merge. Images already on your default branch preview correctly.

Next steps

• Theme — match the site palette to your brand.
• Navbar — add links beside the logo.
• Schema reference — every docs.json field.