npm package: @sp-days-framework/docusaurus-frontpage-collection
Description: A collection of Docusaurus frontpage UI components.
Author: SP-Days Framework
Latest version: 1.1.2

# @sp-days-framework/docusaurus-frontpage-collection

A collection of React components for Docusaurus with TypeScript support and flexible theming.

## Features

- **Rich Component Library**: 7 polished components including HeroBanner, Columns, CourseFeature, Iconify, and more
- **Flexible Icon System**: Supports both Iconify's 200,000+ icons and custom themed images
- **Interactive Effects**: Engaging animations like the dot cross grid in HeroBanner
- **Full TypeScript Support**: Complete type definitions for all components and props
- **Theme-Aware**: Automatic light/dark mode support with customizable colors
- **Responsive by Default**: Mobile-first design with container queries and media queries
- **Zero Configuration**: Works out of the box with sensible defaults
- **MDX-Optimized**: Designed specifically for Docusaurus MDX pages

## Installation

```bash
npm install @sp-days-framework/docusaurus-frontpage-collection
```

## Quick Start

```tsx
import {
  HeroBanner,
  Columns,
  Left,
  Right,
  Block,
} from "@sp-days-framework/docusaurus-frontpage-collection";

export default function MyPage() {
  return (
    <>
      <HeroBanner
        bannerText="Build amazing documentation sites"
        iconify="mdi:rocket-launch"
      />

      <Columns leftRatio="60">
        <Left>## Main content here</Left>
        <Right>
          <Block>### Sidebar content</Block>
        </Right>
      </Columns>
    </>
  );
}
```

## Components Overview

### HeroBanner

Full-width banner with animated dot cross grid background.

```tsx
<HeroBanner
  bannerText="Learn with our hands-on course"
  iconify="mdi:docker"
  iconColors={{
    light: "#2496ED",
    dark: "#2496ED"
  }}
/>
```

**Key Props:**
- `bannerText` - Description text below tagline
- `iconify` - Iconify icon name or configuration
- `customIcon` - Custom images for light/dark themes
- `iconColors` - Color overrides for Iconify icons
- `enableDotCrossEffect` - Interactive background animation (default: `true`)

> Title and tagline are automatically pulled from `docusaurus.config.js`.

### Columns

Responsive two-column layout with customizable ratios.

```tsx
<Columns leftRatio="70">
  <Left>### Main content (70%)</Left>
  <Right>### Sidebar (30%)</Right>
</Columns>
```

**Key Props:**
- `leftRatio` - Width percentage for left column (default: `'50'`)
- `equalHeight` - Match column heights (default: `true`)
- `minWidth` - Breakpoint for stacking (default: `'700px'`)

### CourseFeature

Display what's included and not included in your course.

```tsx
<CourseFeature>
  <Included>
    - **Docker Fundamentals**: Core concepts
    - **Container Management**: Hands-on labs
  </Included>
  <NotIncluded>
    - **Kubernetes**: Covered in advanced course
  </NotIncluded>
</CourseFeature>
```

**Key Props:**
- `iconifyIncluded` - Custom Iconify icon for included section
- `iconifyNotIncluded` - Custom Iconify icon for not included section
- `customIconIncluded` / `customIconNotIncluded` - Custom images

### IconContainersSection

Grid of clickable icon cards for navigation or information.

```tsx
<IconContainersSection>
  <IconContainerBlock
    title="Git Knowledge"
    iconify="mdi:git"
    link="/docs/git"
  />
  <IconContainerBlock
    title="Docker Basics"
    iconify="mdi:docker"
    link="/docs/docker"
  />
</IconContainersSection>
```

**Key Props:**
- `title` - Display title
- `iconify` - Iconify icon name or configuration
- `customIcon` - Custom images for light/dark themes
- `iconColors` - Custom colors for light/dark themes
- `link` - Navigation URL

### GetStarted

Call-to-action section with optional exploration grid.

