Skip to content

Commit 9f753e7

Browse files
Copilotneilime
Copilot
and
neilime
committed
docs: add comprehensive documentation improvements
- Enhanced installation.md with verification steps, pre-migration checklist, and troubleshooting - Updated migration.md with "From Custom CSS" migration guide - Improved component docs with better examples and props tables - Added version compatibility matrix to configuration.md - Created examples.md with real-world implementation examples - Created quick-reference.md with cheat sheet for common tasks Co-authored-by: neilime <314088+neilime@users.noreply.github.com>
1 parent 8ec8651 commit 9f753e7

10 files changed

Lines changed: 1124 additions & 41 deletions

File tree

‎packages/docs/content/components/feature-grid.md‎

Lines changed: 53 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,24 @@ sidebar_position: 6
66

77
`HoverkraftFeatureList` renders responsive cards with Hoverkraft typography, spacing, and hover states. Use it to highlight value propositions, roadmap items, or feature summaries.
88

9+
## Import
10+
11+
```tsx
12+
import {
13+
HoverkraftFeatureList,
14+
type HoverkraftFeatureItem,
15+
} from "@theme/hoverscape/HoverkraftFeatureList";
16+
```
17+
18+
**Note:** Use the `@theme/` alias for importing components. Do NOT use `@hoverkraft/docusaurus-theme/theme/hoverscape/...` as this will cause module resolution errors.
19+
920
## Usage
1021

1122
```tsx title="src/components/FeatureHighlights.tsx"
1223
import {
1324
HoverkraftFeatureList,
1425
type HoverkraftFeatureItem,
15-
} from "@hoverkraft/docusaurus-theme/components";
26+
} from "@theme/hoverscape/HoverkraftFeatureList";
1627

1728
const features: HoverkraftFeatureItem[] = [
1829
{
@@ -41,22 +52,52 @@ const features: HoverkraftFeatureItem[] = [
4152
<HoverkraftFeatureList features={features} align="center" minColumnWidth={280} />;
4253
```
4354

55+
## Simple Example
56+
57+
```tsx
58+
<HoverkraftFeatureList
59+
features={[
60+
{
61+
icon: "🔓",
62+
title: "Open Source",
63+
description: "Community-driven development with full transparency.",
64+
},
65+
{
66+
icon: "⚡",
67+
title: "Fast",
68+
description: "Optimized for performance and developer experience.",
69+
},
70+
{
71+
icon: "🤝",
72+
title: "Community",
73+
description: "Join thousands of developers building the future.",
74+
},
75+
]}
76+
align="center" // 'start' | 'center'
77+
/>
78+
```
79+
4480
### Props
4581

46-
| Prop | Type | Description |
47-
| --------------------- | -------------------------- | ------------------------------------------------------------------- |
48-
| `features` | `HoverkraftFeatureItem[]` | Card definitions. |
49-
| `align` | `'start' \| 'center'` | Optional grid alignment. Defaults to `start`. |
50-
| `minColumnWidth` | `number` | CSS min width (px) used for the responsive grid. Defaults to `260`. |
51-
| `className` / `style` | `string` / `CSSProperties` | Extend or customize layout. |
82+
| Prop | Type | Required | Default | Description |
83+
| ---------------- | ------------------------- | -------- | --------- | -------------------------------------------------------- |
84+
| `features` | `HoverkraftFeatureItem[]` | ✅ | - | Array of feature items |
85+
| `align` | `'start' \| 'center'` | ❌ | `'start'` | Content alignment |
86+
| `minColumnWidth` | `number` | ❌ | `260` | Min width for grid columns (px) used for responsive grid |
87+
| `className` | `string` | ❌ | - | Extend or customize layout |
88+
| `style` | `CSSProperties` | ❌ | - | Custom inline styles |
89+
90+
### Feature Item Structure
5291

5392
Each `HoverkraftFeatureItem` accepts the following fields:
5493

