Skip to content

feat: added search and filter components #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
haroonwaves merged 3 commits into from
Apr 9, 2026
Merged

feat: added search and filter components #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b912fe
feat: add Filter component and integrate search/category filtering in…
haroonwaves Apr 7, 2026
5ee7cae
chore: bump project version to 1.4.0
haroonwaves Apr 7, 2026
d651044
refactor: decouple filtering logic from BlogList and update documenta…
haroonwaves Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Blog Kit

A powerful Next.js-first toolkit for building professional blog systems with markdown. Consists of two packages: a core library for server-side markdown parsing and a React component library for rendering beautiful blog UIs.
A powerful Next.js-first toolkit for building professional blog systems with markdown. Consists of
two packages: a core library for server-side markdown parsing and a React component library for
rendering beautiful blog UIs.

## Documentation

Expand Down
183 changes: 149 additions & 34 deletions app/content/docs/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,88 +1,204 @@
---
title: Blog Kit API Reference
description: Complete API reference for Blog Kit's core package and React components.
title: API Reference
description:
Complete API reference for all Blog Kit functions, components, hooks, utility functions, and
TypeScript types.
date: 2024-01-06
---

## API Reference

Complete reference documentation for all functions, components, hooks, and types available in Blog
Kit. This guide covers both the core package utilities and React components with detailed
parameters, return values, and usage examples.
The complete reference for everything exported by Blog Kit. For tutorials and usage examples, see
[Getting Started](/docs/getting-started) and [Guides](/docs/guides).

### Core Package
---

### Core Package (`@haroonwaves/blog-kit-core`)

#### Server-Side Functions (SSR/SSG only)
All core functions require Node.js (`fs` module) and only work in server environments (Next.js
SSR/SSG, Node.js scripts, etc.).

##### `getAllBlogsMeta(config: BlogConfig): BlogMeta[]`
#### `getAllBlogsMeta(config: BlogConfig): BlogMeta[]`

Returns an array of all blog metadata sorted by date (newest first). Requires Node.js `fs` module.
Returns an array of all blog metadata sorted by date (newest first).

**Parameters:**

- `config.contentDirectory` (string): Path to your content directory
- `config.blogSubdirectory` (string, optional): Subdirectory for blog files (defaults to 'blog')
- `config.blogSubdirectory` (string, optional): Subdirectory for blog files (defaults to `'blog'`)

**Returns:** Array of `BlogMeta` objects

**Example:**

```typescript
const blogsMeta = getAllBlogsMeta({
contentDirectory: './content',
blogSubdirectory: 'posts', // optional
contentDirectory: process.cwd(),
blogSubdirectory: 'content/blog',
});

// blogs is an array of BlogMeta objects
blogsMeta.forEach((meta) => {
console.log(meta.title, meta.slug, meta.readingTime);
});
```

##### `getBlog(slug: string, config: BlogConfig): Blog | null`
#### `getBlog(slug: string, config: BlogConfig): Blog | null`

Returns the full blog data including content for a specific slug. Requires Node.js `fs` module.
Returns the full blog data (metadata + content) for a specific slug.

**Parameters:**

- `slug` (string): The blog post slug (filename without .md)
- `slug` (string): The blog post slug (filename without `.md`)
- `config.contentDirectory` (string): Path to your content directory
- `config.blogSubdirectory` (string, optional): Subdirectory for blog files (defaults to 'blog')
- `config.blogSubdirectory` (string, optional): Subdirectory for blog files (defaults to `'blog'`)

**Returns:** `Blog` object or `null` if not found

**Example:**

```typescript
const blog = getBlog('my-blog-post', {
contentDirectory: './content',
contentDirectory: process.cwd(),
blogSubdirectory: 'content/blog',
});

if (blog) {
console.log(blog.metadata.title);
console.log(blog.content); // blog markdown content
console.log(blog.readingTime);
console.log(blog.metadata.readingTime);
console.log(blog.content);
}
```

### React Package
---

### React Package (`@haroonwaves/blog-kit-react`)

#### Components

- `BlogRenderer` - Renders markdown content with syntax highlighting
- `BlogCard` - Single blog post card component
- `BlogList` - List of blog cards
- `BlogPlaceholder` - Loading placeholder component
##### `BlogList`

A stateless component that renders a list of blog cards. Works with both server-side and client-side
rendering.

| Prop | Type | Default | Description |
| -------------- | --------------------------------------------------------------- | ------------------------ | ------------------------------------------ |
| `metadata` | `BlogMeta[]` | _required_ | Array of blog metadata to render |
| `title` | `string` | — | Page title (rendered as h1) |
| `description` | `string` | — | Page description |
| `basePath` | `string` | `'/blog'` | Base URL for blog post links |
| `renderLink` | `(href, children) => ReactNode` | — | Custom link renderer (e.g. Next.js `Link`) |
| `className` | `string` | — | CSS class for the card container |
| `emptyMessage` | `string` | `'No blog posts found.'` | Message when list is empty |
| `cardProps` | `Omit<BlogCardProps, 'metadata' \| 'basePath' \| 'renderLink'>` | — | Props forwarded to each `BlogCard` |
| `classNames` | `{ title?, description? }` | — | CSS overrides for title and description |

