API Reference

The complete reference for everything exported by Blog Kit. For tutorials and usage examples, see Getting Started and Guides.

---

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

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[]

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')

Returns: Array of BlogMeta objects

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

blogsMeta.forEach((meta) => {
	console.log(meta.title, meta.slug, meta.readingTime);
});

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

Returns the full blog data (metadata + content) for a specific slug.

Parameters:

• 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')

Returns: Blog object or null if not found

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

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

---

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

Components

BlogList

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

---

BlogCard

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

---

BlogRenderer

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

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.

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

---

BlogPlaceholder

Renders animated skeleton loading cards.

---

Hooks

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

Returns:

---

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.

interface BlogMeta {
	title: string;
	description: string;
	date: string;
	categories?: string[];
	slug: string;
	readingTime: string;
}

interface Blog {
	metadata: BlogMeta;
	content: string;
}

interface BlogConfig {
	contentDirectory: string;
	blogSubdirectory?: string; // defaults to 'blog'
}