@san-siva/blogkit-md 0.1.0

package/hooks/readMarkdownFile.ts

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import '@/utils/devReloadTrigger';
+import { parseMarkdown } from '@/utils/parseMarkdown';
+import type { RenderedMarkdown } from '@/utils/renderMarkdown';
+import { renderMarkdownAst } from '@/utils/renderMarkdown';
+
+type MarkdownFileResult =
+	| { success: true; rendered: RenderedMarkdown }
+	| { success: false; error: string };
+
+export const readMarkdownFile = async (
+	filePath: string | undefined
+): Promise<MarkdownFileResult> => {
+	if (!filePath) {
+		return {
+			success: false,
+			error:
+				'MARKDOWN_FILE env variable is required. Usage: MARKDOWN_FILE=data/test.md npm run dev',
+		};
+	}
+
+	const absolutePath = path.join(process.cwd(), filePath);
+
+	let content: string;
+	try {
+		content = await readFile(absolutePath, 'utf8');
+	} catch {
+		return {
+			success: false,
+			error: `Could not read file: "${filePath}". Make sure the path is correct and the file exists.`,
+		};
+	}
+
+	if (!content.trim()) {
+		return { success: false, error: `File "${filePath}" is empty.` };
+	}
+
+	const ast = parseMarkdown(content);
+	const rendered = renderMarkdownAst(ast);
+
+	return { success: true, rendered };
+};

package/index.ts

@@ -0,0 +1 @@
+export { default as BlogPost } from './components/BlogPost';

package/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@san-siva/blogkit-md",
+	"version": "0.1.0",
+	"description": "Converts markdown files into JSX blog posts for Blogkit",
+	"main": "index.ts",
+	"exports": {
+		".": "./index.ts"
+	},
+	"scripts": {
+		"dev": "tsx scripts/dev.ts",
+		"build": "MARKDOWN_FILE=data/test.md next build",
+		"start": "next start",
+		"lint": "eslint . --config eslint.config.ts",
+		"fix": "eslint . --config eslint.config.ts --fix"
+	},
+	"dependencies": {
+		"@san-siva/blogkit": "^1.1.20",
+		"@san-siva/stylekit": "^1.0.8",
+		"next": "^16.0.10",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"remark-gfm": "^4.0.1",
+		"schema-dts": "^1.1.2",
+		"remark-parse": "^11.0.0",
+		"sass": "^1.95.1",
+		"unified": "^11.0.5"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.0.0",
+		"@types/eslint": "^9.6.1",
+		"@types/eslint__js": "^9.14.0",
+		"@types/mdast": "^4.0.4",
+		"@types/node": "^22",
+		"@types/react": "^19",
+		"@types/react-dom": "^19",
+		"eslint": "^9.0.0",
+		"eslint-config-next": "^16.0.10",
+		"eslint-config-prettier": "^10.0.0",
+		"eslint-import-resolver-typescript": "^4.0.0",
+		"eslint-plugin-import": "^2.0.0",
+		"eslint-plugin-jsx-a11y": "^6.10.0",
+		"eslint-plugin-no-await-in-promise": "^3.0.0",
+		"eslint-plugin-prettier": "^5.0.0",
+		"eslint-plugin-react": "^7.0.0",
+		"eslint-plugin-react-hooks": "^5.0.0",
+		"eslint-plugin-simple-import-sort": "^12.0.0",
+		"eslint-plugin-unicorn": "^62.0.0",
+		"jiti": "^2.0.0",
+		"prettier": "^3.0.0",
+		"tsx": "^4.0.0",
+		"typescript": "^5.0.0",
+		"typescript-eslint": "^8.0.0"
+	}
+}

package/scripts/dev.ts

