@san-siva/blogkit-md 0.2.9 → 0.3.2

package/README.md

@@ -79,13 +79,12 @@ description: A short description shown below the title
 | 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           | `> text` — renders as info callout             |
-| Blockquote (warning) | `> ~text` — renders as warning callout         |
-| Blockquote (error)   | `> !text` — renders as error callout           |
+| Blockquote / Callout | `> text` or `> [!TYPE]` — renders as callout   |
 
 ## Philosophy
 
@@ -215,15 +214,23 @@ Result content.
 
 ### Callouts
 
-Blockquotes are rendered as styled callout banners. The callout type is controlled by a prefix on the first word of the quote.
+Blockquotes are rendered as styled callout banners. Plain blockquotes render as info callouts. Use GitHub-style alert syntax to control the type:
 
-> This is an info callout. Use `> text` for general information.
+| Syntax         | Callout type |
+| :------------- | :----------- |
+| `[!NOTE]`      | info         |
+| `[!TIP]`       | info         |
+| `[!IMPORTANT]` | info         |
+| `[!WARNING]`   | warning      |
+| `[!CAUTION]`   | error        |
 
-> ~This is a warning callout. Use `> ~text` to flag caution.
-
-> !This is an error callout. Use `> !text` for errors or destructive actions.
+```markdown
+> [!WARNING]
+>
+> Do not clone this repository into system folders.
+```
 
-The prefix character is stripped from the rendered output — only the callout style changes.
+The `[!TYPE]` line is stripped from the rendered output.
 
 ## Want more customization?
 