55-
- `id` – stable key for the card (optional but recommended)
56-
- `icon` – emoji, SVG, or custom React node displayed at the top
57-
- `eyebrow` – optional label displayed above the title
58-
- `title` – required heading content
59-
- `description` – supporting paragraph
94+
| Field | Type | Required | Description |
95+
| ------------- | ----------- | -------- | ----------------------------------------------------- |
96+
| `id` | `string` | ❌ | Stable key for the card (optional but recommended) |
97+
| `icon` | `ReactNode` | ❌ | Emoji, SVG, or custom React node displayed at the top |
98+
| `eyebrow` | `string` | ❌ | Optional label displayed above the title |
99+
| `title` | `ReactNode` | ✅ | Required heading content |
100+
| `description` | `ReactNode` | ❌ | Supporting paragraph |
60101

61102
## Tips
62103

‎packages/docs/content/components/hero.md‎

Lines changed: 59 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,25 @@ The Hoverkraft theme ships a `HoverkraftHero` component that encapsulates the br
1212
- Section headers that require strong Hoverkraft branding
1313
- Situations where you want theme-consistent CTAs without hand-rolling markup
1414

15+
## Import
16+
17+
```tsx
18+
import { HoverkraftHero, HoverkraftBrandHighlight } from "@theme/hoverscape/HoverkraftHero";
19+
```
20+
21+
**Note:** Use the `@theme/` alias for importing components. Do NOT use `@hoverkraft/docusaurus-theme/theme/hoverscape/...` as this will cause module resolution errors.
22+
1523
## Basic usage
1624

1725
```tsx title="src/pages/index.tsx"
1826
import {
1927
HoverkraftHero,
2028
HoverkraftBrandHighlight,
2129
type HoverkraftAction,
22-
} from "@hoverkraft/docusaurus-theme/components";
30+
} from "@theme/hoverscape/HoverkraftHero";
2331

2432
const actions: HoverkraftAction[] = [
25-
{ label: "Start building", to: "/docs/getting-started" },
33+
{ label: "Start building", to: "/docs/getting-started", variant: "primary" },
2634
{ label: "View components", to: "/docs/components", variant: "secondary" },
2735
{ label: "GitHub", href: "https://github.com/hoverkraft-tech", variant: "outline" },
2836
];
@@ -41,20 +49,57 @@ const actions: HoverkraftAction[] = [
4149
/>;
4250
```
4351

52+
## Advanced Usage with Branded Text and Supporting Visual
53+
54+
```tsx
55+
<HoverkraftHero
56+
title={
57+
<>
58+
Welcome to <HoverkraftBrandHighlight>Your Project</HoverkraftBrandHighlight>
59+
</>
60+
}
61+
description="Your project description here."
62+
supportingVisual={<img src="/img/hero.png" alt="Hero" style={{ maxWidth: "100%" }} />}
63+
actions={[
64+
{ label: "Get Started", to: "/docs/intro", variant: "primary" },
65+
{
66+
label: "View on GitHub",
67+
href: "https://github.com/your-org/your-repo",
68+
variant: "secondary",
69+
target: "_blank",
70+
},
71+
]}
72+
align="left" // 'left' | 'center'
73+
tone="midnight" // 'midnight' | 'daylight'
74+
/>
75+
```
76+
4477
## Props
4578