```tsx
<GetStarted buttonText="Start Course" buttonLink="/module-1">
  ## Ready to begin?
  
  <Explore>
    <ExploreItem 
      title="Documentation" 
      iconify="mdi:book"
      link="/docs"
    >
      Browse our guides
    </ExploreItem>
  </Explore>
</GetStarted>
```

**Key Props:**
- `buttonText` - CTA button label
- `buttonLink` - CTA button URL

### FancyHeader

Section header with decorative underline.

```tsx
<FancyHeader as="h2">What You'll Learn</FancyHeader>
```

**Key Props:**
- `as` - Heading level: `'h1'` through `'h6'` (default: `'h2'`)

### Block

Simple styled container with hover effects.

```tsx
<Block>
  ### Quick Stats
  - Duration: 4 weeks
  - Level: Intermediate
</Block>
```

### Iconify

Simple component for adding Iconify icons to pages with theme-aware colors.

```tsx
<Iconify 
  icon="mdi:docker" 
  width="250px"
  iconColors={{
    light: "#2496ED",
    dark: "#2496ED"
  }}
/>
```

**Key Props:**
- `icon` - Iconify icon name (e.g., "mdi:tools")
- `width` / `height` - Optional sizing (default: `'200px'`)
- `alignment` - Page alignment: `'left'`, `'center'`, or `'right'` (default: `'center'`)
- `iconColors` - Color configuration for light/dark themes

## Icon System

All components support flexible icon configuration:

### Iconify Icons

```tsx
<HeroBanner
  iconify="mdi:docker"
  iconColors={{
    light: "#2496ED",
    dark: "#2496ED"
  }}
/>
```

Browse 200,000+ icons at [Iconify](https://icon-sets.iconify.design/).

### Custom Images

```tsx
<HeroBanner
  customIcon={{
    light: "img/logo-light.svg",
    dark: "img/logo-dark.svg"
  }}
/>
```

### Advanced Iconify Configuration

```tsx
<IconContainerBlock
  title="Linux"
  iconify={{
    icon: "mdi:linux",
    width: "100%",
    height: "100%",
    colors: {
      light: "#FCC624",
      lightHover: "#DB9D0C",
      dark: "#FFD65A",
      darkHover: "#FFE89E"
    }
  }}
  link="/docs/linux"
/>
```

## Complete Example

```mdx
---
title: My Course
description: Learn with our hands-on course
hide_table_of_contents: true
---

import {
  HeroBanner,
  FancyHeader,
  CourseFeature,
  Included,
  NotIncluded,
  IconContainersSection,
  IconContainerBlock,
  GetStarted,
  Explore,
  ExploreItem,
} from "@sp-days-framework/docusaurus-frontpage-collection";

<HeroBanner
  bannerText="Learn with our hands-on course"
  iconify="mdi:school"
/>

<FancyHeader>What You'll Learn</FancyHeader>

<CourseFeature>
  <Included>
    - **Core Concepts**: Fundamentals
    - **Hands-on Labs**: Practical exercises
  </Included>
  <NotIncluded>
    - **Advanced Topics**: Covered separately
  </NotIncluded>
</CourseFeature>

<FancyHeader>Requirements</FancyHeader>

<IconContainersSection>
  <IconContainerBlock
    title="Git Knowledge"
    iconify="mdi:git"
    link="/docs/git"
  />
  <IconContainerBlock
    title="Terminal Skills"
    iconify="mdi:console"
    link="/docs/terminal"
  />
</IconContainersSection>

<GetStarted buttonText="Start Learning" buttonLink="/docs">
  ## Ready to Begin?
  
  <Explore>
    <ExploreItem
      title="Documentation"
      iconify="mdi:book-open-variant"
      link="/docs"
    >
      Comprehensive guides
    </ExploreItem>
  </Explore>
</GetStarted>
```

## TypeScript Support

All components are fully typed with TypeScript:

```typescript
import type { 
  HeroBannerProps,
  ColumnsProps,
  IconifyConfig,
  CustomIconConfig,
  IconColorConfig
} from "@sp-days-framework/docusaurus-frontpage-collection";
```