@aaronellington/vite-plugin-inkwell 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Ellington
+
+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,48 @@
+# @aaronellington/vite-plugin-inkwell
+
+[![CI](https://github.com/aaronellington/vite-plugin-inkwell/actions/workflows/ci.yml/badge.svg)](https://github.com/aaronellington/vite-plugin-inkwell/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@aaronellington/vite-plugin-inkwell)](https://www.npmjs.com/package/@aaronellington/vite-plugin-inkwell)
+[![license](https://img.shields.io/npm/l/@aaronellington/vite-plugin-inkwell)](./LICENSE)
+
+A Vite plugin that transforms directories of markdown files into typed, lazy-loaded content collections with frontmatter parsing, asset hashing, and HMR.
+
+## Setup
+
+Install the plugin:
+
+```bash
+npm install @aaronellington/vite-plugin-inkwell
+```
+
+Register it in `vite.config.ts`:
+
+```typescript
+import { inkwell } from "@aaronellington/vite-plugin-inkwell";
+
+export default defineConfig({
+	plugins: [inkwell()],
+});
+```
+
+## Usage
+
+Import a content directory using the `inkwell:` prefix. The path resolves relative to the importing file:
+
+```typescript
+import collection from "inkwell:./content";
+```
+
+Multiple collections are supported:
+
+```typescript
+import blog from "inkwell:./blog";
+import tutorials from "inkwell:./tutorials";
+```
+
+## Draft Mode
+
+Posts with `draft: true` are excluded from production builds but included during development. Override with the `includeDrafts` option.
+
+## HMR
+
+Editing or adding markdown files triggers a full page reload in development. The plugin watches all imported content directories automatically.

package/content.d.ts

@@ -0,0 +1,6 @@
+import type { ContentItem } from "./src/types.ts"
+
+declare module "inkwell:*" {
+	const collection: ContentItem[]
+	export default collection
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@aaronellington/vite-plugin-inkwell",
+	"version": "0.0.1",
+	"description": "A Vite plugin that transforms directories of markdown files into typed, lazy-loaded content collections with frontmatter parsing, asset hashing, and HMR.",
+	"license": "MIT",
+	"author": "Aaron Ellington",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/aaronellington/vite-plugin-inkwell.git"
+	},
+	"homepage": "https://github.com/aaronellington/vite-plugin-inkwell#readme",
+	"bugs": "https://github.com/aaronellington/vite-plugin-inkwell/issues",
+	"keywords": [
+		"vite",
+		"vite-plugin",
+		"markdown",
+		"content",
+		"frontmatter",
+		"blog"
+	],
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src/*.ts",
+		"content.d.ts"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"dependencies": {
+		"gray-matter": "^4.0.3",
+		"marked": "^17.0.0",
+		"smol-toml": "^1.3.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.5",
+		"@playwright/test": "^1.52.0",
+		"@types/node": "^25.3.3",
+		"prettier": "^3.8.1",
+		"sirv": "^3.0.2",
+		"typescript": "^5.9.3",
+		"vite": "^7.1.2"
+	},
+	"peerDependencies": {
+		"vite": "^7.0.0"
+	},
+	"scripts": {
+		"lint": "tsc -b && biome check . && prettier --check .",
+		"fix": "biome check --write . && prettier --write .",
+		"test": "playwright test",
+		"test:install": "playwright install chromium"
+	}
+}

package/src/assets.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs"
+import path from "node:path"
+import type { AssetReference } from "./types.ts"
+
+const ASSET_REGEX =
+	/(?:src|href|poster)=["'](?!(?:https?:|data:|#|\/\/|\/))([^"']+)["']/g
+
+export function extractAssetReferences(
+	html: string,
+	mdFilePath: string,
+): AssetReference[] {
+	const mdDir = path.dirname(mdFilePath)
+	const assets: AssetReference[] = []
+	const seen = new Set<string>()
+
+	ASSET_REGEX.lastIndex = 0
+	for (
+		let match = ASSET_REGEX.exec(html);
+		match !== null;
+		match = ASSET_REGEX.exec(html)
+	) {
+		const originalPath = match[1]
+		if (seen.has(originalPath)) continue
+		seen.add(originalPath)
+
+		const absolutePath = path.resolve(mdDir, originalPath)
+
+		if (!fs.existsSync(absolutePath)) {
+			throw new Error(
+				`Missing asset referenced in ${mdFilePath}: "${originalPath}"\n` +
+					`Resolved to: ${absolutePath}`,
+			)
+		}
+
+		const placeholderToken = `__CONTENT_ASSET_${assets.length}__`
+		assets.push({ absolutePath, originalPath, placeholderToken })
+	}
+
+	return assets
+}
+
+export function replaceAssetsWithPlaceholders(
+	html: string,
+	assets: AssetReference[],
+): string {
+	let result = html
+	for (const asset of assets) {
+		result = result.split(asset.originalPath).join(asset.placeholderToken)
+	}
+	return result
+}
+
+export function generateSlugModuleCode(
+	html: string,
+	assets: AssetReference[],
+): string {
+	if (assets.length === 0) {
+		return `export default ${JSON.stringify(html)};`
+	}
+
+	const lines: string[] = []
+
+	for (let i = 0; i < assets.length; i++) {
+		const asset = assets[i]
+		lines.push(
+			`import __asset_${i}__ from ${JSON.stringify(asset.absolutePath)};`,
+		)
+	}
+
+	lines.push("")
+	lines.push(`let html = ${JSON.stringify(html)};`)
+
+	for (let i = 0; i < assets.length; i++) {
+		const asset = assets[i]
+		lines.push(
+			`html = html.replaceAll(${JSON.stringify(asset.placeholderToken)}, __asset_${i}__);`,
+		)
+	}
+
+	lines.push("")
+	lines.push("export default html;")
+
+	return lines.join("\n")
+}

package/src/content.ts

@@ -0,0 +1,143 @@
+import fs from "node:fs"
+import path from "node:path"
+import matter from "gray-matter"
+import type { MarkedExtension } from "marked"
+import { Marked } from "marked"
+import { parse as parseToml } from "smol-toml"
+import type { ContentFrontmatter, ParsedContentItem } from "./types.ts"
+
+const matterOptions: matter.GrayMatterOption<string, any> = {
+	engines: {
+		toml: {
+			parse: parseToml as unknown as (input: string) => Record<string, unknown>,
+			stringify: () => {
+				throw new Error("TOML stringify not supported")
+			},
+		},
+	},
+}
+
+export function scanDirectory(dir: string, recursive: boolean): string[] {
+	const results: string[] = []
+	const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name)
+		if (entry.isDirectory() && recursive) {
+			results.push(...scanDirectory(fullPath, recursive))
+		} else if (entry.isFile() && entry.name.endsWith(".md")) {
+			results.push(fullPath)
+		}
+	}
+
+	return results
+}
+
+export function parseFrontmatter(
+	fileContent: string,
+	filePath: string,
+): { data: Record<string, unknown>; content: string } {
+	try {
+		const result = matter(fileContent, matterOptions)
+		return { content: result.content, data: result.data }
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		throw new Error(`Invalid frontmatter in ${filePath}: ${message}`)
+	}
+}
+
+export function computeSlug(
+	frontmatter: Record<string, unknown>,
+	filePath: string,
+): string {
+	if (
+		typeof frontmatter.slug === "string" &&
+		frontmatter.slug.trim().length > 0
+	) {
+		return frontmatter.slug.trim()
+	}
+	return path.basename(filePath, ".md")
+}
+
+export function checkDuplicateSlugs(items: ParsedContentItem[]): void {
+	const seen = new Map<string, string>()
+	for (const item of items) {
+		const existing = seen.get(item.frontmatter.slug)
+		if (existing) {
+			throw new Error(
+				`Duplicate slug "${item.frontmatter.slug}" found in:\n` +
+					`  - ${existing}\n` +
+					`  - ${item.filePath}\n` +
+					`Provide an explicit "slug" in frontmatter to resolve.`,
+			)
+		}
+		seen.set(item.frontmatter.slug, item.filePath)
+	}
+}
+
+const FILE_EXT_REGEX = /\.\w{1,10}$/
+
+const assetLinkExtension: MarkedExtension = {
+	renderer: {
+		link({ href, text }) {
+			if (href && FILE_EXT_REGEX.test(href)) {
+				return `<a href="${href}" target="_blank" rel="noopener noreferrer">${text}</a>`
+			}
+			return false
+		},
+	},
+}
+
+export function createRenderer(extensions: MarkedExtension[]): Marked {
+	const marked = new Marked()
+	marked.use(assetLinkExtension)
+	if (extensions.length > 0) {
+		marked.use(...extensions)
+	}
+	return marked
+}
+
+export function parseContentFile(
+	filePath: string,
+	baseDir: string,
+	renderer: Marked,
+	validate?: (frontmatter: Record<string, unknown>, filePath: string) => void,
+): ParsedContentItem {
+	const fileContent = fs.readFileSync(filePath, "utf-8")
+	const { data, content } = parseFrontmatter(fileContent, filePath)
+
+	if (validate) {
+		validate(data, filePath)
+	}
+
+	const slug = computeSlug(data, filePath)
+	const directoryPath = path.relative(baseDir, path.dirname(filePath))
+
+	const html = renderer.parse(content)
+	if (typeof html !== "string") {
+		throw new Error(
+			`Async marked extensions are not supported. File: ${filePath}`,
+		)
+	}
+
+	const frontmatter: ContentFrontmatter = {
+		...data,
+		date:
+			typeof data.date === "string"
+				? data.date
+				: data.date instanceof Date
+					? data.date.toISOString()
+					: "",
+		draft: data.draft === true,
+		slug,
+		title: typeof data.title === "string" ? data.title : "",
+	}
+
+	return {
+		assets: [],
+		directoryPath,
+		filePath,
+		frontmatter,
+		html,
+	}
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { inkwell } from "./plugin.ts"
+export type {
+	ContentFrontmatter,
+	ContentItem,
+	ContentPluginOptions,
+	ParsedContentItem,
+} from "./types.ts"

package/src/plugin.ts

@@ -0,0 +1,247 @@
+import fs from "node:fs"
+import path from "node:path"
+import type { Plugin, ResolvedConfig, ViteDevServer } from "vite"
+import {
+	extractAssetReferences,
+	generateSlugModuleCode,
+	replaceAssetsWithPlaceholders,
+} from "./assets.ts"
+import {
+	checkDuplicateSlugs,
+	createRenderer,
+	parseContentFile,
+	scanDirectory,
+} from "./content.ts"
+import type { ContentPluginOptions, ParsedContentItem } from "./types.ts"
+
+const CONTENT_PREFIX = "inkwell:"
+const RESOLVED_PREFIX = "\0inkwell:"
+const SLUG_SEPARATOR = "/"
+
+export function inkwell(options?: ContentPluginOptions): Plugin {
+	const opts = options ?? {}
+	let config: ResolvedConfig
+	let server: ViteDevServer | undefined
+	let isProduction = false
+
+	const renderer = createRenderer(opts.markedExtensions ?? [])
+
+	// Map from absolute directory path to its parsed content items
+	const collections = new Map<string, ParsedContentItem[]>()
+	// Track which directories are in use for HMR
+	const watchedDirs = new Set<string>()
+
+	function buildCollection(absoluteDir: string): ParsedContentItem[] {
+		if (!fs.existsSync(absoluteDir)) {
+			throw new Error(`Content directory does not exist: ${absoluteDir}`)
+		}
+
+		const recursive = opts.recursive !== false
+		const allFiles = scanDirectory(absoluteDir, recursive)
+		const items: ParsedContentItem[] = []
+
+		for (const filePath of allFiles) {
+			const item = parseContentFile(
+				filePath,
+				absoluteDir,
+				renderer,
+				opts.validate,
+			)
+
+			const assets = extractAssetReferences(item.html, filePath)
+			item.assets = assets
+			item.html = replaceAssetsWithPlaceholders(item.html, assets)
+
+			items.push(item)
+		}
+
+		checkDuplicateSlugs(items)
+		return items
+	}
+
+	function getVisibleItems(items: ParsedContentItem[]): ParsedContentItem[] {
+		if (isProduction && !opts.includeDrafts) {
+			return items.filter((item) => !item.frontmatter.draft)
+		}
+		return items
+	}
+
+	function generateCollectionModule(absoluteDir: string): string {
+		const allItems = collections.get(absoluteDir)
+		if (!allItems) {
+			throw new Error(`No content collection for directory: ${absoluteDir}`)
+		}
+
+		const items = getVisibleItems(allItems)
+		const slugPrefix = CONTENT_PREFIX + absoluteDir + SLUG_SEPARATOR
+
+		const entries = items.map((item) => {
+			const meta: Record<string, unknown> = { ...item.frontmatter }
+			delete meta.title
+			delete meta.slug
+			delete meta.date
+			delete meta.draft
+
+			return [
+				"  {",
+				`    title: ${JSON.stringify(item.frontmatter.title)},`,
+				`    slug: ${JSON.stringify(item.frontmatter.slug)},`,
+				`    date: ${JSON.stringify(item.frontmatter.date)},`,
+				`    draft: ${JSON.stringify(item.frontmatter.draft)},`,
+				`    directory: ${JSON.stringify(item.directoryPath)},`,
+				`    meta: ${JSON.stringify(meta)},`,
+				`    getHtml: () => import(${JSON.stringify(slugPrefix + item.frontmatter.slug)}).then(m => m.default),`,
+				"  }",
+			].join("\n")
+		})
+
+		return `export default [\n${entries.join(",\n")}\n];\n`
+	}
+
+	function findItemBySlug(
+		absoluteDir: string,
+		slug: string,
+	): ParsedContentItem | undefined {
+		const items = collections.get(absoluteDir)
+		return items?.find((i) => i.frontmatter.slug === slug)
+	}
+
+	return {
+		configResolved(resolvedConfig) {
+			config = resolvedConfig
+			isProduction = resolvedConfig.command === "build"
+		},
+
+		configureServer(devServer) {
+			server = devServer
+		},
+		enforce: "pre",
+
+		handleHotUpdate(ctx) {
+			const { file, server: hmrServer } = ctx
+			if (!file.endsWith(".md")) return
+
+			// Find which watched directory this file belongs to
+			let matchedDir: string | undefined
+			for (const dir of watchedDirs) {
+				if (file.startsWith(dir + path.sep) || file.startsWith(`${dir}/`)) {
+					matchedDir = dir
+					break
+				}
+			}
+
+			if (!matchedDir) return
+
+			try {
+				const items = buildCollection(matchedDir)
+				collections.set(matchedDir, items)
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error)
+				hmrServer.config.logger.error(message)
+				return []
+			}
+
+			// Invalidate the collection module
+			const collectionId = RESOLVED_PREFIX + matchedDir
+			const collectionModule = hmrServer.moduleGraph.getModuleById(collectionId)
+			if (collectionModule) {
+				hmrServer.moduleGraph.invalidateModule(collectionModule)
+			}
+
+			// Invalidate the changed file's slug module
+			const items = collections.get(matchedDir)
+			const changedItem = items?.find((item) => item.filePath === file)
+			if (changedItem) {
+				const slugId =
+					RESOLVED_PREFIX +
+					matchedDir +
+					SLUG_SEPARATOR +
+					changedItem.frontmatter.slug
+				const slugModule = hmrServer.moduleGraph.getModuleById(slugId)
+				if (slugModule) {
+					hmrServer.moduleGraph.invalidateModule(slugModule)
+				}
+			}
+
+			hmrServer.hot.send({ type: "full-reload" })
+			return []
+		},
+
+		load(id) {
+			if (!id.startsWith(RESOLVED_PREFIX)) return null
+
+			const rest = id.slice(RESOLVED_PREFIX.length)
+
+			// Check if this is a slug module (contains a slug after the directory path)
+			// Slug modules: \0content:/abs/path/to/dir/my-slug
+			// Collection modules: \0content:/abs/path/to/dir
+			for (const [absoluteDir, items] of collections) {
+				const dirPrefix = absoluteDir + SLUG_SEPARATOR
+				if (rest.startsWith(dirPrefix) && rest.length > dirPrefix.length) {
+					const slug = rest.slice(dirPrefix.length)
+					const item = items.find((i) => i.frontmatter.slug === slug)
+					if (!item) {
+						throw new Error(`Content item with slug "${slug}" not found`)
+					}
+					return generateSlugModuleCode(item.html, item.assets)
+				}
+
+				if (rest === absoluteDir) {
+					return generateCollectionModule(absoluteDir)
+				}
+			}
+
+			// If we get here, the collection hasn't been built yet
+			// This happens on first load — build it now
+			if (rest.includes(SLUG_SEPARATOR)) {
+				// Try to find the directory portion
+				// Walk backward from the end to find a valid directory
+				const lastSlash = rest.lastIndexOf(SLUG_SEPARATOR)
+				const possibleDir = rest.slice(0, lastSlash)
+				const slug = rest.slice(lastSlash + 1)
+
+				if (collections.has(possibleDir)) {
+					const item = findItemBySlug(possibleDir, slug)
+					if (!item) {
+						throw new Error(`Content item with slug "${slug}" not found`)
+					}
+					return generateSlugModuleCode(item.html, item.assets)
+				}
+			}
+
+			return null
+		},
+		name: "inkwell",
+
+		resolveId(source, importer) {
+			if (!source.startsWith(CONTENT_PREFIX)) return null
+
+			const rawPath = source.slice(CONTENT_PREFIX.length)
+
+			// If the path is already absolute (resolved from a slug module import), use it directly
+			if (path.isAbsolute(rawPath)) {
+				return RESOLVED_PREFIX + rawPath
+			}
+
+			// Resolve relative to the importer's directory
+			const importerDir = importer ? path.dirname(importer) : config.root
+			// Strip the \0 prefix from importer if it's a virtual module
+			const cleanImporterDir = importerDir.replace(/^\0/, "")
+			const absoluteDir = path.resolve(cleanImporterDir, rawPath)
+
+			// Build the collection if we haven't yet
+			if (!collections.has(absoluteDir)) {
+				const items = buildCollection(absoluteDir)
+				collections.set(absoluteDir, items)
+
+				// Watch directory for HMR
+				if (server) {
+					server.watcher.add(absoluteDir)
+				}
+				watchedDirs.add(absoluteDir)
+			}
+
+			return RESOLVED_PREFIX + absoluteDir
+		},
+	}
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+import type { MarkedExtension } from "marked"
+
+export interface ContentPluginOptions {
+	/** Whether to recursively scan subdirectories (default: true) */
+	recursive?: boolean
+	/** Custom frontmatter validation function. Throw to fail build. */
+	validate?: (frontmatter: Record<string, unknown>, filePath: string) => void
+	/** Marked extensions for custom markdown rendering */
+	markedExtensions?: MarkedExtension[]
+	/** Whether to include draft posts in production (default: false) */
+	includeDrafts?: boolean
+}
+
+export interface ContentFrontmatter {
+	title: string
+	slug: string
+	date: string
+	draft: boolean
+	[key: string]: unknown
+}
+
+export interface AssetReference {
+	/** Original relative path as written in the markdown */
+	originalPath: string
+	/** Absolute filesystem path */
+	absolutePath: string
+	/** Placeholder token used in the HTML template string */
+	placeholderToken: string
+}
+
+export interface ParsedContentItem {
+	frontmatter: ContentFrontmatter
+	filePath: string
+	/** Directory path relative to the configured content directory */
+	directoryPath: string
+	/** Rendered HTML with placeholder tokens for assets */
+	html: string
+	/** Asset references discovered in this content */
+	assets: AssetReference[]
+}
+
+export interface ContentItem {
+	title: string
+	slug: string
+	date: string
+	draft: boolean
+	/** Relative directory path within the content source */
+	directory: string
+	/** All frontmatter key-value pairs (excluding title, slug, date, draft) */
+	meta: Record<string, unknown>
+	/** Lazy-load the rendered HTML for this content item */
+	getHtml: () => Promise<string>
+}