---

##### `BlogCard`

Renders a single blog post card with category badges, reading time, and date.

| Prop | Type | Default | Description |
| ----------------- | ------------------------------- | ---------- | ------------------------------------------ |
| `metadata` | `BlogMeta` | _required_ | Blog metadata object |
| `basePath` | `string` | `'/blog'` | Base path for blog links |
| `renderLink` | `(href, children) => ReactNode` | — | Custom link renderer (e.g. Next.js `Link`) |
| `className` | `string` | — | Additional CSS classes |
| `showCategory` | `boolean` | `true` | Show category badge |
| `showReadingTime` | `boolean` | `true` | Show reading time |
| `showDate` | `boolean` | `true` | Show publication date |

---

##### `BlogRenderer`

Renders markdown content with syntax highlighting (Prism), GFM support, heading anchor links, and
styled typography. Supports custom component overrides.

| Prop | Type | Default | Description |
| ----------------- | ------------------------------- | ---------- | --------------------------------------- |
| `content` | `string` | _required_ | Markdown content to render |
| `metadata` | `BlogMeta` | _required_ | Blog metadata object |
| `className` | `string` | — | Additional CSS classes |
| `components` | `Record<string, ComponentType>` | — | Override default HTML element renderers |
| `showCategory` | `boolean` | `true` | Show category badge |
| `showReadingTime` | `boolean` | `true` | Show reading time |
| `showDate` | `boolean` | `true` | Show publication date |

**Overridable elements:** `h1`–`h6`, `p`, `a`, `blockquote`, `code`, `pre`, `img`, `table`, `thead`,
`tbody`, `tr`, `th`, `td`, `ul`, `ol`, `li`, `strong`, `em`, `del`, `hr`, `br`, `input`

---

##### `Filter`

A client component for searching and category filtering.

| Prop | Type | Default | Description |
| --------------------- | ------------------------------- | ------------------- | --------------------------------- |
| `searchTerm` | `string` | _required_ | Current search input value |
| `setSearchTerm` | `(term: string) => void` | _required_ | Callback for search input changes |
| `selectedCategory` | `string \| null` | _required_ | Currently selected category |
| `setSelectedCategory` | `(cat: string \| null) => void` | _required_ | Callback for category changes |
| `categories` | `string[]` | _required_ | List of available category labels |
| `postsCount` | `number` | — | Number of results to display |
| `placeholder` | `string` | `'Search blogs...'` | Search input placeholder text |
| `className` | `string` | — | Container CSS class |
| `classNames` | `object` | — | CSS overrides (see below) |

**`classNames` keys:** `input`, `categoryContainer`, `pill`, `activePill`, `inactivePill`,
`postsCount`

---

##### `BlogPlaceholder`

Renders animated skeleton loading cards.

| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ------------------------------- |
| `count` | `number` | `3` | Number of placeholder skeletons |
| `className` | `string` | — | Additional CSS classes |

---

#### Hooks

- `useBlogs(blogs: BlogMeta[])` - Provides search and filter functionality
##### `useBlogs(blogsMeta: BlogMeta[])`

A client-side hook that provides search and category filter state management with debounced search
(500ms).

**Parameters:**

- `blogsMeta` (BlogMeta[]): Array of blog metadata to filter

See the [React Package](/docs/react-package) section for detailed examples of each component and
hook.
**Returns:**

| Field | Type | Description |
| --------------------- | ------------------------------- | -------------------------------------- |
| `metadata` | `BlogMeta[]` | Filtered blog posts |
| `searchTerm` | `string` | Current search input value |
| `setSearchTerm` | `(term: string) => void` | Update the search term |
| `selectedCategory` | `string \| null` | Currently selected category |
| `setSelectedCategory` | `(cat: string \| null) => void` | Update selected category |
| `categories` | `string[]` | All unique categories from input blogs |

---

#### Utility Functions

##### `filterBlogs(blogs: BlogMeta[], searchTerm?: string, selectedCategory?: string | null): BlogMeta[]`

Pure utility to filter blogs by search term (matches title and description) and/or category. Useful
for server-side filtering or custom implementations outside of `useBlogs`.

##### `getAvailableCategories(blogs: BlogMeta[]): string[]`

Returns a deduplicated array of all categories across the provided blog metadata.

---

### Types

All types are exported from both `@haroonwaves/blog-kit-core` and `@haroonwaves/blog-kit-react`.

```typescript
interface BlogMeta {
title: string;
Expand All @@ -96,11 +212,10 @@ interface BlogMeta {
interface Blog {
metadata: BlogMeta;
content: string;
readingTime: string;
}

interface BlogConfig {
contentDirectory: string;
blogSubdirectory?: string;
blogSubdirectory?: string; // defaults to 'blog'
}
```
79 changes: 0 additions & 79 deletions app/content/docs/core-package.md
View file
Open in desktop

This file was deleted.

Loading
Loading