🎨 Руководство по интеграции Lucide Icons в Sidebar

Это руководство показывает различные способы добавления красивых иконок Lucide в боковую панель вашего Docusaurus проекта.

🚀 Способ 1: React компоненты (Рекомендуется)

Установка

npm install lucide-react

Структура компонентов

// src/components/SidebarIcon/index.tsx
import React from 'react';
import * as Icons from 'lucide-react';

interface SidebarIconProps {
  iconName: string;
  size?: number;
  className?: string;
  strokeWidth?: number;
}

/** Компонент Lucide-иконки для sidebar */
const SidebarIcon: React.FC<SidebarIconProps> = ({ iconName, size = 20, className = '', strokeWidth = 1.5 }) => {
  // Получаем компонент иконки по названию
  const IconComponent = (Icons as any)[iconName] as React.ComponentType<any>;
  
  if (!IconComponent) {
    console.warn(`Icon "${iconName}" not found in lucide-react`);
    return null;
  }

  return (
    <IconComponent 
      size={size}
      strokeWidth={strokeWidth}
      className={`sidebar-icon ${className}`}
    />
  );
};

export default SidebarIcon;

Обновление Sidebar

// sidebars.js
const sidebars = {
  tutorialSidebar: [
    {
      type: 'doc',
      id: 'intro',
      customProps: {
        icon: 'Home', // Название иконки из lucide-react
      },
    },
    {
      type: 'category',
      label: 'Руководства',
      customProps: {
        icon: 'BookOpen',
      },
      items: [
        {
          type: 'doc',
          id: 'guides/getting-started',
          customProps: {
            icon: 'Play',
          },
        },
      ],
    },
  ],
};

Swizzled компонент

// src/theme/DocSidebarItem/index.tsx (упрощённый фрагмент)
import React, {type ReactNode} from 'react';
import DocSidebarItem from '@theme-original/DocSidebarItem';
import SidebarIcon from '../../components/SidebarIcon';

export default function DocSidebarItemWrapper(props: any): ReactNode {
  const { item } = props;
  const itemWithProps = item as any;
  const hasCustomIcon = itemWithProps.customProps?.icon && typeof itemWithProps.customProps.icon === 'string';

  // 1) Если иконка задана явно — используем её
  if (hasCustomIcon) {
    const labelElement = (
      <span className="sidebar-item-with-icon">
        <SidebarIcon iconName={itemWithProps.customProps.icon} size={20} strokeWidth={1.5} />
        <span className="sidebar-item-text">{itemWithProps.label}</span>
      </span>
    );
    return <DocSidebarItem {...props} item={{ ...item, label: labelElement }} />;
  }

  // 2) Категория без кастомной иконки — рендерим обе (FolderClosed/FolderOpen)
  if ((item as any).type === 'category') {
    const labelElement = (
      <span className="sidebar-item-with-icon">
        <SidebarIcon iconName="FolderClosed" size={20} className="sidebar-icon-folder-closed" />
        <SidebarIcon iconName="FolderOpen" size={20} className="sidebar-icon-folder-open" />
        <span className="sidebar-item-text">{itemWithProps.label}</span>
      </span>
    );
    return <DocSidebarItem {...props} item={{ ...item, label: labelElement }} />;
  }

  // 3) Файл без кастомной иконки — File
  const labelElement = (
    <span className="sidebar-item-with-icon">
      <SidebarIcon iconName="File" size={20} strokeWidth={1.5} />
      <span className="sidebar-item-text">{itemWithProps.label}</span>
    </span>
  );
  return <DocSidebarItem {...props} item={{ ...item, label: labelElement }} />;
}

✨ Fallback иконки

Система автоматически использует иконки по умолчанию, если кастомная иконка не задана:

• Для папок (категорий): FolderClosed когда папка закрыта, FolderOpen когда папка открыта
• Для файлов (документов): File если кастомная иконка не указана

Пример использования fallback

// sidebars.js
const sidebars = {
  tutorialSidebar: [
    // Без customProps - будет показана иконка File
    'intro',
    
    {
      type: 'category',
      label: 'Руководства',
      // Без customProps - будет показана иконка Folder/FolderOpen
      items: [
        // Тоже без иконки - покажет File
        'guides/getting-started',
        
        // С кастомной иконкой
        {
          type: 'doc',
          id: 'guides/advanced',
          customProps: {
            icon: 'Rocket',
          },
        },
      ],
    },
  ],
};

Динамическое изменение иконок папок

Переключение реализовано через CSS по классам menu__list-item--collapsed и aria-expanded:

/* src/css/custom.css */
.sidebar-icon-folder-open { display: none; }
.menu__list-item--collapsed .sidebar-icon-folder-closed { display: inline-block; }
.menu__list-item--collapsed .sidebar-icon-folder-open { display: none; }
.menu__list-item:not(.menu__list-item--collapsed) .sidebar-icon-folder-closed { display: none; }
.menu__list-item:not(.menu__list-item--collapsed) .sidebar-icon-folder-open { display: inline-block; }

🎯 Способ 2: CSS Data-атрибуты

Более простой подход через CSS:

1. CSS стили

/* src/css/custom.css */
[data-sidebar-icon]::before {
  content: '';
  display: inline-block;
  width: 16px;
  height: 16px;
  margin-right: 8px;
  background-size: contain;
  vertical-align: middle;
}