@@ -238,3 +245,7 @@ Contributions are welcome!
 
 - **Author:** [Santhosh Siva](https://www.santhoshsiva.dev)
 - **License:** [MIT](https://github.com/san-siva/blogkit-md/blob/main/LICENSE)
+
+> [!WARNING]
+>
+> This project is in early development.

package/dist/index.js

@@ -29,6 +29,25 @@ import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { parse as parseYaml } from "yaml";
+
+// src/utils/extractText.ts
+var extractText = (nodes) => nodes.map((node) => {
+  if (node.type === "text") return node.value;
+  if ("children" in node)
+    return extractText(node.children);
+  return "";
+}).join("");
+
+// src/utils/parseMarkdown.ts
+var consumeH1Title = (ast, frontmatter) => {
+  var _a;
+  if (!frontmatter.title && ((_a = ast.children[0]) == null ? void 0 : _a.type) === "heading" && ast.children[0].depth === 1) {
+    const title = extractText(ast.children[0].children);
+    ast.children.shift();
+    return __spreadProps(__spreadValues({}, frontmatter), { title });
+  }
+  return frontmatter;
+};
 var parseMarkdown = (content) => {
   var _a, _b;
   const processor = unified().use(remarkParse).use(remarkGfm).use(remarkFrontmatter, ["yaml"]);
@@ -44,6 +63,7 @@ var parseMarkdown = (content) => {
     };
     ast.children.shift();
   }
+  frontmatter = consumeH1Title(ast, frontmatter);
   return { ast, frontmatter };
 };
 
@@ -51,19 +71,12 @@ var parseMarkdown = (content) => {
 import {
   BlogSection,
   Callout,
+  CheckList,
   CodeBlock,
   Mermaid,
   Table
 } from "@san-siva/blogkit";
 
-// src/utils/extractText.ts
-var extractText = (nodes) => nodes.map((node) => {
-  if (node.type === "text") return node.value;
-  if ("children" in node)
-    return extractText(node.children);
-  return "";
-}).join("");
-
 // src/utils/groupSections.ts
 var consumeNode = (nodes, index, sections, section) => {
   const node = nodes.at(index);
@@ -216,7 +229,8 @@ function renderNode({
   key,
   nextNode,
   inList = false,
-  inCallout = false
+  inCallout = false,
+  counters
 }) {
   var _a;
   switch (node.type) {
@@ -231,10 +245,11 @@ function renderNode({
     }
     case "code": {
       if (node.lang === "mermaid") {
+        const mermaidId = counters.mermaid++;
         return /* @__PURE__ */ jsx2(
           Mermaid,
           {
-            id: `mermaid-${key}`,
+            id: `mermaid-${mermaidId}`,
             code: node.value,
             hasMarginUp: true,
             hasMarginDown: true
@@ -286,30 +301,11 @@ function renderNode({
       if ((firstChild == null ? void 0 : firstChild.type) === "paragraph") {
         const firstInline = firstChild.children[0];
         if ((firstInline == null ? void 0 : firstInline.type) === "text") {
-          if (firstInline.value.startsWith("!")) {
-            calloutType = "error";
-            const trimmed = firstInline.value.slice(1).trimStart();
-            strippedChildren = [
-              __spreadProps(__spreadValues({}, firstChild), {
-                children: [
-                  __spreadProps(__spreadValues({}, 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 = [
-              __spreadProps(__spreadValues({}, firstChild), {
-                children: [
-                  __spreadProps(__spreadValues({}, firstInline), { value: trimmed }),
-                  ...firstChild.children.slice(1)
-                ]
-              }),
-              ...children.slice(1)
-            ];
+          const githubAlertMatch = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]$/i.exec(firstInline.value);
+          if (githubAlertMatch) {
+            const alertType = githubAlertMatch[1].toUpperCase();
+            calloutType = alertType === "WARNING" ? "warning" : alertType === "CAUTION" ? "error" : "info";
+            strippedChildren = children.slice(1);
           }
         }
       }
@@ -318,17 +314,30 @@ function renderNode({
           node: child,
           key: index,
           nextNode: strippedChildren[index + 1],
-          inCallout: true
+          inCallout: true,
+          counters
         })
       ) }, key);
     }
     case "list": {
+      const isTaskList = node.children.every((item) => item.checked !== null && item.checked !== void 0);
+      if (isTaskList) {
+        const items = node.children.map((item, index) => ({
+          id: String(index),
+          isChecked: item.checked === true,
+          children: item.children.map(
+            (child, childIndex) => renderNode({ node: child, key: childIndex, inList: true, counters })
+          )
+        }));
+        return /* @__PURE__ */ jsx2(CheckList, { items, hasMarginUp: true, hasMarginDown: true }, key);
+      }
       const Tag = node.ordered ? "ol" : "ul";
       return /* @__PURE__ */ jsx2(Tag, { className: styles2["margin-bottom--2"], children: node.children.map((item, index) => /* @__PURE__ */ jsx2("li", { children: item.children.map(
         (child, index2) => renderNode({
           node: child,
           key: index2,
-          inList: true
+          inList: true,
+          counters
         })
       ) }, index)) }, key);
     }
@@ -337,24 +346,25 @@ function renderNode({
     }
   }
 }
-function renderNodes(nodes) {
+function renderNodes(nodes, counters) {
   return nodes.map(
-    (node, index) => renderNode({ node, key: index, nextNode: nodes[index + 1] })
+    (node, index) => renderNode({ node, key: index, nextNode: nodes[index + 1], counters })
   );
 }
-function renderSection(section, key = -1) {
+function renderSection(section, counters, key = -1) {
   var _a;
   return /* @__PURE__ */ jsxs(BlogSection, { title: (_a = section == null ? void 0 : section.title) != null ? _a : "", children: [
-    renderNodes(section.nodes),
+    renderNodes(section.nodes, counters),
     section.subsections.map(
-      (subsection, index) => renderSection(subsection, index)
+      (subsection, index) => renderSection(subsection, counters, index)
     )
   ] }, key);
 }
 var renderMarkdownAst = (ast) => {
+  const counters = { mermaid: 0 };
   const grouped = groupSections(ast.children);
   return {
-    sections: grouped.map((section, index) => renderSection(section, index))
+    sections: grouped.map((section, index) => renderSection(section, counters, index))
   };
 };
 var MarkdownSections = ({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@san-siva/blogkit-md",
-	"version": "0.2.9",
+	"version": "0.3.2",
 	"description": "Converts markdown files into JSX blog posts for Blogkit",
 	"main": "./dist/index.js",
 	"exports": {
@@ -21,7 +21,7 @@
 		"fix": "eslint . --config eslint.config.ts --fix"
 	},
 	"dependencies": {
-		"@san-siva/blogkit": "^1.1.23",
+		"@san-siva/blogkit": "^1.1.26",
 		"@san-siva/stylekit": "^1.0.12",
 		"next": "^16.0.10",
 		"react": "^19.0.0",

package/src/utils/groupSections.test.ts

@@ -1,9 +1,15 @@
 import { describe, expect, it } from 'vitest';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import type { Root } from 'mdast';
 
-import { parseMarkdown } from './parseMarkdown';
 import { groupSections } from './groupSections';
 
-const sections = (md: string) => groupSections(parseMarkdown(md).ast.children);
+const sections = (md: string) => {
+	const ast = unified().use(remarkParse).use(remarkGfm).parse(md) as Root;
+	return groupSections(ast.children);
+};
 
 describe('groupSections', () => {
 	describe('empty input', () => {

package/src/utils/parseMarkdown.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseMarkdown } from './parseMarkdown';
+
+describe('parseMarkdown', () => {
+	describe('consumeH1Title', () => {
+		it('extracts a leading H1 as the title when no frontmatter title is set', () => {
+			const { frontmatter, ast } = parseMarkdown('# My Title\n\nSome content');
+			expect(frontmatter.title).toBe('My Title');
+		});
+
+		it('removes the H1 from the AST after extracting it as the title', () => {
+			const { ast } = parseMarkdown('# My Title\n\nSome content');
+			expect(ast.children[0]?.type).not.toBe('heading');
+		});
+
+		it('does not consume the H1 when frontmatter title is already set', () => {
+			const { frontmatter, ast } = parseMarkdown('---\ntitle: Frontmatter Title\n---\n\n# H1 Title');
+			expect(frontmatter.title).toBe('Frontmatter Title');
+			expect(ast.children[0]?.type).toBe('heading');
+		});
+
+		it('does not extract a title when the first heading is not H1', () => {
+			const { frontmatter } = parseMarkdown('## Section Title');
+			expect(frontmatter.title).toBeUndefined();
+		});
+
+		it('does not extract a title when H1 is not the first node', () => {
+			const { frontmatter, ast } = parseMarkdown('Some intro\n\n# Title');
+			expect(frontmatter.title).toBeUndefined();
+			expect(ast.children).toHaveLength(2);
+		});
+
+		it('handles inline formatting in the H1', () => {
+			const { frontmatter } = parseMarkdown('# My **Bold** Title');
+			expect(frontmatter.title).toBe('My Bold Title');
+		});
+	});
+});

package/src/utils/parseMarkdown.ts

@@ -1,10 +1,12 @@
-import type { Root, Yaml } from 'mdast';
+import type { Heading, 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';
 
+import { extractText } from './extractText';
+
 export type Frontmatter = {
 	title?: string;
 	description?: string;
@@ -15,6 +17,17 @@ export type ParseResult = {
 	frontmatter: Frontmatter;
 };
 
+// When a document has no frontmatter title, treat a leading H1 as the page title
+// and remove it from the AST so it isn't also rendered as a section.
+const consumeH1Title = (ast: Root, frontmatter: Frontmatter): Frontmatter => {
+	if (!frontmatter.title && ast.children[0]?.type === 'heading' && (ast.children[0] as Heading).depth === 1) {
+		const title = extractText((ast.children[0] as Heading).children);
+		ast.children.shift();
+		return { ...frontmatter, title };
+	}
+	return frontmatter;
+};
+
 export const parseMarkdown = (content: string): ParseResult => {
 	const processor = unified().use(remarkParse).use(remarkGfm).use(remarkFrontmatter, ['yaml']);
 	const ast = processor.parse(content) as Root;
@@ -32,5 +45,7 @@ export const parseMarkdown = (content: string): ParseResult => {
 		ast.children.shift();
 	}
 
+	frontmatter = consumeH1Title(ast, frontmatter);
+
 	return { ast, frontmatter };
 };

package/src/utils/renderMarkdown.tsx

@@ -3,6 +3,8 @@ import React from 'react';
 import {
 	BlogSection,
 	Callout,
+	CheckList,
+	type CheckListItem,
 	CodeBlock,
 	Mermaid,
 	Table,
@@ -15,18 +17,22 @@ import { renderPhrasingContent } from './renderPhrasingContent';
 
 import styles from '@san-siva/stylekit/styles/index.module.scss';
 
+type Counters = { mermaid: number };
+
 function renderNode({
 	node,
 	key,
 	nextNode,
 	inList = false,
 	inCallout = false,
+	counters,
 }: {
 	node: RootContent;
 	key: number;
 	nextNode?: RootContent;
 	inList?: boolean;
 	inCallout?: boolean;
+	counters: Counters;
 }): React.ReactNode {
 	switch (node.type) {
 		case 'paragraph': {
@@ -51,10 +57,11 @@ function renderNode({
 		}
 		case 'code': {
 			if (node.lang === 'mermaid') {
+				const mermaidId = counters.mermaid++;
 				return (
 					<Mermaid
 						key={key}
-						id={`mermaid-${key}`}
+						id={`mermaid-${mermaidId}`}
 						code={node.value}
 						hasMarginUp
 						hasMarginDown
@@ -110,32 +117,11 @@ function renderNode({
 			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),
-						];
+					const githubAlertMatch = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]$/i.exec(firstInline.value);
+					if (githubAlertMatch) {
+						const alertType = githubAlertMatch[1].toUpperCase();
+						calloutType = alertType === 'WARNING' ? 'warning' : alertType === 'CAUTION' ? 'error' : 'info';
+						strippedChildren = children.slice(1);
 					}
 				}
 			}
@@ -148,12 +134,24 @@ function renderNode({
 							key: index,
 							nextNode: strippedChildren[index + 1],
 							inCallout: true,
+							counters,
 						})
 					)}
 				</Callout>
 			);
 		}
 		case 'list': {
+			const isTaskList = node.children.every(item => item.checked !== null && item.checked !== undefined);
+			if (isTaskList) {
+				const items: CheckListItem[] = node.children.map((item, index) => ({
+					id: String(index),
+					isChecked: item.checked === true,
+					children: item.children.map((child, childIndex) =>
+						renderNode({ node: child as RootContent, key: childIndex, inList: true, counters })
+					),
+				}));
+				return <CheckList key={key} items={items} hasMarginUp hasMarginDown />;
+			}
 			const Tag = node.ordered ? 'ol' : 'ul';
 			return (
 				<Tag key={key} className={styles['margin-bottom--2']}>
@@ -164,6 +162,7 @@ function renderNode({
 									node: child as RootContent,
 									key: index,
 									inList: true,
+									counters,
 								})
 							)}
 						</li>
@@ -177,18 +176,18 @@ function renderNode({
 	}
 }
 
-function renderNodes(nodes: RootContent[]): React.ReactNode[] {
+function renderNodes(nodes: RootContent[], counters: Counters): React.ReactNode[] {
 	return nodes.map((node, index) =>
-		renderNode({ node, key: index, nextNode: nodes[index + 1] })
+		renderNode({ node, key: index, nextNode: nodes[index + 1], counters })
 	);
 }
 
-function renderSection(section: Section, key = -1): React.ReactNode {
+function renderSection(section: Section, counters: Counters, key = -1): React.ReactNode {
 	return (
 		<BlogSection key={key} title={section?.title ?? ''}>
-			{renderNodes(section.nodes)}
+			{renderNodes(section.nodes, counters)}
 			{section.subsections.map((subsection, index) =>
-				renderSection(subsection, index)
+				renderSection(subsection, counters, index)
 			)}
 		</BlogSection>
 	);
@@ -199,9 +198,10 @@ export type RenderedMarkdown = {
 };
 
 export const renderMarkdownAst = (ast: Root): RenderedMarkdown => {
+	const counters: Counters = { mermaid: 0 };
 	const grouped = groupSections(ast.children);
 	return {
-		sections: grouped.map((section, index) => renderSection(section, index)),
+		sections: grouped.map((section, index) => renderSection(section, counters, index)),
 	};
 };