blogkit-md

A React component library that converts markdown files into rendered blog posts for `@san-siva/blogkit`.

A React component library that converts markdown files into rendered blog posts for @san-siva/blogkit.

Live preview of this README is available here blogkit-md.santhoshsiva.dev

Getting started

No title

blogkit-md exposes a BlogPost server component you can drop into any Next.js project.

Install

bash
npm install @san-siva/blogkit-md

Usage

tsx
import { BlogPost } from '@san-siva/blogkit-md';

export default function Page() {
	return (
		<BlogPost
			filePath="content/my-post.md"
			jsonLd={{
				'@context': 'https://schema.org',
				'@type': 'BlogPosting',
				headline: 'My Post',
				description: 'Post description',
				datePublished: '2026-01-01',
				author: { '@type': 'Person', name: 'Your Name' },
			}}
		/>
	);
}

Props

Prop
Type
Required
Description

filePath

string

Yes

Path to the markdown file. Relative paths are resolved from process.cwd().

jsonLd

WithContext<Thing>

No

Optional JSON-LD schema passed to <Blog> for structured data / SEO.

Frontmatter

Set the page title and description via a YAML frontmatter block at the top of your markdown file:

yaml
---
title: My Post Title
description: A short description shown below the title
---
Field
Description

title

Renders as the BlogHeader page title

description

Renders as the BlogHeader description

Supported markdown features

Feature
Syntax

Frontmatter

--- YAML block — sets title, description

Section title

# H1 ## H2 — top-level section

Subsection title

### H3 — nested section

Bold line

#### H4 ##### H5 ###### H6

Paragraph

Plain text

Hard line break

Two spaces at end of line

Bold

**bold**

Italic

_italic_

Inline code

`code`

Link

[text](url)

Image

![alt](url)

Ordered list

1. item

Unordered list

- item

Task list

- [ ] item / - [x] item

Table

| col | col | — headers and rows only

Code block

```lang

Mermaid diagram

```mermaid

Thematic break

---

Blockquote / Callout

> text or > [!TYPE] — renders as callout

Philosophy

Not Your Average Markdown Viewer

If you're looking for a strictly standard, 1:1 markdown renderer, blogkit-md might not be what you expect.

Instead of building just another plain document viewer, intentional design liberties have been taken to render markdown as beautiful, engaging blog posts.

Documentation shouldn't be a wall of boring text. The goal of this tool is to make reading technical docs, articles, and guides an exciting and visually pleasing experience.

Key Differences

blogkit-md
Plain markdown renderer

Output

Styled blog post

Raw document

Typography

Optimized for long-form reading

Unstyled

Ecosystem

Built for Blogkit

Generic

Architecture

The markdown file is parsed into an AST using remark-parse + remark-gfm, then transformed into React components from @san-siva/blogkit.

mermaid
flowchart LR
    A[Markdown file] --> B[Parse AST]
    B --> C[Group sections]
    C --> D[Render to React]
    D --> E[Blog page]

How Markdown Translates to Blog Sections

Headings as Layout Triggers

In blogkit-md, headings aren't just for changing font sizes — they are the architectural blueprint for your post.

Markdown
Layout Behavior

# H1 & ## H2

Top-level section. Creates a new BlogSection.

### H3

Subsection. Nests within the active H1/H2 section. Promoted to top-level if none exists.

#### H4 ##### H5 ###### H6

Bold line. Rendered as styled text inside the current section — no layout effect.

Standard content — paragraphs, lists, code blocks — flows into the most recently opened section or subsection.

The Nesting Logic

The layout is determined entirely by heading level (depth):

  • Deeper heading (level up): If a heading has a higher number than the current one (e.g. ### H3 after ## H2), it creates a nested subsection inside the current section.

  • Equal or shallower heading (level down): If a heading has a number equal to or lower than the current one (e.g. ## H2 after another ## H2), it closes the current section and starts a new one at the appropriate level.

  • Initial content: Any content before the very first heading is grouped into an automatic untitled intro section.

Visualizing the Structure

Here is how a standard markdown document maps to blog layout:

markdown
Intro content

## The Setup

Some content goes here.

### Prerequisites

Nested content belongs here.

## The Execution

Some more content.

### The Results

Result content.

# A Note

### A Subsection

## Also Nested

Here is how the parser breaks the above document down into isolated React components:

Intro section

markdown
Intro content

Section 1

markdown
## The Setup

Some content goes here.

### Prerequisites

Nested content belongs here.

Section 2

markdown
## The Execution

Some more content.

### The Results

Result content.

Section 3

markdown
# A Note

### A Subsection

## Also Nested

## Also Nested does not start a new top-level section. Because it appears after a ### H3 inside an # H1, the parser backtracks to the H1 and nests the H2 beneath it.

Callouts

Blockquotes are rendered as styled callout banners. Plain blockquotes render as info callouts. Use GitHub-style alert syntax to control the type:

Syntax
Callout type

[!NOTE]

info

[!TIP]

info

[!IMPORTANT]

info

[!WARNING]

warning

[!CAUTION]

error

markdown
> [!WARNING]
>
> Do not clone this repository into system folders.

The [!TYPE] line is stripped from the rendered output.

Want more customization?

blogkit-md is just one piece of the puzzle. If you want to customize the underlying React components, tweak the UI, or take full control over your blog's layout, dive into the official Blogkit documentation.

License

blogkit-md is open source software licensed under the MIT license.
Contributions are welcome!

About