Customization & Branding

Customize colors, fonts, components, and branding for your organization

Learn how to customize this framework to match your brand identity and requirements.

Branding Configuration

Update Site Metadata

Edit src/config/site.ts:

export const siteConfig = {
  // Site name
  name: 'Your Company Documentation',
  
  // Meta description
  description: 'Complete documentation for your product',
  
  // Primary domain
  url: 'https://docs.yourcompany.com',
  
  // Organization info
  author: 'Your Company Name',
  
  // Links in footer/header
  links: {
    github: 'https://github.com/yourcompany',
    website: 'https://yourcompany.com',
    contact: 'support@yourcompany.com',
  }
};

Color Customization

Change Brand Colors

Edit src/styles/global.css:

:root {
  /* Primary brand color */
  --brand: #0066cc;
  
  /* Hover/active state */
  --brand-hover: #004499;
  
  /* Light background variant */
  --brand-contrast: #f8fbff;
  
  /* Text colors */
  --text-primary: #1d1d1f;
  --text-secondary: #3a3a3e;
  
  /* Borders and dividers */
  --border-subtle: #e8e8ed;
  
  /* Background */
  --app-bg: #f5f5f7;
  --surface: #ffffff;
  --surface-muted: #fbfbfd;
}

Color Palette Example

Technology Brand:

--brand: #007acc;        /* Blue */
--brand-hover: #005a9e;  /* Darker blue */

Creative Brand:

--brand: #ff6b6b;        /* Red */
--brand-hover: #ee5a52;  /* Darker red */

Healthcare Brand:

--brand: #00a854;        /* Green */
--brand-hover: #007d3a;  /* Darker green */

Typography Customization

Change Fonts

The framework uses Inter by default. To use a different font:

Install new font from Fontsource:

npm install @fontsource/roboto    # Example: Roboto

Update src/layouts/DocsLayout.astro:

// Replace:
import '@fontsource/inter/300.css';
import '@fontsource/inter/400.css';
import '@fontsource/inter/500.css';
import '@fontsource/inter/600.css';

// With:
import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/600.css';

Update src/styles/global.css:

:root {
  --font-sans: 'Roboto', sans-serif;
  --font-display: 'Roboto', sans-serif;
}

Adjust Type Scale

Edit the font size clamp in src/styles/global.css:

body {
  /* Default: 15.5px to 17px responsive */
  font-size: clamp(15.5px, 0.5vw + 14px, 17px);
  
  /* More dramatic: */
  font-size: clamp(14px, 1vw + 12px, 18px);
  
  /* More subtle: */
  font-size: clamp(15px, 0.3vw + 15px, 16px);
}

Layout & Spacing

In src/layouts/DocsLayout.astro, find the sidebar:

<!-- Change w-72 (288px) to your preferred width -->
<aside class="fixed inset-y-0 left-0 z-30 hidden w-80 ...">
                                                    ^^^
<!-- Width options: w-64 (256px), w-72 (288px), w-80 (320px) -->

Right sidebar:

<!-- Change w-64 (256px) to your preferred width -->
<aside class="fixed inset-y-0 right-0 z-30 hidden w-64 ...">
                                                    ^^^

Adjust Content Max Width

In src/layouts/DocsLayout.astro:

<div class="mx-auto w-full max-w-5xl ...">
                          ^^^^^^^
  <!-- Options: max-w-3xl, max-w-4xl, max-w-5xl, max-w-6xl, max-w-7xl -->
</div>

Logo & Images

Add Custom Logo

Place logo in src/components/ or src/assets/
Update the sidebar header in src/layouts/DocsLayout.astro:

<!-- Current logo: -->
<svg class="h-8 w-8 text-blue-600" ...>
  <path ... />
</svg>

<!-- Replace with: -->
<img 
  src="/logo.png" 
  alt="Your Logo" 
  class="h-8 w-8 object-contain" 
/>

Update Favicon

Place your favicon in public/favicon.ico
Update src/layouts/DocsLayout.astro head:

<head>
  <link rel="icon" href="/favicon.ico" type="image/x-icon" />
  <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
</head>

Change Icon Set

Edit the shared Lucide registry in src/lib/doc-icons.ts:

export const docIconMap = {
  'book-open': BookOpen,
  rocket: Rocket,
  'pen-tool': PenTool,
  'cloud-upload': CloudUpload,
  'shield-check': ShieldCheck,
};

Recommended semantic icon choices:

book-open for docs and reference content
rocket for onboarding and fast starts
pen-tool for authoring workflows
cloud-upload for deployment and publishing
shield-check for security and policy material
life-buoy for troubleshooting and support

Use in front matter:

---
title: "Settings"
icon: "settings-2"
---

Animation Customization

Adjust Animation Duration

Edit GSAP animations in src/layouts/DocsLayout.astro:

gsap.from('.js-doc-topbar', {
  y: -12,
  opacity: 0,
  duration: 0.55,    // Faster (0.3) or slower (1.0)
  ease: 'power2.out' // Try: 'power1.out', 'sine.out', 'back.out'
});

Disable Animations

For users with prefers-reduced-motion, animations are already disabled.

To disable all animations, comment out the animation scripts in src/layouts/DocsLayout.astro.

CSS Classes

Custom Button Styles

Edit src/styles/global.css:

.hig-button-primary {
  /* Your custom styles */
  background: var(--brand);
  color: white;
  padding: 0.75rem 1.5rem;
  border-radius: 8px;  /* Change roundness */
  font-weight: 500;
}

Custom Card Styles

.hig-card {
  background: white;
  border-radius: 12px;  /* Change this */
  border: 1px solid var(--border-subtle);
  padding: 1.5rem;
}

Dark Mode (Optional)

To add dark mode support, extend src/styles/global.css:

@media (prefers-color-scheme: dark) {
  :root {
    color-scheme: dark;
    --app-bg: #1d1d1f;
    --surface: #2d2d2f;
    --text-primary: #f5f5f7;
    --text-secondary: #a1a1a6;
    --border-subtle: #424245;
    --brand: #0084ff;
  }
}

And update src/styles/global.css base styles to use CSS variables.

Tailwind Configuration

Extend Tailwind configuration in tailwind.config.cjs:

export default {
  theme: {
    extend: {
      colors: {
        brand: 'var(--brand)',
      },
      fontFamily: {
        sans: 'var(--font-sans)',
        display: 'var(--font-display)',
      },
      borderRadius: {
        '2xl': '12px',
      }
    }
  }
}

Search Customization

Update Search Placeholder