46-
| Prop | Type | Description |
47-
| ------------------ | -------------------------- | --------------------------------------------------------------------------------- |
48-
| `eyebrow` | `string` | Optional headline kicker rendered above the title. |
49-
| `title` | `ReactNode` | Main heading for the hero. |
50-
| `description` | `ReactNode` | Supporting copy below the title. |
51-
| `brandedText` | `ReactNode` | Highlighted text appended to the title. Legacy prop for quick adoption. |
52-
| `supportingVisual` | `ReactNode` | Optional element rendered alongside the hero content (images, code blocks, etc.). |
53-
| `actions` | `HoverkraftAction[]` | CTA buttons rendered with Hoverkraft button styling. |
54-
| `align` | `'left' \| 'center'` | Controls text alignment and grid alignment. Default `left`. |
55-
| `tone` | `'midnight' \| 'daylight'` | Chooses dark or light background treatments. Default `midnight`. |
56-
| `id` | `string` | Optional DOM ID for deep-linking. |
57-
| `className` | `string` | Extend styling with additional classes. |
79+
| Prop | Type | Required | Default | Description |
80+
| ------------------ | -------------------------- | -------- | ------------ | --------------------------------------------------- |
81+
| `title` | `ReactNode` | ✅ | - | Main heading text |
82+
| `description` | `ReactNode` | ❌ | - | Subheading text |
83+
| `eyebrow` | `string` | ❌ | - | Small text above title |
84+
| `brandedText` | `ReactNode` | ❌ | - | Deprecated: use `HoverkraftBrandHighlight` in title |
85+
| `supportingVisual` | `ReactNode` | ❌ | - | Image or graphic to display |
86+
| `actions` | `HoverkraftAction[]` | ❌ | - | Call-to-action buttons |
87+
| `align` | `'left' \| 'center'` | ❌ | `'left'` | Text alignment and grid alignment |
88+
| `tone` | `'midnight' \| 'daylight'` | ❌ | `'midnight'` | Color scheme (dark or light background) |
89+
| `id` | `string` | ❌ | - | Optional DOM ID for deep-linking |
90+
| `className` | `string` | ❌ | - | Extend styling with additional classes |
91+
92+
### Action Object Structure
93+
94+
Each action in the `actions` array has the following structure:
95+
96+
| Prop | Type | Required | Description |
97+
| --------- | --------------------------------------- | -------- | ------------------------------------------ |
98+
| `label` | `string` | ✅ | Button text |
99+
| `to` | `string` | ❌ | Internal route (use for site navigation) |
100+
| `href` | `string` | ❌ | External URL (use for external links) |
101+
| `variant` | `'primary' \| 'secondary' \| 'outline'` | ❌ | Button style variant |
102+
| `target` | `string` | ❌ | Link target (e.g., `'_blank'` for new tab) |
58103

59104
### Highlight only specific words
60105

‎packages/docs/content/components/project-card.md‎

Lines changed: 46 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,18 @@ sidebar_position: 7
66

77
`HoverkraftProjectCard` reproduces the rich cards used across the Hoverkraft projects directory. It bundles iconography, metadata, tags, and CTA buttons with consistent spacing and hover interactions.
88

9+
## Import
10+
11+
```tsx
12+
import { HoverkraftProjectCard } from "@theme/hoverscape/HoverkraftProjectCard";
13+
```
14+
15+
**Note:** Use the `@theme/` alias for importing components. Do NOT use `@hoverkraft/docusaurus-theme/theme/hoverscape/...` as this will cause module resolution errors.
16+
917
## Usage
1018

1119
```tsx title="src/components/FeaturedProjects.tsx"
12-
import { HoverkraftProjectCard } from "@hoverkraft/docusaurus-theme/components";
20+
import { HoverkraftProjectCard } from "@theme/hoverscape/HoverkraftProjectCard";
1321

1422
const card = {
1523
icon: "⚡",
@@ -31,20 +39,45 @@ const card = {
3139
<HoverkraftProjectCard {...card} />;
3240
```
3341

42+
## Complete Example
43+
44+
```tsx
45+
<HoverkraftProjectCard
46+
icon="⚡"
47+
title="My Awesome Project"
48+
titleHref="https://github.com/user/project"
49+
titleTarget="_blank"
50+
meta="⭐ 1.2k • TypeScript"
51+
description="A modern framework for building scalable applications with great DX."
52+
tags={["typescript", "framework", "developer-tools"]}
53+
accent="primary" // 'primary' | 'neutral'
54+
actions={[
55+
{
56+
label: "Documentation",
57+
to: "/docs",
58+
variant: "outline",
59+
},
60+
]}
61+
/>
62+
```
63+
3464
## Props
3565

