Blogkit

A reusable, feature-rich blog component library for React and Next.js applications

Overview

Blogkit is a comprehensive component library built with TypeScript and SCSS modules, providing everything you need to create beautiful, interactive blog posts with code highlighting, diagrams, callouts, and more.

In fact, this documentation page itself was built using Blogkit! You're currently viewing a live example of what Blogkit can do.

Examples

Explore these production-ready examples to see Blogkit in action and learn from real-world implementations:

Live Websites

Blog Post Examples

See how Blogkit handles complex technical content with rich features:

Tip: Browse the source code of these examples to learn best practices for component usage, styling customization, and application structure. Each example demonstrates different use cases and complexity levels.

System Requirements

Requirement
Details
Node.js
18.0.0 or higher (20.x LTS recommended)
Package Manager
npm 7+, yarn 1.22+, or pnpm 8+
React
^19.0.0 or higher
React DOM
^19.0.0 or higher
Next.js
^16.0.10 or higher
TypeScript
5.0.0 or higher (optional)

Browser Support: Blogkit supports all modern browsers including Chrome 90+, Firefox 88+, Safari 14+, and Edge 90+.

Installation

Install Blogkit using npm or yarn:

bash
npm install @san-siva/blogkit

Note: npm 7+ will automatically prompt you to install peer dependencies if they're missing.

Setup

Important: You must import the Blogkit styles in your root layout or app entry point.

Why is this required?
Blogkit pre-compiles its SCSS modules into CSS at build time. This means you don't need Sass as a dependency, and your builds are faster. The styles.css import provides all component styles, responsive design rules, theme variables, and critical layout styles. Without it, components will render unstyled.

tsx
// app/layout.tsx or _app.tsx
// REQUIRED: Import Blogkit styles once in your root layout
// This provides all compiled SCSS module styles for components
import '@san-siva/blogkit/styles.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Quick Start

Once you've imported the styles, you can start using Blogkit components:

tsx
import { Blog, BlogHeader, BlogSection } from '@san-siva/blogkit';

// Note: Ensure you've imported '@san-siva/blogkit/styles.css' in your root layout

export default function MyBlog() {
  return (
    <Blog>
      <BlogHeader
        title={['My Blog Post']}
        desc={['A description of my blog post']}
      />
      <BlogSection title="Introduction">
        <p>Your content here...</p>
      </BlogSection>
    </Blog>
  );
}

Core Components

Blog

The main container component that wraps all your blog content.

tsx
<Blog>
  {/* Your blog content */}
</Blog>
Prop
Type
Default
Description
children
ReactNode
Blog content
title
string
"In this article"
Label for the table of contents
jsonLd
WithContext<Thing>
undefined
Schema.org structured data injected as a JSON-LD script tag

JSON-LD / Structured Data

JSON-LD (JavaScript Object Notation for Linked Data) is a lightweight way to embed machine-readable metadata directly inside your HTML. Search engines like Google read this metadata to understand the content of a page beyond what they can infer from the visible text alone — enabling rich results such as article cards, author attribution, publish dates, and breadcrumbs in search listings.

Unlike <meta> tags, which only describe the page in general terms, JSON-LD lets you express precise, typed facts about your content using the shared vocabulary defined by Schema.org. For example, a BlogPosting type can carry the headline, author, publication date, and canonical URL all in one structured block — the same information that social platforms and search engines surface when previewing your link.

Pass a jsonLd prop to the Blog component to inject this metadata as a <script type="application/ld+json"> tag in the page head. Blogkit uses the schema-dts package to give you full TypeScript types for every Schema.org type, so mistakes are caught at compile time.

Tip: Use a specific Schema.org type like BlogPosting, Article, or TechArticle instead of the base Thing type for richer structured data.

tsx
import { Blog } from '@san-siva/blogkit';
import type { WithContext, BlogPosting } from 'schema-dts';

const jsonLd: WithContext<BlogPosting> = {
  '@context': 'https://schema.org',
  '@type': 'BlogPosting',
  headline: 'My Blog Post Title',
  description: 'A short description of the post',
  author: {
    '@type': 'Person',
    name: 'Author Name',
  },
  datePublished: '2025-01-01',
  url: 'https://blogkit.santhoshsiva.dev/',
};

export default function MyBlogPost() {
  return (
    <Blog jsonLd={jsonLd}>
      {/* Your blog content */}
    </Blog>
  );
}

BlogHeader

Display a title and description at the top of your blog post.

tsx
<BlogHeader
  title={['My Blog Title']}
  desc={['Posted on January 1, 2025']}
/>
Prop
Type
Description
title
string[]
Array of title lines
desc
string[]
Array of description lines

BlogSection

Create sections within your blog post with optional titles.

tsx
<BlogSection title="Section Title" hasMarginBottom>
  <p>Your section content...</p>
</BlogSection>
Prop
Type
Description
title
string
Section title (optional)
hasMarginBottom
boolean
Add margin at the bottom (optional)
children
ReactNode
Section content

CodeBlock

Display syntax-highlighted code blocks with support for multiple programming languages.

tsx
<CodeBlock
  language="typescript"
  code={`const greeting = "Hello, World!";`}
  hasMarginDown={true}
/>
Prop
Type
Description
code
string
Code to display
language
string
Programming language for syntax highlighting
hasMarginDown
boolean
Add margin below the code block (optional)

