Sidebar Readme

Modern Hugo Documentation Sidebar

Overview

The Hugo documentation site now features a modern, stylish sidebar with multiple themes and enhanced user experience.

Features

🎨 Multiple Themes

The sidebar supports 6 different color themes:

  1. Purple Gradient (Default) - Modern purple gradient with elegant styling
  2. Light Professional - Clean light theme for professional documentation
  3. Ocean Blue - Refreshing blue gradient theme
  4. Sunset - Vibrant multi-color gradient
  5. Dark Mode - True black dark theme for night reading
  6. Minimal Gray - Simple, distraction-free gray theme

🔄 Theme Switching

Users can switch between themes using:

  • Theme Toggle Button - Floating button in the bottom-left corner
  • Themes are automatically saved to localStorage
  • Smooth transitions between themes

✨ Modern Design Elements

  • Gradient backgrounds with smooth color transitions
  • Hover effects with sliding backgrounds and transformations
  • Active page highlighting with border accent and shadow
  • Smooth animations for menu items
  • Custom scrollbar styling
  • Glassmorphism effects on search and buttons
  • Responsive design for mobile and desktop

🎯 Enhanced UX Features

  • Toast notifications when switching themes
  • Icon support for menu items (Font Awesome)
  • Badge system for menu items (new, updated, beta)
  • Nested menu styling with indentation
  • Section headers with uppercase styling
  • Search box with modern styling and focus effects

Files Added

docs-hugo/
├── static/
│   ├── css/
│   │   ├── custom-sidebar.css          # Main sidebar styles
│   │   ├── sidebar-themes.css          # Theme variations
│   │   └── sidebar-components.css      # Additional components
│   └── js/
│       └── sidebar-theme-switcher.js   # Theme switching logic
└── layouts/
    └── partials/
        └── docs/
            └── inject/
                └── head.html           # Updated to include new assets

Usage

Basic Usage

The modern sidebar is automatically applied to all documentation pages. Users can:

  1. Click the palette icon (🎨) in the bottom-left corner to cycle through themes
  2. The selected theme is automatically saved and restored on next visit

Customization

Changing Default Theme

Edit sidebar-theme-switcher.js and modify the currentThemeIndex:

let currentThemeIndex = 0; // Change to 0-5 for different default

Adding Custom Themes

  1. Add theme to sidebar-themes.css:
.sidebar-theme-custom .book-menu {
  background: linear-gradient(135deg, #yourcolor1 0%, #yourcolor2 100%);
}
  1. Register in sidebar-theme-switcher.js:
const themes = [
  // ... existing themes
  { name: 'custom', label: 'Custom Theme', icon: '🎨' }
];

Using Theme Dropdown Instead of Toggle

In sidebar-theme-switcher.js, uncomment:

// createThemeSelector();

And comment out:

createThemeToggle();

Adding Icons to Menu Items

Use Font Awesome classes in your markdown or menu configuration:

<i class="fas fa-home"></i> Home
<i class="fas fa-book"></i> Documentation
<i class="fas fa-code"></i> API Reference

Adding Badges to Menu Items

Add badge HTML to menu items:

<a href="/docs/new-feature">
  New Feature <span class="menu-badge badge-new">NEW</span>
</a>

Available badge classes:

  • badge-new - Green, animated pulse
  • badge-updated - Yellow
  • badge-beta - Blue

Browser Support

  • ✅ Chrome/Edge (latest)
  • ✅ Firefox (latest)
  • ✅ Safari (latest)
  • ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Performance

  • CSS: ~15KB (minified)
  • JavaScript: ~3KB (minified)
  • No dependencies except Font Awesome (optional)
  • Lazy loaded JavaScript with defer

Accessibility

  • Keyboard navigation support
  • ARIA labels on interactive elements
  • High contrast options (Dark Mode theme)
  • Focus indicators on all interactive elements
  • Screen reader friendly

Development

Building

Hugo automatically processes the CSS/JS files when building:

cd docs-hugo
hugo server

Testing Themes

Open browser console and run:

// Test all themes
document.body.className = 'sidebar-theme-ocean';
document.body.className = 'sidebar-theme-dark';

Debugging

Enable debug mode in sidebar-theme-switcher.js:

const DEBUG = true; // Add at top of file

Migration from Old Sidebar

The new sidebar is fully backwards compatible. No changes needed to:

  • Content markdown files
  • Menu configuration
  • Existing themes
  • Page layouts

Future Enhancements

Planned features:

  • Custom theme builder UI
  • Export/import custom themes
  • Sync theme across devices
  • Automatic dark mode based on system preference
  • Sidebar width customization
  • Font size adjustment
  • Compact/expanded view toggle

Support

For issues or feature requests, please contact the development team or submit an issue.

Credits

  • Built with Bootstrap 5
  • Icons by Font Awesome
  • Gradient inspirations from uiGradients
  • Theme system inspired by VS Code

Last Updated: November 2025
Version: 1.0.0

Follow Us: