@san-siva/blogkit-md 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,11 @@
-# blogkit-md
+---
+title: blogkit-md
+description: A Next.js tool that converts standard markdown files into rendered blog posts for `@san-siva/blogkit`.
+---
 
 A Next.js tool that converts standard markdown files into rendered blog posts for [`@san-siva/blogkit`](https://blogkit.santhoshsiva.dev).
 
-> Note: [This](https://blogkit-md.santhoshsiva.dev) blog post is translated from the `README.md` file in the [`blogkit-md`](https://github.com/san-siva/blogkit-md) repository.
+> This README is automatically rendered as a live demo at [blogkit-md.santhoshsiva.dev](https://blogkit-md.santhoshsiva.dev)
 
 ## Getting started
 
@@ -87,25 +90,46 @@ export default function Page() {
 | `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                             |
-| --------------- | ---------------------------------- |
-| Headings        | `# H1` `## H2` `### H3` `#### H4`  |
-| 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`                           |
-| Table           | GFM table syntax                   |
-| Code block      | ` ```lang `                        |
-| Mermaid diagram | ` ```mermaid `                     |
-| Thematic break  | `---`                              |
-| Blockquote      | `> text` — renders as info callout |
+| 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`                                       |
+| Table                | GFM table syntax                               |
+| Code block           | ` ```lang `                                    |
+| Mermaid diagram      | ` ```mermaid `                                 |
+| Thematic break       | `---`                                          |
+| Blockquote           | `> text` — renders as info callout             |
+| Blockquote (warning) | `> ~text` — renders as warning callout         |
+| Blockquote (error)   | `> !text` — renders as error callout           |
 
 ## Philosophy
 
@@ -141,36 +165,30 @@ flowchart LR
 
 ### Headings as Layout Triggers
 
-In `blogkit-md`, headings aren't just for changing font sizes—**they are the architectural blueprint for your post**. Each heading level acts as a layout trigger, directly controlling how `BlogSection` components are generated, nested, or promoted.
+In `blogkit-md`, headings aren't just for changing font sizes — **they are the architectural blueprint for your post**.
 
-| Markdown                 | Layout Behavior                                                                                                                                            |
-| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `# H1`                   | **Page Title.** Sets the main article title. Does not generate a structural section block.                                                                 |
-| `## H2`                  | **Main Section.** Creates a new, top-level `BlogSection`.                                                                                                  |
-| `### H3`                 | **Subsection.** Nests cleanly within the currently active `H2` section.                                                                                    |
-| `#### H4`                | **Section Break.** Renders as a bold line, but acts as a layout trigger: it forces the _next_ `H3` to break out and become a brand-new, top-level section. |
-| `##### H5` & `###### H6` | **Inline Emphasis.** Renders as a bold line within the current section or subsection without altering the page layout.                                     |
+| 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—such as paragraphs, lists, and code blocks—automatically flows into the most recently opened section or subsection.
+> Standard content — paragraphs, lists, code blocks — flows into the most recently opened section or subsection.
 
-### Special Layout Rules
+### The Nesting Logic
 
-Because `blogkit-md` is optimized for blog readability, it includes smart fallbacks to ensure your layout looks great even in edge cases:
+The layout is determined entirely by heading level (depth):
 
-| Rule                                                 | Behavior                                                                                                                                                                                                              |
-| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Strictly Deepening Hierarchy                         | Headings within a section must always go deeper (e.g., `H2 → H3 → H4`). If the hierarchy reverses—like an `H3` appearing after an `H4`—the nesting breaks, and the `H3` is promoted to a brand-new top-level section. |
-| `H1` loses structural significance if not at the top | If an `H1` appears anywhere other than the very top of the document, it does not create a page title. Instead, it is treated as stylized text and rendered as a section break.                                        |
-| Intro section                                        | Any text written before the first heading—or directly beneath the `# H1` page title—is automatically grouped into an untitled, top-level BlogSection                                                                  |
+- **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
 
-Let's put those layout rules into practice. Here is how a standard markdown document translates into a blog layout:
+Here is how a standard markdown document maps to blog layout:
 
 ```markdown
-# My Awesome Blog Post
-
-This text becomes the Preamble (an untitled, top-level section).
+Intro content
 
 ## The Setup
 
@@ -182,9 +200,17 @@ Nested content belongs here.
 
 ## The Execution
 
-#### Note on performance:
+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:
@@ -192,7 +218,7 @@ Here is how the parser breaks the above document down into isolated React compon
 ##### Intro section
 
 ```markdown
-This text becomes an introductory, untitled section.
+Intro content
 ```
 
 ##### Section 1
@@ -202,7 +228,7 @@ This text becomes an introductory, untitled section.
 
 Some content goes here.
 
-#### Prerequisites
+### Prerequisites
 
 Nested content belongs here.
 ```
@@ -212,25 +238,47 @@ Nested content belongs here.
 ```markdown
 ## The Execution
 
-#### Note on performance:
+Some more content.
+
+### The Results
+
+Result content.
 ```
 
 ##### Section 3
 
 ```markdown
-## The Results
+# 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. The callout type is controlled by a prefix on the first word of the quote:
+
+| Syntax    | Callout Type | Example                      |
+| :-------- | :----------- | :--------------------------- |
+| `> text`  | Info         | `> This is an info callout.` |
+| `> ~text` | Warning      | `> ~This is a warning.`      |
+| `> !text` | Error        | `> !This is an error.`       |
+
+The prefix character is stripped from the rendered output — only the callout style changes.
+
 ## 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](https://blogkit.santhoshsiva.dev/).
 
-## License
+### License
 
-`blogkit-md` is open source software licensed under the [MIT license](https://github.com/san-siva/blogkit-md/blob/main/LICENSE).
+`blogkit-md` is open source software licensed under the [MIT license](https://github.com/san-siva/blogkit-md/blob/main/LICENSE).  
 Contributions are welcome!
 
-## About
+### About
 
 - **Author:** [Santhosh Siva](https://www.santhoshsiva.dev)
 - **License:** [MIT](https://github.com/san-siva/blogkit-md/blob/main/LICENSE)

package/app/page.tsx

@@ -14,11 +14,16 @@ const Page = async () => {
 		);
 	}
 
-	const { rendered } = result;
+	const { rendered, frontmatter } = result;
 
 	return (
 		<Blog>
-			{rendered.pageTitle && <BlogHeader title={[rendered.pageTitle]} desc={[]} />}
+			{frontmatter.title && (
+				<BlogHeader
+					title={[frontmatter.title]}
+					desc={frontmatter.description ? [frontmatter.description] : []}
+				/>
+			)}
 			<MarkdownSections rendered={rendered} />
 		</Blog>
 	);

package/components/BlogPost.tsx

@@ -38,14 +38,15 @@ const BlogPost = async ({ filePath, jsonLd }: BlogPostProperties) => {
 		);
 	}
 
-	const ast = parseMarkdown(content);
+	const { ast, frontmatter } = parseMarkdown(content);
 	const rendered = renderMarkdownAst(ast);
 
+	const title = frontmatter.title;
+	const desc = frontmatter.description;
+
 	return (
 		<Blog jsonLd={jsonLd}>
-			{rendered.pageTitle && (
-				<BlogHeader title={[rendered.pageTitle]} desc={[]} />
-			)}
+			{title && <BlogHeader title={[title]} desc={desc ? [desc] : []} />}
 			<MarkdownSections rendered={rendered} />
 		</Blog>
 	);

package/hooks/readMarkdownFile.ts

@@ -2,12 +2,13 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import '@/utils/devReloadTrigger';
+import type { Frontmatter } from '@/utils/parseMarkdown';
 import { parseMarkdown } from '@/utils/parseMarkdown';
 import type { RenderedMarkdown } from '@/utils/renderMarkdown';
 import { renderMarkdownAst } from '@/utils/renderMarkdown';
 
 type MarkdownFileResult =
-	| { success: true; rendered: RenderedMarkdown }
+	| { success: true; rendered: RenderedMarkdown; frontmatter: Frontmatter }
 	| { success: false; error: string };
 
 export const readMarkdownFile = async (
@@ -37,8 +38,8 @@ export const readMarkdownFile = async (
 		return { success: false, error: `File "${filePath}" is empty.` };
 	}
 
-	const ast = parseMarkdown(content);
+	const { ast, frontmatter } = parseMarkdown(content);
 	const rendered = renderMarkdownAst(ast);
 
-	return { success: true, rendered };
+	return { success: true, rendered, frontmatter };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@san-siva/blogkit-md",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Converts markdown files into JSX blog posts for Blogkit",
 	"main": "index.ts",
 	"exports": {
@@ -10,6 +10,7 @@
 		"dev": "tsx scripts/dev.ts",
 		"build": "MARKDOWN_FILE=data/test.md next build",
 		"start": "next start",
+		"test": "vitest run",
 		"lint": "eslint . --config eslint.config.ts",
 		"fix": "eslint . --config eslint.config.ts --fix"
 	},
@@ -19,11 +20,13 @@
 		"next": "^16.0.10",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
+		"remark-frontmatter": "^5.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"
+		"schema-dts": "^1.1.2",
+		"unified": "^11.0.5",
+		"yaml": "^2.8.2"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.0.0",
@@ -49,6 +52,7 @@
 		"prettier": "^3.0.0",
 		"tsx": "^4.0.0",
 		"typescript": "^5.0.0",
-		"typescript-eslint": "^8.0.0"
+		"typescript-eslint": "^8.0.0",
+		"vitest": "^4.1.0"
 	}
 }

package/utils/groupSections.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseMarkdown } from './parseMarkdown';
+import { groupSections } from './groupSections';
+
+const sections = (md: string) => groupSections(parseMarkdown(md).ast.children);
+
+describe('groupSections', () => {
+	describe('empty input', () => {
+		it('returns an empty array', () => {
+			expect(sections('')).toHaveLength(0);
+		});
+	});
+
+	describe('content with no headings', () => {
+		it('returns a single untitled section containing all nodes', () => {
+			const result = sections('some text\n\nmore text');
+			expect(result).toHaveLength(1);
+			expect(result[0].title).toBe('');
+			expect(result[0].nodes).toHaveLength(2);
+		});
+	});
+
+	describe('top-level sections', () => {
+		it('creates a section for H1', () => {
+			const result = sections('# Title');
+			expect(result).toHaveLength(1);
+			expect(result[0].title).toBe('Title');
+			expect(result[0].headingLevel).toBe(1);
+		});
+
+		it('creates a section for H2', () => {
+			const result = sections('## Section');
+			expect(result).toHaveLength(1);
+			expect(result[0].title).toBe('Section');
+			expect(result[0].headingLevel).toBe(2);
+		});
+
+		it('creates multiple sections for sequential H2s', () => {
+			const result = sections('## One\n\n## Two\n\n## Three');
+			expect(result).toHaveLength(3);
+			expect(result.map(s => s.title)).toEqual(['One', 'Two', 'Three']);
+		});
+
+		it('groups content nodes under their section', () => {
+			const result = sections('## Section\n\nsome text\n\nmore text');
+			expect(result).toHaveLength(1);
+			expect(result[0].nodes).toHaveLength(2);
+		});
+	});
+
+	describe('intro content before headings', () => {
+		it('returns an untitled intro section followed by headed sections', () => {
+			const result = sections('intro text\n\n## Section');
+			expect(result).toHaveLength(2);
+			expect(result[0].title).toBe('');
+			expect(result[0].nodes).toHaveLength(1);
+			expect(result[1].title).toBe('Section');
+		});
+	});
+
+	describe('nested sections (H3)', () => {
+		it('nests H3 under a preceding H2', () => {
+			const result = sections('## Parent\n\n### Child');
+			expect(result).toHaveLength(1);
+			expect(result[0].subsections).toHaveLength(1);
+			expect(result[0].subsections[0].title).toBe('Child');
+		});
+
+		it('promotes H3 to top-level when no parent section exists', () => {
+			const result = sections('### Orphan');
+			expect(result).toHaveLength(1);
+			expect(result[0].title).toBe('Orphan');
+		});
+
+		it('creates multiple subsections under one parent', () => {
+			const result = sections('## Parent\n\n### A\n\n### B');
+			expect(result).toHaveLength(1);
+			expect(result[0].subsections.map(s => s.title)).toEqual(['A', 'B']);
+		});
+	});
+
+	describe('deeper headings (H4+)', () => {
+		it('nests H4 as a subsection of H2', () => {
+			const result = sections('## Section\n\n#### Note');
+			expect(result[0].subsections).toHaveLength(1);
+			expect(result[0].subsections[0].headingLevel).toBe(4);
+		});
+
+		it('nests H6 inside H5 inside H2', () => {
+			const result = sections('## Section\n\n##### Five\n\n###### Six');
+			const h5 = result[0].subsections[0];
+			expect(h5.headingLevel).toBe(5);
+			expect(h5.subsections[0].headingLevel).toBe(6);
+		});
+	});
+});

package/utils/groupSections.ts

@@ -4,111 +4,67 @@ import { extractText } from './extractText';
 
 export type Section = {
 	title: string;
+	headingLevel: number;
 	nodes: RootContent[];
 	subsections: Section[];
+	previousSection?: 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;
-		}
+const consumeNode = (
+	nodes: RootContent[],
+	index: number,
+	sections: Section[],
+	section: Section
+): Section[] => {
+	const node = nodes.at(index);
+	if (!node) {
+		return sections;
+	}
 
-		if (currentSubsection) {
-			currentSubsection.nodes.push(node);
-			continue;
-		}
+	const isHeading = node.type === 'heading';
+	if (!isHeading) {
+		section.nodes.push(node);
+		return consumeNode(nodes, index + 1, sections, section);
+	}
 
-		if (currentSection) {
-			currentSection.nodes.push(node);
-			continue;
-		}
+	const headingLevel = node.depth;
+	const isIncrementingHeading = headingLevel > section.headingLevel;
+	if (isIncrementingHeading) {
+		const subsection: Section = {
+			title: extractText(node.children),
+			headingLevel,
+			nodes: [],
+			subsections: [],
+			previousSection: section,
+		};
+		section.subsections.push(subsection);
+		return consumeNode(nodes, index + 1, sections, subsection);
+	}
 
-		if (afterH1) {
-			textBeforeFirstSection.push(node);
-		}
+	if (!section.previousSection) {
+		const subSection: Section = {
+			title: extractText(node.children),
+			headingLevel,
+			nodes: [],
+			subsections: [],
+			previousSection: undefined,
+		};
+		sections.push(subSection);
+		return consumeNode(nodes, index + 1, sections, subSection);
 	}
 
-	return { pageTitle, beforeFirstHeading, textBeforeFirstSection, sections };
+	return consumeNode(nodes, index, sections, section.previousSection);
+};
+
+export const groupSections = (nodes: RootContent[]): Section[] => {
+	const initialSection: Section = {
+		title: '',
+		headingLevel: Infinity,
+		nodes: [],
+		subsections: [],
+		previousSection: undefined,
+	};
+	const sections: Section[] = [initialSection];
+	consumeNode(nodes, 0, sections, initialSection);
+	return sections.filter(s => s.title !== '' || s.nodes.length > 0);
 };

package/utils/parseMarkdown.ts

@@ -1,9 +1,35 @@
-import type { Root } from 'mdast';
+import type { Root, Yaml } from 'mdast';
+import remarkFrontmatter from 'remark-frontmatter';
 import remarkGfm from 'remark-gfm';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
+import { parse as parseYaml } from 'yaml';
 
-export const parseMarkdown = (content: string): Root => {
-	const processor = unified().use(remarkParse).use(remarkGfm);
-	return processor.parse(content) as Root;
+export type Frontmatter = {
+	title?: string;
+	description?: string;
+};
+
+export type ParseResult = {
+	ast: Root;
+	frontmatter: Frontmatter;
+};
+
+export const parseMarkdown = (content: string): ParseResult => {
+	const processor = unified().use(remarkParse).use(remarkGfm).use(remarkFrontmatter, ['yaml']);
+	const ast = processor.parse(content) as Root;
+
+	let frontmatter: Frontmatter = {};
+
+	if (ast.children[0]?.type === 'yaml') {
+		const raw = (ast.children[0] as Yaml).value;
+		const parsed = parseYaml(raw) as Record<string, unknown>;
+		frontmatter = {
+			title: typeof parsed.title === 'string' ? parsed.title : undefined,
+			description: typeof parsed.description === 'string' ? parsed.description : undefined,
+		};
+		ast.children.shift();
+	}
+
+	return { ast, frontmatter };
 };

package/utils/renderMarkdown.tsx

@@ -1,6 +1,12 @@
 import React from 'react';
 
-import { BlogSection, Callout, CodeBlock, Mermaid, Table } from '@san-siva/blogkit';
+import {
+	BlogSection,
+	Callout,
+	CodeBlock,
+	Mermaid,
+	Table,
+} from '@san-siva/blogkit';
 import type { Root, RootContent } from 'mdast';
 
 import type { Section } from './groupSections';
@@ -9,21 +15,34 @@ 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 {
+function renderNode({
+	node,
+	key,
+	nextNode,
+	inList = false,
+	inCallout = false,
+}: {
+	node: RootContent;
+	key: number;
+	nextNode?: RootContent;
+	inList?: boolean;
+	inCallout?: boolean;
+}): 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']
+
+			const isFollowedByParagraph = nextNode?.type === 'paragraph';
+			const isLastInCallout = !nextNode && inCallout;
+
+			const marginClass = isFollowedByParagraph
+				? styles['margin-bottom--1']
+				: isLastInCallout
+					? undefined
 					: styles['margin-bottom--2'];
+
 			return (
 				<p key={key} className={marginClass}>
 					{renderPhrasingContent(node.children)}
@@ -84,10 +103,52 @@ function renderNode(
 		}
 		case 'blockquote': {
 			const children = node.children as RootContent[];
+			let calloutType: 'info' | 'warning' | 'error' = 'info';
+			let strippedChildren = children;
+
+			const firstChild = children[0];
+			if (firstChild?.type === 'paragraph') {
+				const firstInline = firstChild.children[0];
+				if (firstInline?.type === 'text') {
+					if (firstInline.value.startsWith('!')) {
+						calloutType = 'error';
+						const trimmed = firstInline.value.slice(1).trimStart();
+						strippedChildren = [
+							{
+								...firstChild,
+								children: [
+									{ ...firstInline, value: trimmed },
+									...firstChild.children.slice(1),
+								],
+							},
+							...children.slice(1),
+						];
+					} else if (firstInline.value.startsWith('~')) {
+						calloutType = 'warning';
+						const trimmed = firstInline.value.slice(1).trimStart();
+						strippedChildren = [
+							{
+								...firstChild,
+								children: [
+									{ ...firstInline, value: trimmed },
+									...firstChild.children.slice(1),
+								],
+							},
+							...children.slice(1),
+						];
+					}
+				}
+			}
+
 			return (
-				<Callout key={key} type="info" hasMarginUp hasMarginDown>
-					{children.map((child, index) =>
-						renderNode(child, index, children[index + 1])
+				<Callout key={key} type={calloutType} hasMarginUp hasMarginDown>
+					{strippedChildren.map((child, index) =>
+						renderNode({
+							node: child,
+							key: index,
+							nextNode: strippedChildren[index + 1],
+							inCallout: true,
+						})
 					)}
 				</Callout>
 			);
@@ -95,11 +156,15 @@ function renderNode(
 		case 'list': {
 			const Tag = node.ordered ? 'ol' : 'ul';
 			return (
-				<Tag key={key}>
+				<Tag key={key} className={styles['margin-bottom--2']}>
 					{node.children.map((item, index) => (
 						<li key={index}>
 							{item.children.map((child, index) =>
-								renderNode(child as RootContent, index, undefined, true)
+								renderNode({
+									node: child as RootContent,
+									key: index,
+									inList: true,
+								})
 							)}
 						</li>
 					))}
@@ -113,12 +178,14 @@ function renderNode(
 }
 
 function renderNodes(nodes: RootContent[]): React.ReactNode[] {
-	return nodes.map((node, index) => renderNode(node, index, nodes[index + 1]));
+	return nodes.map((node, index) =>
+		renderNode({ node, key: index, nextNode: nodes[index + 1] })
+	);
 }
 
-function renderSection(section: Section, key: number): React.ReactNode {
+function renderSection(section: Section, key = -1): React.ReactNode {
 	return (
-		<BlogSection key={key} title={section.title}>
+		<BlogSection key={key} title={section?.title ?? ''}>
 			{renderNodes(section.nodes)}
 			{section.subsections.map((subsection, index) =>
 				renderSection(subsection, index)
@@ -128,21 +195,13 @@ function renderSection(section: Section, key: number): React.ReactNode {
 }
 
 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);
-
+	const grouped = groupSections(ast.children);
 	return {
-		pageTitle,
-		beforeFirstHeading: renderNodes(beforeFirstHeading),
-		textBeforeFirstSection: renderNodes(textBeforeFirstSection),
-		sections: sections.map((section, index) => renderSection(section, index)),
+		sections: grouped.map((section, index) => renderSection(section, index)),
 	};
 };
 
@@ -150,14 +209,4 @@ 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}
-	</>
-);
+}): React.ReactNode => <>{rendered.sections}</>;

package/website/package-lock.json

@@ -25,18 +25,20 @@
 		},
 		"..": {
 			"name": "@san-siva/blogkit-md",
-			"version": "0.1.0",
+			"version": "0.1.1",
 			"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-frontmatter": "^5.0.0",
 				"remark-gfm": "^4.0.1",
 				"remark-parse": "^11.0.0",
 				"sass": "^1.95.1",
 				"schema-dts": "^1.1.2",
-				"unified": "^11.0.5"
+				"unified": "^11.0.5",
+				"yaml": "^2.8.2"
 			},
 			"devDependencies": {
 				"@eslint/js": "^9.0.0",
@@ -62,7 +64,8 @@
 				"prettier": "^3.0.0",
 				"tsx": "^4.0.0",
 				"typescript": "^5.0.0",
-				"typescript-eslint": "^8.0.0"
+				"typescript-eslint": "^8.0.0",
+				"vitest": "^4.1.0"
 			}
 		},
 		"node_modules/@babel/runtime": {