@@ -0,0 +1,50 @@
+import { exec, spawn } from 'node:child_process';
+import { stat, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const fileArgument = process.argv.find(argument => argument.startsWith('--file='));
+const markdownFile = fileArgument ? fileArgument.replace('--file=', '') : 'data/test.md';
+
+const markdownPath = path.join(process.cwd(), markdownFile);
+const triggerPath = path.join(process.cwd(), 'utils/devReloadTrigger.ts');
+
+// Write on startup so fresh clones have the file before Next.js compiles.
+writeFileSync(triggerPath, `export const reloadTrigger = '${Date.now()}';\n`);
+
+let lastMtime: number | null = null;
+
+const checkMarkdownFile = () => {
+	stat(markdownPath, (error, stats) => {
+		if (error) return;
+		const { mtimeMs } = stats;
+		if (lastMtime !== null && mtimeMs !== lastMtime) {
+			writeFileSync(triggerPath, `export const reloadTrigger = '${mtimeMs}';\n`);
+		}
+		lastMtime = mtimeMs;
+	});
+};
+
+setInterval(checkMarkdownFile, 500);
+checkMarkdownFile();
+
+const child = spawn('next', ['dev'], {
+	env: { ...process.env, MARKDOWN_FILE: markdownFile },
+	stdio: ['inherit', 'pipe', 'inherit'],
+});
+
+let browserOpened = false;
+
+child.stdout?.on('data', (chunk: Buffer) => {
+	process.stdout.write(chunk);
+	if (!browserOpened) {
+		const match = chunk.toString().match(/http:\/\/localhost:\d+/);
+		if (match) {
+			browserOpened = true;
+			exec(`open ${match[0]}`);
+		}
+	}
+});
+
+child.on('exit', code => {
+	process.exit(code ?? 0);
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+	"compilerOptions": {
+		"target": "ES2017",
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"allowJs": true,
+		"skipLibCheck": true,
+		"strict": true,
+		"noEmit": true,
+		"esModuleInterop": true,
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"jsx": "react-jsx",
+		"incremental": true,
+		"plugins": [{ "name": "next" }],
+		"paths": {
+			"@/*": ["./*"]
+		}
+	},
+	"include": [
+		"next-env.d.ts",
+		"**/*.ts",
+		"**/*.tsx",
+		".next/types/**/*.ts",
+		".next/dev/types/**/*.ts"
+	],
+	"exclude": ["node_modules", "dist"]
+}

package/utils/extractText.ts

@@ -0,0 +1,11 @@
+import type { PhrasingContent } from 'mdast';
+
+export const extractText = (nodes: PhrasingContent[]): string =>
+	nodes
+		.map(node => {
+			if (node.type === 'text') return node.value;
+			if ('children' in node)
+				return extractText(node.children as PhrasingContent[]);
+			return '';
+		})
+		.join('');

package/utils/groupSections.ts

@@ -0,0 +1,114 @@
+import type { RootContent } from 'mdast';
+
+import { extractText } from './extractText';
+
+export type Section = {
+	title: string;
+	nodes: RootContent[];
+	subsections: Section[];
+};
+
+export type GroupedSections = {
+	pageTitle: string | null;
+	beforeFirstHeading: RootContent[];
+	textBeforeFirstSection: RootContent[];
+	sections: Section[];
+};
+
+const makeSection = (title: string): Section => ({
+	title,
+	nodes: [],
+	subsections: [],
+});
+
+// Closes over `sections` (const array — mutation only, CFA-safe).
+// Callers assign the return value to `currentSection` directly in the
+// outer scope so TypeScript's CFA can track the narrowing correctly.
+const addSection = (title: string, sections: Section[]): Section => {
+	const section = makeSection(title);
+	sections.push(section);
+	return section;
+};
+
+export const groupSections = (nodes: RootContent[]): GroupedSections => {
+	let pageTitle: string | null = null;
+	const beforeFirstHeading: RootContent[] = [];
+	const textBeforeFirstSection: RootContent[] = [];
+	const sections: Section[] = [];
+	let currentSection: Section | null = null;
+	let currentSubsection: Section | null = null;
+	let seenFirstHeading = false;
+	let afterH1 = false;
+	let seenH4InCurrentSection = false;
+
+	for (const node of nodes) {
+		if (node.type === 'heading') {
+			seenFirstHeading = true;
+
+			switch (node.depth) {
+				case 1: {
+					if (sections.length === 0) {
+						pageTitle = extractText(node.children);
+						afterH1 = true;
+					} else {
+						currentSubsection = null;
+						seenH4InCurrentSection = false;
+						currentSection = addSection(extractText(node.children), sections);
+					}
+					break;
+				}
+				case 2: {
+					currentSubsection = null;
+					seenH4InCurrentSection = false;
+					currentSection = addSection(extractText(node.children), sections);
+					afterH1 = false;
+					break;
+				}
+				case 3: {
+					if (seenH4InCurrentSection) {
+						currentSubsection = null;
+						seenH4InCurrentSection = false;
+						currentSection = addSection(extractText(node.children), sections);
+					} else {
+						currentSubsection = makeSection(extractText(node.children));
+						currentSection?.subsections.push(currentSubsection);
+					}
+					break;
+				}
+				case 4: {
+					seenH4InCurrentSection = true;
+					(currentSubsection ?? currentSection)?.nodes.push(node);
+					break;
+				}
+				case 5:
+				case 6: {
+					(currentSubsection ?? currentSection)?.nodes.push(node);
+					break;
+				}
+				// No default
+			}
+			continue;
+		}
+
+		if (!seenFirstHeading) {
+			beforeFirstHeading.push(node);
+			continue;
+		}
+
+		if (currentSubsection) {
+			currentSubsection.nodes.push(node);
+			continue;
+		}
+
+		if (currentSection) {
+			currentSection.nodes.push(node);
+			continue;
+		}
+
+		if (afterH1) {
+			textBeforeFirstSection.push(node);
+		}
+	}
+
+	return { pageTitle, beforeFirstHeading, textBeforeFirstSection, sections };
+};

package/utils/parseMarkdown.ts

@@ -0,0 +1,9 @@
+import type { Root } from 'mdast';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+
+export const parseMarkdown = (content: string): Root => {
+	const processor = unified().use(remarkParse).use(remarkGfm);
+	return processor.parse(content) as Root;
+};

package/utils/renderMarkdown.tsx

@@ -0,0 +1,163 @@
+import React from 'react';
+
+import { BlogSection, Callout, CodeBlock, Mermaid, Table } from '@san-siva/blogkit';
+import type { Root, RootContent } from 'mdast';
+
+import type { Section } from './groupSections';
+import { groupSections } from './groupSections';
+import { renderPhrasingContent } from './renderPhrasingContent';
+
+import styles from '@san-siva/stylekit/styles/index.module.scss';
+
+function renderNode(
+	node: RootContent,
+	key: number,
+	nextNode?: RootContent,
+	inList = false
+): React.ReactNode {
+	switch (node.type) {
+		case 'paragraph': {
+			if (inList) {
+				return <p key={key}>{renderPhrasingContent(node.children)}</p>;
+			}
+			const marginClass =
+				nextNode?.type === 'paragraph'
+					? styles['margin-bottom--1']
+					: styles['margin-bottom--2'];
+			return (
+				<p key={key} className={marginClass}>
+					{renderPhrasingContent(node.children)}
+				</p>
+			);
+		}
+		case 'code': {
+			if (node.lang === 'mermaid') {
+				return (
+					<Mermaid
+						key={key}
+						id={`mermaid-${key}`}
+						code={node.value}
+						hasMarginUp
+						hasMarginDown
+					/>
+				);
+			}
+			return (
+				<CodeBlock
+					key={key}
+					language={node.lang ?? 'text'}
+					code={node.value}
+					hasMarginUp
+					hasMarginDown
+				/>
+			);
+		}
+		case 'heading': {
+			return (
+				<p key={key} className={styles['margin-bottom--2']}>
+					<strong>{renderPhrasingContent(node.children)}</strong>
+				</p>
+			);
+		}
+		case 'thematicBreak': {
+			return <hr key={key} className={styles['margin-bottom--2']} />;
+		}
+		case 'table': {
+			const [headerRow, ...bodyRows] = node.children;
+			const headers = headerRow?.children.map(cell =>
+				renderPhrasingContent(cell.children)
+			);
+			const rows = bodyRows.map(row =>
+				row.children.map((cell, index) => (
+					<p key={index}>{renderPhrasingContent(cell.children)}</p>
+				))
+			);
+			return (
+				<Table
+					key={key}
+					headers={headers}
+					rows={rows}
+					hasMarginUp
+					hasMarginDown
+				/>
+			);
+		}
+		case 'blockquote': {
+			const children = node.children as RootContent[];
+			return (
+				<Callout key={key} type="info" hasMarginUp hasMarginDown>
+					{children.map((child, index) =>
+						renderNode(child, index, children[index + 1])
+					)}
+				</Callout>
+			);
+		}
+		case 'list': {
+			const Tag = node.ordered ? 'ol' : 'ul';
+			return (
+				<Tag key={key}>
+					{node.children.map((item, index) => (
+						<li key={index}>
+							{item.children.map((child, index) =>
+								renderNode(child as RootContent, index, undefined, true)
+							)}
+						</li>
+					))}
+				</Tag>
+			);
+		}
+		default: {
+			return null;
+		}
+	}
+}
+
+function renderNodes(nodes: RootContent[]): React.ReactNode[] {
+	return nodes.map((node, index) => renderNode(node, index, nodes[index + 1]));
+}
+
+function renderSection(section: Section, key: number): React.ReactNode {
+	return (
+		<BlogSection key={key} title={section.title}>
+			{renderNodes(section.nodes)}
+			{section.subsections.map((subsection, index) =>
+				renderSection(subsection, index)
+			)}
+		</BlogSection>
+	);
+}
+
+export type RenderedMarkdown = {
+	pageTitle: string | null;
+	beforeFirstHeading: React.ReactNode[];
+	textBeforeFirstSection: React.ReactNode[];
+	sections: React.ReactNode[];
+};
+
+export const renderMarkdownAst = (ast: Root): RenderedMarkdown => {
+	const { pageTitle, beforeFirstHeading, textBeforeFirstSection, sections } =
+		groupSections(ast.children);
+
+	return {
+		pageTitle,
+		beforeFirstHeading: renderNodes(beforeFirstHeading),
+		textBeforeFirstSection: renderNodes(textBeforeFirstSection),
+		sections: sections.map((section, index) => renderSection(section, index)),
+	};
+};
+
+export const MarkdownSections = ({
+	rendered,
+}: {
+	rendered: RenderedMarkdown;
+}): React.ReactNode => (
+	<>
+		{rendered.beforeFirstHeading.length > 0 && (
+			<BlogSection>{rendered.beforeFirstHeading}</BlogSection>
+		)}
+		{rendered.textBeforeFirstSection.length > 0 && (
+			<BlogSection>{rendered.textBeforeFirstSection}</BlogSection>
+		)}
+		{rendered.sections}
+	</>
+);

package/utils/renderPhrasingContent.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+
+import type { PhrasingContent } from 'mdast';
+
+import styles from '@san-siva/stylekit/styles/index.module.scss';
+
+function escapeHtml(text: string): string {
+	return text
+		.replaceAll('&', '&')
+		.replaceAll('<', '&lt;')
+		.replaceAll('>', '&gt;');
+}
+
+function toHtmlString(nodes: PhrasingContent[]): string {
+	return nodes
+		.map(node => {
+			switch (node.type) {
+				case 'text': {
+					return escapeHtml(node.value);
+				}
+				case 'html': {
+					return node.value;
+				}
+				case 'strong': {
+					return `<strong>${toHtmlString(node.children)}</strong>`;
+				}
+				case 'emphasis': {
+					return `<em>${toHtmlString(node.children)}</em>`;
+				}
+				case 'inlineCode': {
+					return `<code>${escapeHtml(node.value)}</code>`;
+				}
+				case 'link': {
+					return `<a href="${escapeHtml(node.url)}">${toHtmlString(node.children)}</a>`;
+				}
+				case 'break': {
+					return '<br>';
+				}
+				case 'image': {
+					return `<img src="${escapeHtml(node.url)}" alt="${escapeHtml(node.alt ?? '')}" style="max-width:300px">`;
+				}
+				default: {
+					return '';
+				}
+			}
+		})
+		.join('');
+}
+
+export function renderPhrasingContent(
+	nodes: PhrasingContent[]
+): React.ReactNode {
+	if (nodes.some(node => node.type === 'html')) {
+		return <span dangerouslySetInnerHTML={{ __html: toHtmlString(nodes) }} />;
+	}
+
+	return nodes.map((node, index) => {
+		switch (node.type) {
+			case 'text': {
+				return node.value;
+			}
+			case 'strong': {
+				return (
+					<strong key={index}>{renderPhrasingContent(node.children)}</strong>
+				);
+			}
+			case 'emphasis': {
+				return <em key={index}>{renderPhrasingContent(node.children)}</em>;
+			}
+			case 'inlineCode': {
+				return <code key={index}>{node.value}</code>;
+			}
+			case 'link': {
+				return (
+					<a key={index} href={node.url} className={styles['a--highlighted']}>
+						{renderPhrasingContent(node.children)}
+					</a>
+				);
+			}
+			case 'break': {
+				return <br key={index} />;
+			}
+			case 'image': {
+				return (
+					<img
+						key={index}
+						src={node.url}
+						alt={node.alt ?? ''}
+						style={{ maxWidth: '300px' }}
+					/>
+				);
+			}
+			default: {
+				return null;
+			}
+		}
+	});
+}

package/website/app/data.ts

@@ -0,0 +1,46 @@
+export const SITE_URL = 'https://blogkit-md.santhoshsiva.dev';
+
+export type PageMeta = {
+	title: string;
+	desc: string;
+	publishedOn: string;
+	isoDate: string;
+	keywords: string[];
+};
+
+export const generateMetadata = (meta: PageMeta) => ({
+	title: meta.title,
+	description: meta.desc,
+	keywords: meta.keywords,
+	authors: [{ name: 'Santhosh Siva' }],
+	alternates: {
+		canonical: `${SITE_URL}/`,
+	},
+	openGraph: {
+		title: meta.title,
+		description: meta.desc,
+		type: 'website' as const,
+		url: `${SITE_URL}/`,
+	},
+	twitter: {
+		card: 'summary_large_image' as const,
+		title: meta.title,
+		description: meta.desc,
+	},
+});
+
+export const BLOGKIT_MD: PageMeta = {
+	title: 'blogkit-md — Markdown to Blog',
+	desc: 'A Next.js tool that converts standard markdown files into rendered blog posts for Blogkit.',
+	publishedOn: 'March 18, 2026',
+	isoDate: '2026-03-18',
+	keywords: [
+		'markdown',
+		'blog',
+		'next.js',
+		'blogkit',
+		'react',
+		'remark',
+		'mdast',
+	],
+};