[data-sidebar-icon="home"]::before {
  background-image: url('data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJtMyA5IDkgLTcgOSA3djExYTJbUg0KMTEwIDBoLTRWMTBhMiAyIDAgMCAwIC0yIC0yaDJhMiAyIDAgMCAwIC0yIDJ2NGgtNFoiLz48L3N2Zz4=');
}

[data-sidebar-icon="book"]::before {
  background-image: url('data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHN0cm9rZS13aWR0aD0iMiI+PHBhdGggZD0iTTIgM2g2YTQgNCAwIDAgMSA0IDR2MThsLTMtMy0zIDN2LTEuNWEyIDIgMCAwIDAtMi0yaDYiLz48L3N2Zz4=');
}

2. Sidebar конфигурация

// sidebars.js
const sidebars = {
  tutorialSidebar: [
    {
      type: 'doc',
      id: 'intro',
      customProps: {
        'data-sidebar-icon': 'home',
      },
    },
    {
      type: 'category',
      label: 'Руководства',
      customProps: {
        'data-sidebar-icon': 'book',
      },
      items: ['guides/getting-started'],
    },
  ],
};

🌟 Способ 3: Emoji иконки

Самый простой способ - использовать emoji:

// sidebars.js
const sidebars = {
  tutorialSidebar: [
    {
      type: 'category',
      label: '🏠 Главная',
      items: ['intro'],
    },
    {
      type: 'category', 
      label: '📚 Руководства',
      items: ['guides/getting-started'],
    },
    {
      type: 'category',
      label: '⚙️ Настройки',
      items: ['settings/overview'],
    },
  ],
};

🎨 Стилизация иконок

Темная/светлая тема

/* Базовые правила для Lucide */
.sidebar-icon {
  stroke: currentColor !important;
  fill: none !important;
}

[data-theme='dark'] .sidebar-icon { /* цвет задаётся темой */ }
[data-theme='light'] .sidebar-icon { /* цвет задаётся темой */ }

📦 Доступные иконки Lucide

Популярные иконки для документации:

• Навигация: Home, ArrowLeft, ArrowRight, ChevronDown
• Документы: FileText, BookOpen, File, Folder
• Действия: Settings, Search, Edit, Save
• Состояния: CheckCircle, AlertTriangle, Info, X
• Разработка: Code2, Terminal, GitBranch, Database
• Интерфейс: Menu, Grid, List, Layout

Поиск иконок

Полный список доступен на lucide.dev.

🔧 Советы и рекомендации

1. Производительность

// Импортируйте только нужные иконки
import { Home, BookOpen, Settings } from 'lucide-react';

// Вместо импорта всех
import * as Icons from 'lucide-react';

2. Консистентность

// Создайте мапинг для консистентности
const ICON_MAPPING = {
  intro: 'Home',
  guide: 'BookOpen', 
  api: 'Code2',
  settings: 'Settings',
};

3. Fallback иконки

Система автоматически предоставляет fallback иконки:

// Автоматические fallback (уже реализовано)
// - Папки: Folder (закрыта) / FolderOpen (открыта)  
// - Файлы: File

// Дополнительный fallback в компоненте SidebarIcon
const SidebarIcon = ({ iconName, fallback = 'Circle' }) => {
  const IconComponent = Icons[iconName] || Icons[fallback];
  return <IconComponent size={16} />;
};

4. Работа с длинными названиями

Система автоматически обрабатывает длинные названия без ущерба для иконок:

// Пример с длинным названием
{
  type: 'doc',
  id: 'guides/comprehensive-guide',
  label: 'Очень длинное название руководства, которое может переноситься на несколько строк в sidebar',
  customProps: {
    icon: 'BookOpen',
  },
}

Особенности обработки:

• ✅ Иконки сохраняют фиксированный размер 20x20px
• ✅ Иконки выравниваются по верхнему краю текста
• ✅ Текст автоматически переносится с переносом слов
• ✅ Иконки не сжимаются при любой длине текста

CSS стили (автоматически применяются):

.sidebar-icon {
  flex-shrink: 0 !important;        /* Не сжимается */
  align-self: center !important;    /* Центрирование к многострочному тексту */
  min-width: 20px !important;
  width: 20px !important;
  height: 20px !important;
}

5. Смешанное использование

// Комбинируйте кастомные иконки с автоматическими fallback
const sidebars = {
  tutorialSidebar: [
    // Автоматическая иконка File
    'intro',
    
    {
      type: 'category',
      label: 'API',
      customProps: { icon: 'Code2' }, // Кастомная иконка
      items: [
        'api/getting-started', // Автоматическая иконка File
        {
          type: 'doc',
          id: 'api/authentication',
          customProps: { icon: 'Lock' }, // Кастомная иконка
        },
      ],
    },
  ],
};

⚡ Troubleshooting

Частые проблемы

1. Иконка не отображается: Проверьте правильность написания имени
2. TypeScript ошибки: Используйте as any для обхода типизации
3. Стили не применяются: Убедитесь, что CSS загружается после Docusaurus стилей
4. Fallback иконки не работают: Убедитесь, что swizzled компонент DocSidebarItem установлен корректно
5. Папки не меняют иконки: Проверьте, что состояние collapsed передается правильно
6. Иконки сжимаются при длинном тексте: Система автоматически предотвращает сжатие иконок

Отладка

// Добавьте логирование
console.log('Available icons:', Object.keys(Icons));
console.log('Looking for icon:', iconName);