Assets Directory

This directory contains branding assets for your documentation site. Replace the placeholder files with your organization's logo and favicon to customize the site's appearance.

Quick Start

Replace these two files to brand your documentation site:

logo.svg - Displayed in the site header and navigation
favicon.svg - Browser tab icon

After replacing the files, commit and push your changes. GitHub Pages will rebuild the site automatically (2-3 minutes).

Asset Specifications

Logo (`logo.svg`)

Purpose: Main brand identity shown in the site header.

Recommended specifications:

Format: SVG (preferred) or PNG
Dimensions: 200px width × 48px height (4:1 aspect ratio)
Aspect ratios: 4:1 to 5:1 work well
File size: Keep under 50 KB for fast loading
Background: Transparent or solid (matches your color scheme)
Colors: Use your primary brand color or full-color logo

Where it appears:

Site header (top-left corner)
Navigation sidebar (desktop view)
Mobile menu (collapsed nav)

Design tips:

Use a horizontal logo variant (vertical logos don't fit well)
Ensure good contrast against the header background color
Test visibility in both light and dark modes if supporting both
Include your organization name in the logo for recognition
Avoid very thin lines or small text (may not render well at small sizes)

File naming:

Default: logo.svg
Custom: Update branding.logo_path in docs/_config.yml

SVG optimization:

# Install SVGO (optional, for optimization)
npm install -g svgo

# Optimize your SVG
svgo logo.svg -o logo-optimized.svg

Favicon (`favicon.svg`)

Purpose: Small icon shown in browser tabs, bookmarks, and shortcuts.

Recommended specifications:

Format: SVG (preferred) or PNG
Dimensions: 48px × 48px (square)
Aspect ratio: 1:1 (square)
File size: Keep under 10 KB
Background: Transparent or solid color
Colors: Simple, high-contrast design

Where it appears:

Browser tab (next to page title)
Bookmark bar
History
Mobile home screen shortcuts

Design tips:

Use a simplified version of your logo (icon only, no text)
Ensure it's recognizable at 16x16px (smallest size)
Use solid shapes and bold lines (avoid fine details)
Test on light and dark browser themes
Consider using your brand's icon mark or monogram

File naming:

Default: favicon.svg
Custom: Update branding.favicon_path in docs/_config.yml

Multi-size support (optional, advanced):

For maximum compatibility, you can provide multiple favicon sizes:

Create a favicon.ico with multiple sizes embedded:

# Using ImageMagick
convert favicon-16.png favicon-32.png favicon-48.png favicon-64.png favicon.ico

Update HTML in docs/_includes/head_custom.html:

<link rel="icon" type="image/svg+xml" href="/os-guidelines/assets/favicon.svg">
<link rel="icon" type="image/png" sizes="32x32" href="/os-guidelines/assets/favicon-32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/os-guidelines/assets/favicon-16.png">
<link rel="shortcut icon" href="/os-guidelines/assets/favicon.ico">

File Formats

SVG (Recommended)

Advantages:

Scalable to any size without quality loss
Small file size
Supports transparency
Can be styled with CSS (color changes)
Works on all modern browsers

Best for:

Logo with text
Icon-based favicons
Responsive designs

Browser support: All modern browsers (IE 11+ for favicons)

Example SVG structure:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 48">
  <rect fill="#FF6B35" width="200" height="48" rx="4"/>
  <text x="100" y="30" font-family="Arial" font-size="24"
        fill="white" text-anchor="middle">Your Org</text>
</svg>

PNG (Alternative)

Advantages:

Universal browser support (including old browsers)
Good for photographic logos
Supports transparency

Best for:

Complex gradients
Photographic elements
Maximum compatibility

Requirements:

Use transparent background (unless your design requires solid)
Export at 2x resolution for retina displays (e.g., 400×96 for logo)
Optimize file size with tools like TinyPNG

Export settings:

Color mode: RGB (not CMYK)
Bit depth: 24-bit with alpha channel (PNG-24)
Compression: Maximum (lossless)

How to Replace Assets

Method 1: GitHub Web Interface (Easiest)

Navigate to your repository on GitHub
Go to docs/assets/ directory
Click "Add file" > "Upload files"
Drag and drop your logo.svg and favicon.svg
Scroll down and click "Commit changes"
Wait 2-3 minutes for GitHub Pages to rebuild

Method 2: Git Command Line

# Clone your repository (if not already cloned)
git clone https://github.com/your-org/your-repo.git
cd your-repo

# Copy your assets
cp /path/to/your-logo.svg docs/assets/logo.svg
cp /path/to/your-favicon.svg docs/assets/favicon.svg

# Commit and push
git add docs/assets/
git commit -m "Add organization branding assets"
git push origin main

Method 3: GitHub Desktop

Open your repository in GitHub Desktop
Navigate to docs/assets/ in your file system
Replace logo.svg and favicon.svg with your files
Return to GitHub Desktop (changes will appear)
Add commit message: "Add organization branding assets"
Click "Commit to main"
Click "Push origin"

Custom Asset Paths

If you want to use different file names or organize assets differently:

Using Custom Paths

Edit docs/_config.yml:

branding:
  logo_path: "assets/images/company-logo.svg"
  favicon_path: "assets/icons/site-icon.svg"

Using External URLs

You can also reference assets from external URLs (CDN, corporate website):

branding:
  logo_path: "https://cdn.yourorg.com/logo.svg"
  favicon_path: "https://cdn.yourorg.com/favicon.svg"

Note: External URLs may slow down page load if the external server is slow.

Design Recommendations

Color and Contrast

Logo contrast:

Test logo visibility against header background
Aim for WCAG AA contrast ratio (4.5:1 minimum)
Consider providing separate light/dark logo variants

Checking contrast:

Use WebAIM Contrast Checker
Test with browser dev tools (disable colors, check grayscale)
Verify in both light and dark modes (if supporting both)

Accessibility

Alt text: Logo alt text is set in docs/_config.yml:

organization:
  name: "Your Organization"  # Used as alt text

Semantic HTML: The logo uses proper semantic markup:

<a href="/" class="site-title">
  <img src="" alt="Ondřej Chrastina">
</a>

Keyboard navigation: Logo is accessible via keyboard (Tab key).

Performance

Optimizing SVG files:

Remove unnecessary metadata from SVG files:

# Using SVGO
svgo logo.svg --multipass --pretty

Optimizing PNG files:

Compress PNG without visible quality loss:

# Using ImageMagick
convert logo.png -strip -quality 90 logo-optimized.png

# Or use online tools:
# - TinyPNG: https://tinypng.com/
# - Squoosh: https://squoosh.app/

Lazy loading (optional):

For below-the-fold images, add lazy loading:

<img src="image.svg" alt="Description" loading="lazy">

Common Issues and Solutions

Logo Not Displaying

Symptom: Broken image icon in header

Solutions:

Verify file exists at docs/assets/logo.svg
Check file name matches exactly (case-sensitive)
Confirm file is committed and pushed to GitHub
Wait 2-3 minutes for GitHub Pages rebuild
Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
Check branding.logo_path in _config.yml matches file location

Logo Too Large or Too Small

Symptom: Logo doesn't fit well in header

Solutions:

Resize your logo to recommended dimensions (200×48px)

Adjust CSS in docs/_sass/custom/custom.scss:

.site-title img {
  max-width: 200px;
  max-height: 48px;
}

Favicon Not Updating

Symptom: Old favicon still appears after replacement

Solutions:

Clear browser cache (favicon is aggressively cached)
Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
Try incognito/private browsing window
Check browser dev tools > Network tab (should show 200 status)
Wait up to 24 hours for browser cache to expire

SVG Not Rendering

Symptom: SVG appears as broken image or doesn't display

Solutions:

Validate SVG syntax with SVG Validator

Ensure SVG has proper XML declaration:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 48">

Remove Adobe Illustrator metadata (use SVGO)
Convert to PNG as fallback if issues persist

Poor Contrast

Symptom: Logo hard to see against background

Solutions:

Adjust logo colors to match theme
Add stroke/outline to logo shapes

Change header background color in _config.yml:

branding:
  accent_color: "#1A1A1D"  # Darker background

Create separate light/dark logo variants

File Size Too Large

Symptom: Slow page load, large repository size

Solutions:

Optimize SVG with SVGO (can reduce size 50-80%)
Compress PNG with TinyPNG or ImageMagick
Consider using fewer colors
Remove embedded fonts from SVG (use web fonts instead)
Use external CDN for assets instead of repository storage

Asset Creation Tools

Vector Graphics (SVG)

Professional tools:

Adobe Illustrator (industry standard)
Sketch (Mac only, popular for web design)
Figma (web-based, free tier available)
Affinity Designer (one-time purchase)

Free alternatives:

Inkscape (open source, cross-platform)
Vectr (simple, web-based)
Boxy SVG (Chrome extension)

Raster Graphics (PNG)

Professional tools:

Adobe Photoshop
Affinity Photo

Free alternatives:

GIMP (open source, cross-platform)
Photopea (web-based Photoshop alternative)
Paint.NET (Windows only)

Online Favicon Generators

If you don't have design tools, use online generators:

RealFaviconGenerator - Comprehensive favicon generator
Favicon.io - Simple text-to-favicon tool
Canva - Logo and icon creator (free tier)

Advanced Customization

Animated Logo (SVG)

Add CSS animations to your SVG logo:

<!-- docs/assets/logo.svg -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 48">
  <style>
    @keyframes fadeIn {
      from { opacity: 0; }
      to { opacity: 1; }
    }
    .animated {
      animation: fadeIn 1s ease-in;
    }
  </style>
  <rect class="animated" fill="#FF6B35" width="200" height="48" rx="4"/>
</svg>

Responsive Logo Variants

Use different logos for desktop vs. mobile:

<!-- docs/_includes/head_custom.html -->
<picture>
  <source media="(max-width: 768px)" srcset="/os-guidelines/assets/logo-mobile.svg">
  <img src="/os-guidelines/assets/logo.svg" alt="Ondřej Chrastina">
</picture>

Dark Mode Logo Switching

Automatically switch logo based on user's color scheme:

// docs/_sass/custom/custom.scss
@media (prefers-color-scheme: dark) {
  .site-title img {
    content: url('/assets/logo-dark.svg');
  }
}

@media (prefers-color-scheme: light) {
  .site-title img {
    content: url('/assets/logo-light.svg');
  }
}

Additional Assets

You can add other assets to this directory as needed:

Screenshots and Diagrams

docs/assets/
├── screenshots/
│   ├── setup-step-1.png
│   ├── setup-step-2.png
│   └── setup-step-3.png
└── diagrams/
    ├── architecture.svg
    └── workflow.svg

Reference in markdown:

![Setup Step 1](assets/screenshots/setup-step-1.png)

Icons and Graphics

docs/assets/
└── icons/
    ├── github.svg
    ├── twitter.svg
    └── discord.svg

Custom Fonts (Optional)

docs/assets/
└── fonts/
    ├── custom-font.woff2
    └── custom-font.woff

Load in docs/_sass/custom/custom.scss:

@font-face {
  font-family: 'CustomFont';
  src: url('/assets/fonts/custom-font.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
}

body {
  font-family: 'CustomFont', sans-serif;
}

Getting Help

Asset design questions:

Figma Community - Free design resources
r/logodesign - Logo feedback community
Dribbble - Design inspiration

Technical issues:

Jekyll Documentation - Asset handling in Jekyll
Just the Docs - Theme documentation
GitHub Issues - Report template-specific issues

Need professional help:

Hire a designer on Fiverr, Upwork, or 99designs
Contact your organization's marketing/design team
Engage a design agency for comprehensive branding

Checklist

Before finalizing your assets:

[ ] Logo is 200×48px (or similar 4:1 aspect ratio)
[ ] Favicon is 48×48px (square)
[ ] Both files are optimized (small file size)
[ ] Logo has good contrast against header background
[ ] Favicon is recognizable at 16×16px
[ ] SVG files are valid and render correctly
[ ] Files are committed and pushed to GitHub
[ ] Site rebuilds successfully (check Actions tab)
[ ] Assets display correctly on live site
[ ] Tested on desktop and mobile
[ ] Tested in multiple browsers (Chrome, Firefox, Safari)
[ ] Favicon appears in browser tab

Last updated: 2026-01-31

Assets Directory

Quick Start

Asset Specifications

Logo (logo.svg)

Favicon (favicon.svg)

File Formats

SVG (Recommended)

PNG (Alternative)

How to Replace Assets

Method 1: GitHub Web Interface (Easiest)

Method 2: Git Command Line

Method 3: GitHub Desktop

Custom Asset Paths

Using Custom Paths

Using External URLs

Design Recommendations

Color and Contrast

Accessibility

Performance

Common Issues and Solutions

Logo Not Displaying

Logo Too Large or Too Small

Favicon Not Updating

SVG Not Rendering

Poor Contrast

File Size Too Large

Asset Creation Tools

Vector Graphics (SVG)

Raster Graphics (PNG)

Online Favicon Generators

Advanced Customization

Animated Logo (SVG)

Responsive Logo Variants

Dark Mode Logo Switching

Additional Assets

Screenshots and Diagrams

Icons and Graphics

Custom Fonts (Optional)

Getting Help

Checklist

Logo (`logo.svg`)

Favicon (`favicon.svg`)