Callout

Highlight important information with styled callout boxes.

Information: This is an informative message, often used to provide
context or additional details to users.

Warning: This is a warning message, typically used to alert users of
potential risks or issues.

Error: This is an error message, used to notify users of critical
problems or failures.

Success: This is a success message, indicating that an action or
operation was completed successfully.

tsx
<Callout type="info">
  <p>
    <b>Information:</b>
		This is an informative message, often used to provide
    <br />
    context or <b>additional details</b> to users.
  </p>
</Callout>
Prop
Type
Description
type

"info",
"warning",
"error",
"success"

Callout style
hasMarginDown
boolean
Add margin below (optional)
children
ReactNode
Callout content

Mermaid

Render diagrams and visualizations using Mermaid syntax. Supports flowcharts, sequence diagrams, timelines, and more.

Diagram Loading...

tsx
<Mermaid
  id="my-diagram"
  code={`flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
    C --> D`}
  hasMarginDown={true}
/>
Prop
Type
Description
id
string
Unique identifier for the diagram
code
string
Mermaid diagram code
hasMarginUp
boolean
Add margin above (optional)
hasMarginDown
boolean
Add margin below (optional)

BlogLink

Create animated links to blog posts with title, description, and hover effects.

tsx
<BlogLink
  title="My Blog Post"
  desc="A short description of the blog post content"
  href="/blog/my-blog-post"
/>
Prop
Type
Description
title
string
Link title
desc
string
Link description (optional)
href
string
Custom URL (optional, defaults to /blog/[title-slug])
isInProgress
boolean
Hide link if post is in progress (optional)

Table

Display tabular data with headers and rows. Columns automatically size to fit their content for optimal space usage.

tsx
<Table
  headers={['Column 1', 'Column 2', 'Column 3']}
  rows={[
    ['Row 1, Col 1', 'Row 1, Col 2', 'Row 1, Col 3'],
    ['Row 2, Col 1', 'Row 2, Col 2', 'Row 2, Col 3'],
  ]}
  hasMarginDown={true}
  fontSize="14px"
/>
Prop
Type
Description
headers
(string | ReactNode)[]
Table header cells
rows
(string | ReactNode)[][]
Table rows
hasMarginDown
boolean
Add margin below (optional)
hasMarginUp
boolean
Add margin above (optional)
fontSize
string
Custom font size (e.g., "14px", "1rem") (optional)

Features

Feature
Description
Blog Layout with TOC
Responsive blog layout with sticky table of contents sidebar
Code Highlighting
Syntax highlighting for multiple programming languages using Prism.js
Mermaid Diagrams
Render flowcharts, sequence diagrams, timelines, and more
Callouts
Info, warning, error, and success notification boxes
Data Tables
Flexible table component with dynamic column sizing
Blog Sections
Hierarchical section organization with auto-generated IDs
Blog Links
Animated link cards for blog navigation

Developer Experience

Feature
Description
TypeScript Support
Fully typed components with ReactNode support
SCSS Modules
Scoped, customizable styles using StyleKit

Compatibility

Feature
Description
Next.js Optimized
Works seamlessly with Next.js 14, 15, and 16
React 19 Ready
Full support for React 18 and 19

SEO

Feature
Description
Deep Linking
Sections generate shareable ?section= URLs with scroll-aware TOC highlighting that activates only after user interaction
SSR & Hydration Safe
Static fallback renders full content server-side for instant load and SEO; interactive layer hydrates progressively via Suspense without layout shift
JSON-LD / Structured Data
Inject Schema.org structured data via the jsonLd prop to enable rich search results such as article cards, author attribution, and publish dates

Customization

Blogkit is powered by StyleKit, a modular SCSS design system that provides the foundation for all styling in Blogkit. StyleKit is a comprehensive design system that includes colors, typography, spacing utilities, animations, and responsive breakpoints.

How StyleKit Powers Blogkit

StyleKit provides Blogkit with a consistent design language through:

  • Color System: Primary, secondary, accent, and semantic colors with variants for consistent theming
  • Typography Scale: Font families, sizes, weights, and line heights for harmonious text hierarchy
  • Spacing System: A 0-9 scale (4px to 96px) for consistent margins and padding
  • Utility Classes: Pre-built classes for common styling patterns
  • Responsive Design: Built-in breakpoints for mobile-first layouts
  • Animations: Smooth transitions and loading animations

By leveraging StyleKit, Blogkit ensures visual consistency across all components while giving you full control over customization through SCSS variables and CSS custom properties.

Customizing Your Blog

You can customize Blogkit's appearance in two ways:

  1. Override StyleKit Variables: Import StyleKit in your own SCSS files and override variables to match your brand
  2. Use CSS Custom Properties: Override CSS variables at runtime for dynamic theming

Visit the StyleKit documentation to explore all available design tokens and customization options.

Browser Support

Blogkit supports all modern browsers with the following minimum versions:

Browser
Minimum Version
Chrome
90+
Firefox
88+
Safari
14+ (macOS and iOS)
Edge
90+

Contributing

Contributions are welcome! Please fork the repository and submit pull requests. For bugs or feature requests, open an issue on the repository.

View source code, report issues, and contribute

License

This project is licensed under the MIT License.