@san-siva/blogkit-md 0.1.0

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+	"printWidth": 80,
+	"tabWidth": 2,
+	"singleQuote": true,
+	"trailingComma": "es5",
+	"useTabs": true,
+	"arrowParens": "avoid",
+	"semi": true
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santhosh Siva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# blogkit-md
+
+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.
+
+## Getting started
+
+```bash
+git clone https://github.com/san-siva/blogkit-md.git
+npm install
+```
+
+### Dev server
+
+```bash
+npm run dev                          # uses data/test.md by default
+npm run dev -- --file=data/my-post.md  # specify a markdown file
+```
+
+The dev server watches the markdown file for changes and auto-reloads the browser via HMR.
+
+### Build
+
+```bash
+npm run build
+npm run start
+```
+
+### Lint
+
+```bash
+npm run lint   # check
+npm run fix    # auto-fix
+```
+
+## Using BlogPost in your own Next.js app
+
+`blogkit-md` exposes a `BlogPost` server component you can drop into any Next.js project.
+
+### Install
+
+```bash
+npm install @san-siva/blogkit-md
+```
+
+Or as a local package:
+
+```json
+"@san-siva/blogkit-md": "file:../blogkit-md"
+```
+
+Add it to `transpilePackages` in your `next.config.ts`:
+
+```ts
+const nextConfig = {
+	transpilePackages: ['@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.        |
+
+## 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 |
+
+## 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.
+
+<mark>Instead of building just another plain document viewer, intentional design liberties have been taken to render markdown as **beautiful, engaging blog posts**.</mark>
+
+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](https://github.com/san-siva/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**. Each heading level acts as a layout trigger, directly controlling how `BlogSection` components are generated, nested, or promoted.
+
+| 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.                                     |
+
+> Standard content—such as paragraphs, lists, and code blocks—automatically flows into the most recently opened section or subsection.
+
+### Special Layout Rules
+
+Because `blogkit-md` is optimized for blog readability, it includes smart fallbacks to ensure your layout looks great even in edge cases:
+
+| 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                                                                  |
+
+### Visualizing the Structure
+
+Let's put those layout rules into practice. Here is how a standard markdown document translates into a blog layout:
+
+```markdown
+# My Awesome Blog Post
+
+This text becomes the Preamble (an untitled, top-level section).
+
+## The Setup
+
+Some content goes here.
+
+### Prerequisites
+
+Nested content belongs here.
+
+## The Execution
+
+#### Note on performance:
+
+### The Results
+```
+
+Here is how the parser breaks the above document down into isolated React components:
+
+##### Intro section
+
+```markdown
+This text becomes an introductory, untitled section.
+```
+
+##### Section 1
+
+```markdown
+## The Setup
+
+Some content goes here.
+
+#### Prerequisites
+
+Nested content belongs here.
+```
+
+##### Section 2
+
+```markdown
+## The Execution
+
+#### Note on performance:
+```
+
+##### Section 3
+
+```markdown
+## The Results
+```
+
+## 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
+
+`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
+
+- **Author:** [Santhosh Siva](https://www.santhoshsiva.dev)
+- **License:** [MIT](https://github.com/san-siva/blogkit-md/blob/main/LICENSE)

package/app/layout.tsx

@@ -0,0 +1,44 @@
+import type { Metadata } from 'next';
+import { JetBrains_Mono, Montserrat, Rubik } from 'next/font/google';
+
+import '@san-siva/stylekit/styles/globals.scss';
+import '@san-siva/blogkit/styles.css';
+import styles from '@san-siva/stylekit/styles/index.module.scss';
+
+const montserrat = Montserrat({
+	subsets: ['latin'] as const,
+	weight: ['400', '500', '600', '700', '800'] as const,
+	style: ['normal', 'italic'] as const,
+	variable: '--font-montserrat',
+});
+
+const rubik = Rubik({
+	subsets: ['latin'] as const,
+	weight: ['300', '400', '500', '600', '700', '800', '900'] as const,
+	style: ['normal', 'italic'] as const,
+	variable: '--font-rubik',
+});
+
+const jetbrainsMono = JetBrains_Mono({
+	subsets: ['latin'] as const,
+	weight: ['400', '500', '600', '700'] as const,
+	style: ['normal', 'italic'] as const,
+	variable: '--font-jetbrains-mono',
+});
+
+export const metadata: Metadata = {
+	title: 'Blogkit MD',
+	description: 'Markdown to JSX blog post renderer',
+};
+
+const RootLayout = ({ children }: { children: React.ReactNode }) => (
+	<html lang="en">
+		<body
+			className={`${montserrat.variable} ${rubik.variable} ${jetbrainsMono.variable}`}
+		>
+			<div className={`${styles.page}`}>{children}</div>
+		</body>
+	</html>
+);
+
+export default RootLayout;

package/app/page.tsx

@@ -0,0 +1,27 @@
+import { Blog, BlogHeader, Callout } from '@san-siva/blogkit';
+
+import { readMarkdownFile } from '@/hooks/readMarkdownFile';
+import { MarkdownSections } from '@/utils/renderMarkdown';
+
+const Page = async () => {
+	const result = await readMarkdownFile(process.env.MARKDOWN_FILE);
+
+	if (!result.success) {
+		return (
+			<Blog>
+				<Callout type="warning">{result.error}</Callout>
+			</Blog>
+		);
+	}
+
+	const { rendered } = result;
+
+	return (
+		<Blog>
+			{rendered.pageTitle && <BlogHeader title={[rendered.pageTitle]} desc={[]} />}
+			<MarkdownSections rendered={rendered} />
+		</Blog>
+	);
+};
+
+export default Page;

package/components/BlogPost.tsx

@@ -0,0 +1,54 @@
+import { Blog, BlogHeader, Callout } from '@san-siva/blogkit';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { Thing, WithContext } from 'schema-dts';
+
+import { parseMarkdown } from '../utils/parseMarkdown';
+import { MarkdownSections, renderMarkdownAst } from '../utils/renderMarkdown';
+
+type BlogPostProperties = {
+	filePath: string;
+	jsonLd?: WithContext<Thing>;
+};
+
+const BlogPost = async ({ filePath, jsonLd }: BlogPostProperties) => {
+	const absolutePath = path.isAbsolute(filePath)
+		? filePath
+		: path.join(process.cwd(), filePath);
+
+	let content: string;
+	try {
+		content = await readFile(absolutePath, 'utf8');
+	} catch {
+		return (
+			<Blog>
+				<Callout type="warning">
+					Could not read file: &quot;{filePath}&quot;. Make sure the path is
+					correct and the file exists.
+				</Callout>
+			</Blog>
+		);
+	}
+
+	if (!content.trim()) {
+		return (
+			<Blog>
+				<Callout type="warning">File &quot;{filePath}&quot; is empty.</Callout>
+			</Blog>
+		);
+	}
+
+	const ast = parseMarkdown(content);
+	const rendered = renderMarkdownAst(ast);
+
+	return (
+		<Blog jsonLd={jsonLd}>
+			{rendered.pageTitle && (
+				<BlogHeader title={[rendered.pageTitle]} desc={[]} />
+			)}
+			<MarkdownSections rendered={rendered} />
+		</Blog>
+	);
+};
+
+export default BlogPost;

package/eslint/common.config.ts

@@ -0,0 +1,29 @@
+import tseslint, { configs as tseslintConfigs } from 'typescript-eslint';
+
+import {
+	defaultExtends,
+	defaultPlugins,
+	defaultRules,
+	defaultSettings,
+	languageOptions,
+	testFiles,
+} from './utilities';
+
+export default tseslint.config(
+	{
+		ignores: ['node_modules/**', 'dist/**', '.next/**', 'next-env.d.ts'],
+	},
+	{
+		files: ['**/*.ts', '**/*.js'],
+		ignores: testFiles,
+		plugins: defaultPlugins,
+		extends: defaultExtends,
+		rules: defaultRules,
+		settings: defaultSettings,
+		languageOptions,
+	},
+	{
+		files: ['eslint.config.ts', 'eslint/**/*.ts'],
+		extends: [tseslintConfigs.disableTypeChecked],
+	}
+);

package/eslint/react.config.ts

@@ -0,0 +1,20 @@
+import tseslint from 'typescript-eslint';
+
+import {
+	languageOptions,
+	reactExtends,
+	reactPlugins,
+	reactRules,
+	reactSettings,
+	testFiles,
+} from './utilities';
+
+export default tseslint.config({
+	files: ['**/*.tsx', '**/*.jsx'],
+	ignores: testFiles,
+	plugins: reactPlugins,
+	extends: reactExtends,
+	rules: reactRules,
+	settings: reactSettings,
+	languageOptions,
+});

package/eslint/utilities.ts

@@ -0,0 +1,236 @@
+import eslint from '@eslint/js';
+import type { Linter } from 'eslint';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import importPlugin from 'eslint-plugin-import';
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+import { configs as noAwaitInPromiseConfigs } from 'eslint-plugin-no-await-in-promise';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import simpleImportSort from 'eslint-plugin-simple-import-sort';
+import eslintPluginUnicorn from 'eslint-plugin-unicorn';
+import { configs as tseslintConfigs } from 'typescript-eslint';
+
+export const defaultExtends = [
+	eslint.configs.recommended,
+	eslintPluginUnicorn.configs.recommended,
+	eslintConfigPrettier,
+	noAwaitInPromiseConfigs.recommended,
+	...tseslintConfigs.recommended,
+	importPlugin.flatConfigs.recommended,
+	importPlugin.flatConfigs.typescript,
+];
+
+export const defaultPlugins = {
+	'simple-import-sort': simpleImportSort,
+};
+
+export const tsRules: Linter.RulesRecord = {
+	'@typescript-eslint/no-explicit-any': 1,
+	'@typescript-eslint/no-floating-promises': 2,
+	'@typescript-eslint/no-unused-vars': 1,
+	'@typescript-eslint/naming-convention': [
+		1,
+		{
+			selector: 'import',
+			format: ['camelCase', 'PascalCase', 'snake_case', 'UPPER_CASE'],
+		},
+		{
+			selector: 'enumMember',
+			format: ['PascalCase'],
+		},
+		{
+			selector: 'default',
+			format: ['camelCase'],
+		},
+		{
+			selector: 'variable',
+			format: ['camelCase', 'UPPER_CASE', 'PascalCase'],
+		},
+		{
+			selector: 'variable',
+			modifiers: ['destructured'],
+			format: ['camelCase', 'snake_case', 'UPPER_CASE', 'PascalCase'],
+		},
+		{
+			selector: 'function',
+			format: ['camelCase', 'PascalCase'],
+		},
+		{
+			selector: 'parameter',
+			format: [],
+		},
+		{
+			selector: 'memberLike',
+			modifiers: ['private'],
+			format: ['camelCase'],
+			leadingUnderscore: 'require',
+		},
+		{
+			selector: 'typeLike',
+			format: ['PascalCase'],
+		},
+		{ selector: 'property', format: [] },
+		{
+			selector: 'method',
+			format: ['PascalCase', 'camelCase', 'UPPER_CASE'],
+			leadingUnderscore: 'allowDouble',
+		},
+	],
+	'@typescript-eslint/no-use-before-define': 2,
+	'@typescript-eslint/no-unused-expressions': [
+		'error',
+		{
+			allowShortCircuit: true,
+			allowTernary: true,
+			allowTaggedTemplates: true,
+		},
+	],
+};
+
+export const defaultRules: Linter.RulesRecord = {
+	...tsRules,
+	'unicorn/filename-case': [
+		'error',
+		{
+			cases: {
+				camelCase: true,
+				kebabCase: true,
+				pascalCase: true,
+			},
+		},
+	],
+	'unicorn/prevent-abbreviations': [1, { allowList: { dev: true } }],
+	'unicorn/no-array-reduce': [1],
+	'unicorn/catch-error-name': [0],
+	'unicorn/no-for-loop': [1],
+	'unicorn/no-null': [0],
+	'unicorn/prefer-string-raw': [1],
+	'unicorn/prefer-string-slice': [1],
+	'unicorn/no-negated-condition': [1],
+	'unicorn/no-array-for-each': [0],
+	'unicorn/no-array-callback-reference': [0],
+	'unicorn/no-object-as-default-parameter': [1],
+	'unicorn/prefer-math-min-max': [1],
+	'unicorn/no-process-exit': [1],
+	'unicorn/prefer-top-level-await': [1],
+	'unicorn/prefer-number-properties': [1],
+	'unicorn/consistent-function-scoping': [1],
+	'arrow-body-style': [1, 'as-needed'],
+	camelcase: 0,
+	'default-param-last': 0,
+	'import/order': 0,
+	'simple-import-sort/imports': [
+		1,
+		{
+			groups: [
+				['^react$', '^react-.*'],
+				['next', 'next-.*'],
+				[String.raw`^@?\w`],
+				[String.raw`^\.\.(?!/?$)`, String.raw`^\.\./?$`],
+				[
+					String.raw`^\./(?=.*/)(?!/?$)`,
+					String.raw`^\.(?!/?$)`,
+					String.raw`^\./?$`,
+				],
+				[String.raw`^.+\.s?css$`],
+			],
+		},
+	],
+	'simple-import-sort/exports': 1,
+	'import/no-extraneous-dependencies': 0,
+	'import/extensions': 0,
+	'import/no-cycle': [2, { ignoreExternal: true }],
+	'import/no-unresolved': 0,
+	'import/prefer-default-export': 0,
+	'max-len': 0,
+	'no-console': 0,
+	'no-delete-var': 2,
+	'no-shadow': 0,
+	'no-underscore-dangle': [2, { allow: ['_id'] }],
+	'no-unused-expressions': 2,
+	'no-unused-labels': 2,
+	'no-use-before-define': 0,
+	semi: 1,
+	quotes: [
+		1,
+		'single',
+		{
+			avoidEscape: true,
+			allowTemplateLiterals: true,
+		},
+	],
+};
+
+export const languageOptions = {
+	ecmaVersion: 2022 as const,
+	parserOptions: {
+		projectService: true,
+		defaultProject: '../tsconfig.json',
+		tsconfigRootDir: import.meta.dirname,
+	},
+};
+
+export const testFiles = [
+	'**/*.test.ts',
+	'**/*.test.tsx',
+	'**/*.test.js',
+	'**/*.test.jsx',
+	'**/*.spec.ts',
+	'**/*.spec.tsx',
+	'**/*.spec.js',
+	'**/*.spec.jsx',
+];
+
+export const defaultSettings = {
+	'import/resolver': {
+		typescript: {
+			project: '../tsconfig.json',
+		},
+	},
+};
+
+export const reactPlugins = {
+	...defaultPlugins,
+	react,
+	'react-hooks': reactHooks,
+};
+
+export const reactSettings = {
+	...defaultSettings,
+	react: {
+		version: 'detect',
+		pragma: 'React',
+		fragment: 'Fragment',
+	},
+};
+
+export const reactRules: Linter.RulesRecord = {
+	...defaultRules,
+	'react/jsx-uses-react': 0,
+	'react/react-in-jsx-scope': 0,
+	'react-hooks/rules-of-hooks': 2,
+	'react-hooks/exhaustive-deps': 1,
+	'eol-last': ['error', 'always'],
+	'jsx-a11y/alt-text': 0,
+	'jsx-a11y/click-events-have-key-events': 0,
+	'jsx-a11y/control-has-associated-label': 0,
+	'jsx-a11y/no-noninteractive-element-interactions': 0,
+	'jsx-a11y/no-static-element-interactions': 0,
+	'jsx-a11y/label-has-associated-control': 0,
+	'react/jsx-filename-extension': [1, { extensions: ['.tsx'] }],
+	'react/jsx-props-no-spreading': 0,
+	'react/no-unstable-nested-components': ['error', { allowAsProps: true }],
+	'react/prop-types': 0,
+	'react/require-default-props': 0,
+	'react/function-component-definition': [
+		2,
+		{ namedComponents: 'arrow-function' },
+	],
+	'react/no-unknown-property': 1,
+};
+
+export const reactExtends = [
+	react.configs.flat.recommended,
+	jsxA11y.flatConfigs?.recommended,
+	...defaultExtends,
+];

package/eslint.config.ts

@@ -0,0 +1,8 @@
+import common from './eslint/common.config';
+import react from './eslint/react.config';
+
+export default [
+	{ ignores: ['website/**'] },
+	...common,
+	...react,
+];