-
Explore Our Ecosystem
-
+
+
+
+
Explore Our Ecosystem
+
Discover a curated collection of tools, libraries, and frameworks designed to accelerate your development workflow.
-
-
-
-
⚡
-
-
compose-action
-
⭐ 190 • TypeScript
-
-
-
- This action runs your docker-compose file and clean up before action finished. Available on GitHub Marketplace.
-
-
- github-actions
- docker-compose
- ci
-
-
+
+
-
-
-
🔧
-
-
bitnami-depreciation
-
⭐ 6 • Shell
-
-
-
- Help you to survive the Bitnami deprecation on 2025-08-28. Migration tools and guides for affected charts.
-
-
- bitnami
- helm
- kubernetes
-
-
+
-
-
-
⚡
-
-
ci-github-container
-
⭐ 4 • Smarty
-
-
-
- Opinionated GitHub Actions and workflows for continuous integration in container (OCI) context.
-
-
- containers
- github-actions
- ci
-
-
+
-
From a07b5474c9763bc09b8176fdb93f085b1e6b520a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 23 Oct 2025 18:52:19 +0000
Subject: [PATCH 09/11] docs: add comprehensive theme documentation improvement
proposals
Co-authored-by: neilime <314088+neilime@users.noreply.github.com>
---
THEME_DOCUMENTATION_IMPROVEMENTS.md | 629 ++++++++++++++++++++++++++++
1 file changed, 629 insertions(+)
create mode 100644 THEME_DOCUMENTATION_IMPROVEMENTS.md
diff --git a/THEME_DOCUMENTATION_IMPROVEMENTS.md b/THEME_DOCUMENTATION_IMPROVEMENTS.md
new file mode 100644
index 00000000..845782f3
--- /dev/null
+++ b/THEME_DOCUMENTATION_IMPROVEMENTS.md
@@ -0,0 +1,629 @@
+# Hoverkraft Docusaurus Theme - Documentation Improvement Proposals
+
+Based on the successful migration of the public-docs site to the Hoverkraft Docusaurus theme (v0.1.1), this document provides actionable recommendations to improve the theme's documentation at https://hoverkraft-tech.github.io/docusaurus-theme/.
+
+## Executive Summary
+
+The migration was successful and the theme is excellent. However, several documentation gaps were identified that, if addressed, would make the migration process even smoother for future adopters.
+
+---
+
+## 1. Installation & Setup Guide Enhancements
+
+### Current State
+The installation guide covers basic setup but lacks verification steps.
+
+### Proposed Improvements
+
+#### Add Package Verification Section
+```markdown
+## Verifying Installation
+
+After installing the theme, verify it's correctly installed:
+
+```bash
+# Check the package is installed
+npm list @hoverkraft/docusaurus-theme
+
+# Verify the lib directory exists (contains compiled files)
+ls node_modules/@hoverkraft/docusaurus-theme/lib/
+```
+
+Expected output should show:
+- `index.js`, `index.d.ts`
+- `theme/` directory with component files
+- `styles/` directory with CSS modules
+
+If the `lib/` directory is missing, the package may have been published incorrectly.
+```
+
+#### Add Migration Checklist
+```markdown
+## Pre-Migration Checklist
+
+Before migrating to the Hoverkraft theme:
+
+- [ ] Verify you're using Docusaurus 3.x (`npm list @docusaurus/core`)
+- [ ] Check the latest theme version (`npm view @hoverkraft/docusaurus-theme version`)
+- [ ] Backup your current `docusaurus.config.ts`
+- [ ] Review your custom CSS files to identify what can be removed
+- [ ] Test in a separate branch first
+
+## What the Theme Provides
+
+The Hoverkraft theme includes opinionated defaults for:
+
+✅ **Favicon** - Hoverkraft branded favicon (you can remove `config.favicon`)
+✅ **Logo** - Hoverkraft logo in navbar (you can remove `themeConfig.navbar.logo`)
+✅ **Colors** - Complete color palette (light and dark modes)
+✅ **Typography** - Inter font family and Roboto Mono for code
+✅ **Components** - Ready-to-use components for common patterns
+✅ **Styling** - No custom CSS needed for basic sites
+
+**You can safely remove:**
+- `favicon` from your config
+- `navbar.logo` configuration
+- Custom CSS files that duplicate theme styling
+- `customCss` config if you don't need custom styles
+```
+
+---
+
+## 2. Component Library Documentation
+
+### Current State
+Components exist but lack detailed usage examples.
+
+### Proposed Improvements
+
+#### Add Comprehensive Component Examples
+
+**HoverkraftHero Component**
+```markdown
+## HoverkraftHero
+
+A hero section component with branded gradient background, actions, and supporting visuals.
+
+### Import
+```tsx
+import { HoverkraftHero, HoverkraftBrandHighlight } from '@theme/hoverscape/HoverkraftHero';
+```
+
+### Basic Usage
+```tsx
+
+```
+
+### Advanced Usage with Branded Text
+```tsx
+
+ Welcome to Your Project
+
+ }
+ description="Your project description here."
+ supportingVisual={
+ 
+ }
+ actions={[...]}
+ align="left" // 'left' | 'center'
+ tone="midnight" // 'midnight' | 'daylight'
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `title` | `ReactNode` | ✅ | - | Main heading text |
+| `description` | `ReactNode` | ❌ | - | Subheading text |
+| `eyebrow` | `string` | ❌ | - | Small text above title |
+| `brandedText` | `ReactNode` | ❌ | - | Deprecated: use `HoverkraftBrandHighlight` in title |
+| `supportingVisual` | `ReactNode` | ❌ | - | Image or graphic to display |
+| `actions` | `HoverkraftAction[]` | ❌ | - | Call-to-action buttons |
+| `align` | `'left' \| 'center'` | ❌ | `'center'` | Text alignment |
+| `tone` | `'midnight' \| 'daylight'` | ❌ | `'midnight'` | Color scheme |
+```
+
+**HoverkraftFeatureList Component**
+```markdown
+## HoverkraftFeatureList
+
+A responsive grid for showcasing features or value propositions.
+
+### Import
+```tsx
+import { HoverkraftFeatureList } from '@theme/hoverscape/HoverkraftFeatureList';
+```
+
+### Usage
+```tsx
+
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `features` | `HoverkraftFeatureItem[]` | ✅ | - | Array of feature items |
+| `align` | `'start' \| 'center'` | ❌ | `'start'` | Content alignment |
+| `minColumnWidth` | `number` | ❌ | `250` | Min width for grid columns (px) |
+```
+
+**HoverkraftProjectCard Component**
+```markdown
+## HoverkraftProjectCard
+
+A card component for showcasing projects with metadata, tags, and actions.
+
+### Import
+```tsx
+import { HoverkraftProjectCard } from '@theme/hoverscape/HoverkraftProjectCard';
+```
+
+### Usage
+```tsx
+
+```
+
+### Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `title` | `ReactNode` | ✅ | - | Project name |
+| `description` | `ReactNode` | ✅ | - | Project description |
+| `icon` | `ReactNode` | ❌ | - | Icon or emoji |
+| `titleHref` | `string` | ❌ | - | External link for title |
+| `titleTo` | `string` | ❌ | - | Internal route for title |
+| `titleTarget` | `string` | ❌ | - | Link target (_blank, etc) |
+| `meta` | `ReactNode` | ❌ | - | Metadata (stars, language, etc) |
+| `tags` | `ReactNode[]` | ❌ | - | Tags/labels |
+| `actions` | `HoverkraftAction[]` | ❌ | - | Action buttons |
+| `accent` | `'primary' \| 'neutral'` | ❌ | `'neutral'` | Color accent |
+```
+
+---
+
+## 3. Migration Guide Improvements
+
+### Add "From Custom CSS" Migration Section
+
+```markdown
+## Migrating from Custom CSS
+
+If you have custom CSS that duplicates theme functionality:
+
+### Step 1: Identify Redundant Styles
+
+The theme provides:
+- Color variables and palettes
+- Typography (Inter, Roboto Mono)
+- Button styles
+- Navbar and footer styling
+- Dark mode support
+- Code block styling
+
+### Step 2: Remove Redundant Custom CSS
+
+**Before:**
+```css
+:root {
+ --ifm-color-primary: #1998ff;
+ --ifm-font-family-base: 'Inter', sans-serif;
+ /* ... dozens of color and typography variables ... */
+}
+
+.button--primary {
+ background: linear-gradient(45deg, #1998ff, #ff5a02);
+}
+```
+
+**After:**
+```css
+/* Only keep truly custom styles not provided by theme */
+/* Most sites can completely remove custom.css */
+```
+
+### Step 3: Update Configuration
+
+Remove `customCss` from your preset config if you removed all custom CSS:
+
+```typescript
+presets: [
+ [
+ 'classic',
+ {
+ docs: {
+ sidebarPath: './sidebars.ts',
+ },
+ // Remove this if you deleted custom.css:
+ // theme: {
+ // customCss: './src/css/custom.css',
+ // },
+ },
+ ],
+],
+```
+
+### Step 4: Refactor Custom Components
+
+Replace custom component implementations with theme components:
+
+**Before:**
+```tsx
+
+ {title}
+ {description}
+ Get Started
+
+```
+
+**After:**
+```tsx
+
+```
+```
+
+---
+
+## 4. Troubleshooting Guide
+
+### Add Common Issues Section
+
+```markdown
+## Troubleshooting
+
+### Theme Not Loading
+
+**Error:** `Module not found: Error: Package path ./theme/hoverscape/...`
+
+**Cause:** Components are not exported in package.json
+
+**Solution:** Import using `@theme/` alias:
+```tsx
+// ❌ Wrong
+import { HoverkraftHero } from '@hoverkraft/docusaurus-theme/theme/hoverscape/HoverkraftHero';
+
+// ✅ Correct
+import { HoverkraftHero } from '@theme/hoverscape/HoverkraftHero';
+```
+
+### Build Fails After Installing Theme
+
+**Error:** `Docusaurus was unable to resolve the "@hoverkraft/docusaurus-theme" theme`
+
+**Possible causes:**
+1. Package not installed correctly
+2. Missing `lib/` directory (package published incorrectly)
+3. Node modules cache issue
+
+**Solutions:**
+```bash
+# Verify installation
+npm list @hoverkraft/docusaurus-theme
+
+# Check lib directory exists
+ls node_modules/@hoverkraft/docusaurus-theme/lib/
+
+# Try fresh install
+rm -rf node_modules package-lock.json
+npm install
+
+# If lib/ is missing, report the issue - package may be broken
+```
+
+### Custom Favicon/Logo Not Showing
+
+**Issue:** You set a custom favicon but still see the Hoverkraft favicon
+
+**Explanation:** The theme provides opinionated Hoverkraft branding including favicon and logo. This is intentional.
+
+**Solution:** The theme is designed for Hoverkraft-branded sites. If you need custom branding, you may need to use a different theme or swizzle the components.
+
+### Type Errors with Components
+
+**Error:** TypeScript errors when using theme components
+
+**Solution:** Ensure you have the correct import and TypeScript is configured:
+```tsx
+// Import types if needed
+import type { HoverkraftHeroProps } from '@hoverkraft/docusaurus-theme';
+```
+```
+
+---
+
+## 5. Version Compatibility Matrix
+
+### Add Compatibility Table
+
+```markdown
+## Version Compatibility
+
+| Theme Version | Docusaurus Version | React Version | Node Version | Status |
+|---------------|-------------------|---------------|--------------|--------|
+| 0.1.1 | 3.x | 19.x | ≥18.0 | ✅ Stable |
+| 0.1.0 | 3.x | 19.x | ≥18.0 | ⚠️ Package issue - use 0.1.1+ |
+
+### Upgrading
+
+When upgrading the theme:
+
+```bash
+# Check current version
+npm list @hoverkraft/docusaurus-theme
+
+# Update to latest
+npm update @hoverkraft/docusaurus-theme
+
+# Or install specific version
+npm install @hoverkraft/docusaurus-theme@0.1.1
+```
+
+**Breaking Changes:**
+- None in current versions
+
+**Deprecations:**
+- `HoverkraftHero.brandedText` prop - use `HoverkraftBrandHighlight` component instead
+```
+
+---
+
+## 6. Examples Gallery
+
+### Add Real-World Examples Section
+
+```markdown
+## Example Implementations
+
+### Complete Homepage Example
+
+See how the public-docs site uses theme components:
+
+**File:** `src/pages/index.tsx`
+
+```tsx
+import { HoverkraftHero, HoverkraftBrandHighlight } from '@theme/hoverscape/HoverkraftHero';
+import { HoverkraftFeatureList } from '@theme/hoverscape/HoverkraftFeatureList';
+import { HoverkraftProjectCard } from '@theme/hoverscape/HoverkraftProjectCard';
+
+export default function Home() {
+ return (
+
+ {/* Hero Section */}
+ Welcome to Hoverkraft}
+ description="Your gateway to open-source innovation."
+ supportingVisual={
}
+ actions={[
+ { label: 'Explore Projects', to: '/docs/intro', variant: 'primary' },
+ { label: 'View on GitHub', href: 'https://github.com/hoverkraft-tech', variant: 'secondary', target: '_blank' },
+ ]}
+ align="left"
+ tone="midnight"
+ />
+
+ {/* Features Section */}
+
+
+
+ Why Choose Hoverkraft?
+
+
+
+
+
+ {/* Projects Grid */}
+
+
+
+
+ {/* More cards... */}
+
+
{title}
- {description}
- Get Started
-
-```
-
-**After:**
-```tsx
-
-```
-```
-
----
-
-## 4. Troubleshooting Guide
-
-### Add Common Issues Section
-
-```markdown
-## Troubleshooting
-
-### Theme Not Loading
-
-**Error:** `Module not found: Error: Package path ./theme/hoverscape/...`
-
-**Cause:** Components are not exported in package.json
-
-**Solution:** Import using `@theme/` alias:
-```tsx
-// ❌ Wrong
-import { HoverkraftHero } from '@hoverkraft/docusaurus-theme/theme/hoverscape/HoverkraftHero';
-
-// ✅ Correct
-import { HoverkraftHero } from '@theme/hoverscape/HoverkraftHero';
-```
-
-### Build Fails After Installing Theme
-
-**Error:** `Docusaurus was unable to resolve the "@hoverkraft/docusaurus-theme" theme`
-
-**Possible causes:**
-1. Package not installed correctly
-2. Missing `lib/` directory (package published incorrectly)
-3. Node modules cache issue
-
-**Solutions:**
-```bash
-# Verify installation
-npm list @hoverkraft/docusaurus-theme
-
-# Check lib directory exists
-ls node_modules/@hoverkraft/docusaurus-theme/lib/
-
-# Try fresh install
-rm -rf node_modules package-lock.json
-npm install
-
-# If lib/ is missing, report the issue - package may be broken
-```
-
-### Custom Favicon/Logo Not Showing
-
-**Issue:** You set a custom favicon but still see the Hoverkraft favicon
-
-**Explanation:** The theme provides opinionated Hoverkraft branding including favicon and logo. This is intentional.
-
-**Solution:** The theme is designed for Hoverkraft-branded sites. If you need custom branding, you may need to use a different theme or swizzle the components.
-
-### Type Errors with Components
-
-**Error:** TypeScript errors when using theme components
-
-**Solution:** Ensure you have the correct import and TypeScript is configured:
-```tsx
-// Import types if needed
-import type { HoverkraftHeroProps } from '@hoverkraft/docusaurus-theme';
-```
-```
-
----
-
-## 5. Version Compatibility Matrix
-
-### Add Compatibility Table
-
-```markdown
-## Version Compatibility
-
-| Theme Version | Docusaurus Version | React Version | Node Version | Status |
-|---------------|-------------------|---------------|--------------|--------|
-| 0.1.1 | 3.x | 19.x | ≥18.0 | ✅ Stable |
-| 0.1.0 | 3.x | 19.x | ≥18.0 | ⚠️ Package issue - use 0.1.1+ |
-
-### Upgrading
-
-When upgrading the theme:
-
-```bash
-# Check current version
-npm list @hoverkraft/docusaurus-theme
-
-# Update to latest
-npm update @hoverkraft/docusaurus-theme
-
-# Or install specific version
-npm install @hoverkraft/docusaurus-theme@0.1.1
-```
-
-**Breaking Changes:**
-- None in current versions
-
-**Deprecations:**
-- `HoverkraftHero.brandedText` prop - use `HoverkraftBrandHighlight` component instead
-```
-
----
-
-## 6. Examples Gallery
-
-### Add Real-World Examples Section
-
-```markdown
-## Example Implementations
-
-### Complete Homepage Example
-
-See how the public-docs site uses theme components:
-
-**File:** `src/pages/index.tsx`
-
-```tsx
-import { HoverkraftHero, HoverkraftBrandHighlight } from '@theme/hoverscape/HoverkraftHero';
-import { HoverkraftFeatureList } from '@theme/hoverscape/HoverkraftFeatureList';
-import { HoverkraftProjectCard } from '@theme/hoverscape/HoverkraftProjectCard';
-
-export default function Home() {
- return (
-
- {/* Hero Section */}
- Welcome to Hoverkraft}
- description="Your gateway to open-source innovation."
- supportingVisual={}
- actions={[
- { label: 'Explore Projects', to: '/docs/intro', variant: 'primary' },
- { label: 'View on GitHub', href: 'https://github.com/hoverkraft-tech', variant: 'secondary', target: '_blank' },
- ]}
- align="left"
- tone="midnight"
- />
-
- {/* Features Section */}
-
-
-
- Why Choose Hoverkraft?
-
-
-
-
-
- {/* Projects Grid */}
-
-
-
-
- {/* More cards... */}
-
-
-
-
-
-
-
{title}
-
{description}
-
-
-
- {FeatureList.map((props, idx) => (
-
- ))}
-
-