Favicon and Manifest

This theme provides built-in support for favicons, Apple touch icons, and Progressive Web App (PWA) manifest configuration through a convenient helper function.

Introduction

The SIX Theme includes a getFavIcons() function that automatically configures:

• Modern favicons in multiple formats (SVG, PNG)
• Apple touch icons for iOS devices
• Web app manifest for PWA functionality
• Theme color for mobile browsers

Quick Setup

1. Add Your Icon Files

Place your favicon and icon files in the public directory of your documentation site:

docs/public/
├── favicon.svg          # Vector favicon (recommended)
├── icon-64.png         # Small favicon (64x64)
├── icon-192.png        # Standard icon (192x192)
├── icon-512.png        # Large icon (512x512)
└── manifest.json       # PWA manifest

2. Configure in astro.config.ts

Import and use the getFavIcons() function in your Astro configuration:

docs/astro.config.ts

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightThemeSix from '@six-tech/starlight-theme-six'
import { getFavIcons } from '@six-tech/starlight-theme-six/utils/favicons'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation',
      logo: {
        src: './src/assets/logo.svg',
      },
      plugins: [
        starlightThemeSix({
          // theme configuration
        })
      ],
      // Add favicon configuration
      head: [
        ...getFavIcons(), // For root deployment
        // Or for subdirectory: ...getFavIcons({ basePath: '/my-docs/' })
        // Add additional head elements here if needed
      ],
      // ... other configuration
    }),
  ],
})

Icon Requirements

Recommended Sizes

File	Size	Purpose
favicon.svg	Vector	Modern browsers (scalable)
icon-64.png	64×64	Small favicon
icon-192.png	192×192	Standard icon, Apple touch icon
icon-512.png	512×512	Large displays, PWA icon

File Formats

• SVG: Preferred for modern browsers (scalable, small file size)
• PNG: Required for compatibility and specific sizes
• ICO: Not required when using SVG + PNG combination

Manifest Configuration

Default manifest.json

The theme expects a manifest.json file in your public directory:

docs/public/manifest.json

{
  "name": "Your Site Name",
  "short_name": "Short Name",
  "description": "Your site description",
  "start_url": "/",
  "scope": "/",
  "background_color": "#0E0E0E",
  "theme_color": "#0E0E0E",
  "display": "standalone",
  "orientation": "portrait-primary",
  "categories": ["productivity", "developer"],
  "lang": "en",
  "icons": [
    {
      "src": "/Six.StarlightTheme/icon-64.png",
      "type": "image/png",
      "sizes": "64x64",
      "purpose": "any"
    },
    {
      "src": "/Six.StarlightTheme/icon-192.png",
      "type": "image/png",
      "sizes": "192x192",
      "purpose": "any maskable"
    },
    {
      "src": "/Six.StarlightTheme/icon-512.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "any maskable"
    },
    {
      "src": "/Six.StarlightTheme/favicon.svg",
      "type": "image/svg+xml",
      "sizes": "any",
      "purpose": "any"
    }
  ]
}

Customizing Colors

Update the background_color and theme_color to match your site’s design:

• Light themes: Use light colors like #ffffff
• Dark themes: Use dark colors like #0E0E0E
• Brand themes: Use your brand’s primary color

Advanced Configuration

Configuration Options

The getFavIcons() function accepts optional configuration:

docs/astro.config.ts

head: [
  // Default configuration (root deployment)
  ...getFavIcons(),

  // For subdirectory deployment (GitHub Pages, etc.)
  ...getFavIcons({ basePath: '/my-project/' }),

  // Custom theme color
  ...getFavIcons({ themeColor: '#your-brand-color' }),

  // Both options
  ...getFavIcons({
    basePath: '/my-docs/',
    themeColor: '#FF6B6B'
  }),
],

Adding Additional Head Elements

You can extend the head configuration with additional elements:

docs/astro.config.ts

head: [
  ...getFavIcons({ basePath: '/my-docs/' }),
  // Add custom meta tags
  {
    tag: 'meta',
    attrs: {
      name: 'author',
      content: 'Your Name'
    }
  },
  // Add custom stylesheets
  {
    tag: 'link',
    attrs: {
      rel: 'stylesheet',
      href: '/custom-styles.css'
    }
  }
],

# Testing Your Configuration

After setting up your favicons and manifest:

1. **Build your site**: `npm run build`
2. **Test in browsers**: Check that favicons appear in tabs and bookmarks
3. **Test on mobile**: Verify Apple touch icons work on iOS
4. **PWA testing**: Use browser dev tools to test manifest functionality
5. **Lighthouse audit**: Run a Lighthouse audit to verify PWA compliance

# Troubleshooting

## Icons Not Appearing

- Ensure files are in the `public` directory, not `src`
- Check file names match exactly (case-sensitive)
- Verify file formats are correct (PNG for specific sizes, SVG for vector)
- Clear browser cache and hard refresh

## Manifest Issues

- Validate your `manifest.json` using online validators
- Ensure all icon paths in the manifest match actual files
- Check that `start_url` and `scope` are correctly configured
- Verify colors are valid hex codes

## Build Errors

- Make sure `getFavIcons` is properly imported from `@six-tech/starlight-theme-six/utils/favicons`
- Check for syntax errors in `astro.config.ts`
- Ensure all file references exist in the `public` directory
- Verify the theme package is properly installed

# Browser Support

| Feature           | Support                                              |
|-------------------|------------------------------------------------------|
| SVG Favicons      | Modern browsers (Chrome 80+, Firefox 41+, Safari 9+) |
| PNG Favicons      | All browsers                                         |
| Apple Touch Icons | iOS Safari, Chrome on iOS                            |
| Web Manifest      | Modern browsers with PWA support                     |
| Theme Color       | Mobile browsers (Chrome, Safari)                     |