36-
| Prop | Type | Description |
37-
| -------------------------- | ------------------------ | -------------------------------------------------- |
38-
| `icon` | `ReactNode` | Emoji or JSX rendered inside the icon container. |
39-
| `title` | `ReactNode` | Project name. |
40-
| `titleHref` / `titleTo` | `string` | External (`href`) or internal (`to`) destination. |
41-
| `titleTarget` / `titleRel` | `string` | Passed to the title link when using external URLs. |
42-
| `meta` | `ReactNode` | Supplementary text (stars, language, etc.). |
43-
| `description` | `ReactNode` | Main body copy. |
44-
| `tags` | `ReactNode[]` | Rendered as capsules below the description. |
45-
| `actions` | `HoverkraftAction[]` | CTA buttons rendered at the bottom. |
46-
| `accent` | `'primary' \| 'neutral'` | Highlight treatment. Defaults to `primary`. |
47-
| `className` / `id` | `string` | Extend styling or deep-link to the card. |
66+
| Prop | Type | Required | Default | Description |
67+
| ------------- | ------------------------ | -------- | ----------- | ---------------------------------------------- |
68+
| `title` | `ReactNode` | ✅ | - | Project name |
69+
| `description` | `ReactNode` | ✅ | - | Project description |
70+
| `icon` | `ReactNode` | ❌ | - | Icon or emoji displayed in the card header |
71+
| `titleHref` | `string` | ❌ | - | External link for title (use with `href` URLs) |
72+
| `titleTo` | `string` | ❌ | - | Internal route for title (use with site paths) |
73+
| `titleTarget` | `string` | ❌ | - | Link target (e.g., `'_blank'` for new tab) |
74+
| `titleRel` | `string` | ❌ | - | Link rel attribute passed to external URLs |
75+
| `meta` | `ReactNode` | ❌ | - | Metadata (stars, language, version, etc.) |
76+
| `tags` | `ReactNode[]` | ❌ | - | Tags/labels rendered as capsules |
77+
| `actions` | `HoverkraftAction[]` | ❌ | - | Call-to-action buttons |
78+
| `accent` | `'primary' \| 'neutral'` | ❌ | `'primary'` | Color accent/highlight treatment |
79+
| `className` | `string` | ❌ | - | Extend styling with additional classes |
80+
| `id` | `string` | ❌ | - | DOM ID for deep-linking to the card |
4881

4982
## Layout suggestions
5083

‎packages/docs/content/configuration.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,37 @@ sidebar_position: 3
66

77
The Hoverkraft theme now inherits from `@docusaurus/theme-classic` and focuses on providing consistent brand styling through CSS and static assets. There are no special `hoverkraft` theme options — the theme is intentionally opinionated about branding.
88

9+
## Version Compatibility
10+
11+
| Theme Version | Docusaurus Version | React Version | Node Version | Status |
12+
| ------------- | ------------------ | ------------- | ------------ | ----------------------------- |
13+
| 1.0.0 | 3.x | 19.x | ≥18.0 | ✅ Stable |
14+
| 0.1.1 | 3.x | 19.x | ≥18.0 | ✅ Stable |
15+
| 0.1.0 | 3.x | 19.x | ≥18.0 | ⚠️ Package issue - use 0.1.1+ |
16+
17+
### Upgrading
18+
19+
When upgrading the theme:
20+
21+
```bash
22+
# Check current version
23+
npm list @hoverkraft/docusaurus-theme
24+
25+
# Update to latest
26+
npm update @hoverkraft/docusaurus-theme
27+
28+
# Or install specific version
29+
npm install @hoverkraft/docusaurus-theme@1.0.0
30+
```
31+
32+
**Breaking Changes:**
33+
34+
- None in current versions
35+
36+
**Deprecations:**
37+
38+
- `HoverkraftHero.brandedText` prop - use `HoverkraftBrandHighlight` component instead
39+
940
## How the theme is applied
1041

1142
- Install the theme package and reference it from `docusaurus.config.js`:

0 commit comments

Comments
 (0)