Zum Hauptinhalt springen

Logo and favicon

Brand extraction grabs a logo and favicon from your website on URL onboarding. It's right about 80% of the time. The 20% is when your site has multiple logos (header + footer + email + favicon all different), and Docsio picks one that isn't the canonical version. Here's how to fix it.

Project settings → Branding → upload logo.svg or logo.png. SVG renders sharper at any size; use PNG only if you don't have a vector version.

A few things people miss:

  • Light mode + dark mode logos can be different files. Settings → Branding → toggle "Different logo for dark mode" and upload a second one.
  • The navbar logo is rendered in a flex container roughly 28–32px tall. Provide a logo at 2× that resolution (so 64px tall PNG) for retina displays.
  • If your logo includes the wordmark, leave the project's site title field empty so it doesn't render twice next to the image.

Favicon — the boring stuff that matters

Browsers use the favicon in tabs, bookmarks, history, and "Add to Home Screen". Most teams ship a single 32×32 PNG and call it done; that's not enough.

Project settings → Branding → Favicon. Upload an SVG and a 180×180 PNG.

  • SVG favicon — modern browsers prefer this. It scales cleanly to 16×16, 32×32, and 64×64 without aliasing.
  • 180×180 PNG — this becomes the apple-touch-icon. iOS uses it when someone bookmarks your docs to their home screen.
  • Background — favicons render at 16×16 in browser tabs. A logo with a thin stroke or fine detail disappears at that size. If yours does, ship a simplified favicon — a single character, a monogram, or your shortest visual mark.

Open Graph image

When someone shares a link to your docs on Slack, X, LinkedIn, the OG image is what shows up. Project settings → Branding → OG image. 1200×630 PNG.

If you don't upload one, Docsio auto-generates a clean one from your logo + page title. Auto-generated is fine for v1; ship a real OG image when you have one.

Common issues

  • Logo too dark in dark mode — upload a light variant.
  • Favicon shows generic Docusaurus icon — your favicon upload didn't take. Re-upload as SVG, then republish.
  • OG image is blurry on Twitter — Twitter prefers 2:1 ratio. 1200×600 instead of 1200×630.
  • Logo blurry on mobile — your file is a low-resolution PNG. Use SVG.

What we don't recommend

Animated SVGs. Lottie files. Gradients with thin lines. Logos that include the URL or the year. None of these survive the "will this still look right at 16×16 next to a dozen other browser tabs" test.