@void/md 0.0.0

package/README.md

@@ -0,0 +1,152 @@
+# @void/md
+
+Markdown pages plugin for Void — `.md` files as first-class routes with zero client JS, islands support, and Shiki syntax highlighting.
+
+## Setup
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { voidPlugin } from 'void';
+import { voidVue } from '@void/vue/plugin';
+import { voidMarkdown } from '@void/md/plugin';
+
+export default defineConfig({
+  plugins: [voidPlugin(), voidVue(), voidMarkdown()],
+});
+```
+
+Works with any framework adapter — auto-detects Vue, React, Svelte, or Solid from the plugin list.
+
+## Plugin
+
+`voidMarkdown(options?)` returns a Vite plugin array (`Plugin[]`). The plugin runs with `enforce: "pre"`.
+
+Options:
+
+- `shiki?.themes` — `{ light: string; dark: string }` (default: `github-light` / `github-dark`)
+- `shiki?.langs` — additional Shiki languages to load (default: all bundled languages, lazy-loaded)
+
+The plugin exposes an API:
+
+- `api.getClientScripts()` — returns `Map<string, string>` of component ID → client code (used by the islands plugin)
+
+## Runtime
+
+Import from `@void/md`:
+
+- **`useFrontmatter()`** — access the current page's frontmatter object. Uses framework-native context (`provide`/`inject` for Vue, `createContext`/`useContext` for React/Solid, `setContext`/`getContext` for Svelte).
+
+## Virtual Modules
+
+- **`@void/md`** — resolves to `useFrontmatter()` runtime
+- **`@void/md/pages`** — flat array of all `MdPage` objects (HMR-aware), useful for building navs, sidebars, and search indexes
+
+```ts
+import pages from '@void/md/pages';
+// MdPage { path, title, frontmatter, headings }
+```
+
+## Pages
+
+`.md` files in the `pages/` directory become routes. They compile to static HTML at build time with zero client JS by default — auto-prerendered like static island pages.
+
+```md
+---
+title: Getting Started
+author: Jane
+---
+
+# Getting Started
+
+Regular markdown content with **full** syntax support.
+```
+
+### Frontmatter
+
+YAML frontmatter between `---` fences. Title is extracted from `frontmatter.title` or the first `<h1>`.
+
+### Islands
+
+Embed interactive components via a `<script>` block with `island` import attributes:
+
+```md
+---
+title: Interactive Page
+---
+
+<script>
+import Counter from "../components/Counter.vue" with { island: "visible" }
+</script>
+
+# Page with Islands
+
+Static content above, interactive island below:
+
+<Counter />
+```
+
+Island strategies: `idle` (default), `visible`, `media(...)`.
+
+### Client Scripts
+
+Regular imports and statements in `<script>` blocks (without `island` attribute) are bundled as a client module, code-split per page:
+
+```md
+<script>
+import { initAnalytics } from "../lib/analytics"
+initAnalytics()
+</script>
+
+# My Page
+
+Content here.
+```
+
+## Markdown Features
+
+Full VitePress-parity feature set:
+
+- **Syntax highlighting** — Shiki with dual light/dark themes
+- **Line highlighting** — `{1,3-5}` meta in code fences
+- **Notation transforms** — `[!code ++]`, `[!code --]`, `[!code highlight]`, `[!code focus]`, `[!code error]`, `[!code warning]`
+- **Line numbers** — `:line-numbers` / `:no-line-numbers` per fence, `{=N}` start line
+- **Code snippet imports** — `<<< ./file.ext` with region and line range support
+- **Custom containers** — `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::details`
+- **GitHub alerts** — `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`, `> [!CAUTION]`
+- **Emoji** — `:emoji_name:` shortcodes
+- **Attributes** — `{.class #id}` on elements via `markdown-it-attrs`
+- **Anchor links** — auto-generated heading anchors
+- **Table of contents** — `[[toc]]` directive
+- **Image lazy loading** — automatic `loading="lazy"` on images
+- **Link handling** — external links get `target="_blank"`, internal `.md` links normalized
+
+## Theme
+
+Two CSS exports for styling markdown content:
+
+- **`@void/md/theme.css`** — full standalone theme (reset + prose + code + containers)
+- **`@void/md/theme-content.css`** — content-only styles scoped to `.void-md` (prose + code + containers)
+
+```ts
+// In your layout or entry
+import '@void/md/theme.css'; // or theme-content.css
+```
+
+## Architecture
+
+- **Compilation pipeline** — `extractScript()` strips `<script>` blocks and collects island imports → `compile()` runs gray-matter + markdown-exit + Shiki → `emit-{framework}()` generates a framework-specific virtual component
+- **Framework-agnostic** — adapter auto-detected from plugin list; emitters for Vue (SFC), React (JSX), Svelte, and Solid
+- **Lightweight metadata extraction** — `extractMetadata()` parses frontmatter + headings without running Shiki, used for `@void/md/pages` scanning
+- **Islands integration** — pages with island imports split HTML into render chunks with `data-island` markers; pages without islands emit static HTML with a frontmatter context provider
+- **Svelte/Solid secondary modules** — emits a JS re-export pointing to a secondary virtual module (`/@void-md-svelte/` or `/@void-md-solid/`) so Vite processes through the framework's own plugin
+
+## Tests
+
+- `test/unit/compile.test.ts` — compilation pipeline: basic, frontmatter, title extraction, headings, Shiki, emoji, anchors
+- `test/unit/extract-script.test.ts` — script extraction: island imports, client code, edge cases
+- `test/unit/plugins.test.ts` — markdown-it plugins: containers, GitHub alerts, links, images, line numbers, emoji, TOC
+- `test/unit/emit-vue.test.ts` — Vue component emission with and without islands
+- `test/unit/emit-react.test.ts` — React component emission with and without islands
+- `test/unit/emit-svelte.test.ts` — Svelte component emission with and without islands
+- `test/unit/emit-solid.test.ts` — Solid component emission with and without islands

package/dist/compile-BRZW8ppH.mjs

@@ -0,0 +1,333 @@
+import matter from "gray-matter";
+import MarkdownExit from "markdown-exit";
+import anchor from "markdown-it-anchor";
+import { createJavaScriptRegexEngine } from "@shikijs/engine-javascript";
+import { transformerMetaHighlight, transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight } from "@shikijs/transformers";
+import attrs from "markdown-it-attrs";
+import { full } from "markdown-it-emoji";
+import { bundledLanguages, createHighlighter, isSpecialLang } from "shiki";
+import container from "markdown-it-container";
+//#region src/plugins/containers.ts
+function createContainer(md, klass, defaultTitle) {
+	return [
+		container,
+		klass,
+		{ render(tokens, idx, _options, env) {
+			const token = tokens[idx];
+			if (token.nesting === 1) {
+				token.attrJoin("class", `${klass} custom-block`);
+				const attrs = md.renderer.renderAttrs(token);
+				const info = token.info.trim().slice(klass.length).trim();
+				const title = md.renderInline(info || defaultTitle, { references: env.references });
+				const titleClass = "custom-block-title" + (info ? "" : " custom-block-title-default");
+				if (klass === "details") return `<details${attrs}><summary>${title}</summary>\n`;
+				return `<div${attrs}><p class="${titleClass}">${title}</p>\n`;
+			}
+			return klass === "details" ? `</details>\n` : `</div>\n`;
+		} }
+	];
+}
+/**
+* Custom container blocks: :::tip, :::info, :::warning, :::danger, :::details
+* Ported from VitePress.
+*/
+function containerPlugin(md, options) {
+	md.use(...createContainer(md, "tip", options?.tipLabel ?? "TIP")).use(...createContainer(md, "info", options?.infoLabel ?? "INFO")).use(...createContainer(md, "warning", options?.warningLabel ?? "WARNING")).use(...createContainer(md, "danger", options?.dangerLabel ?? "DANGER")).use(...createContainer(md, "details", options?.detailsLabel ?? "Details"));
+}
+//#endregion
+//#region src/plugins/github-alerts.ts
+const markerRE = /^\[!(TIP|NOTE|INFO|IMPORTANT|WARNING|CAUTION|DANGER)\]([^\n\r]*)/i;
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+* GitHub-flavored alerts: > [!NOTE], > [!TIP], > [!WARNING], etc.
+* Ported from VitePress.
+*/
+function gitHubAlertsPlugin(md, options) {
+	const titleMark = {
+		tip: options?.tipLabel ?? "TIP",
+		note: options?.noteLabel ?? "NOTE",
+		info: options?.infoLabel ?? "INFO",
+		important: options?.importantLabel ?? "IMPORTANT",
+		warning: options?.warningLabel ?? "WARNING",
+		caution: options?.cautionLabel ?? "CAUTION",
+		danger: options?.dangerLabel ?? "DANGER"
+	};
+	const rule = (state) => {
+		const tokens = state.tokens;
+		for (let i = 0; i < tokens.length; i++) if (tokens[i].type === "blockquote_open") {
+			const startIndex = i;
+			const open = tokens[startIndex];
+			let endIndex = i + 1;
+			while (endIndex < tokens.length && (tokens[endIndex].type !== "blockquote_close" || tokens[endIndex].level !== open.level)) endIndex++;
+			if (endIndex === tokens.length) continue;
+			const close = tokens[endIndex];
+			const firstContent = tokens.slice(startIndex, endIndex + 1).find((token) => token.type === "inline");
+			if (!firstContent) continue;
+			const match = firstContent.content.match(markerRE);
+			if (!match) continue;
+			const type = match[1].toLowerCase();
+			const title = match[2].trim() || titleMark[type] || capitalize(type);
+			firstContent.content = firstContent.content.slice(match[0].length).trimStart();
+			open.type = "github_alert_open";
+			open.tag = "div";
+			open.meta = {
+				title,
+				type
+			};
+			close.type = "github_alert_close";
+			close.tag = "div";
+		}
+	};
+	md.core.ruler.after("block", "github-alerts", rule);
+	md.renderer.rules.github_alert_open = function(tokens, idx) {
+		const { title, type } = tokens[idx].meta;
+		return `<div class="${type} custom-block github-alert"><p class="custom-block-title">${title}</p>\n`;
+	};
+}
+//#endregion
+//#region src/plugins/image.ts
+const EXTERNAL_URL_RE$1 = /^[a-z]+:/i;
+/**
+* Normalizes relative image paths and optionally adds loading="lazy".
+* Ported from VitePress.
+*/
+function imagePlugin(md, options) {
+	const imageRule = md.renderer.rules.image;
+	md.renderer.rules.image = (tokens, idx, mdOptions, env, self) => {
+		const token = tokens[idx];
+		let url = token.attrGet("src");
+		if (url && !EXTERNAL_URL_RE$1.test(url)) {
+			if (!/^\.?\//.test(url)) url = "./" + url;
+			token.attrSet("src", decodeURIComponent(url));
+		}
+		if (options?.lazyLoading) token.attrSet("loading", "lazy");
+		return imageRule(tokens, idx, mdOptions, env, self);
+	};
+}
+//#endregion
+//#region src/plugins/line-numbers.ts
+/**
+* Adds line number gutter to code blocks.
+* Supports `:line-numbers` / `:no-line-numbers` per-block control and `{=N}` start line.
+* Ported from VitePress.
+*/
+function lineNumberPlugin(md, enable = false) {
+	const fence = md.renderer.rules.fence;
+	md.renderer.rules.fence = async (...args) => {
+		const rawCode = await fence(...args);
+		const [tokens, idx] = args;
+		const info = tokens[idx].info;
+		if (!enable && !/:line-numbers\b/.test(info) || enable && /:no-line-numbers\b/.test(info)) return rawCode;
+		let startLineNumber = 1;
+		const matchStart = info.match(/=(\d+)/);
+		if (matchStart?.[1]) startLineNumber = parseInt(matchStart[1]);
+		const lines = rawCode.slice(rawCode.indexOf("<code>"), rawCode.indexOf("</code>")).split("\n");
+		const lineNumbersWrapper = `<div class="line-numbers-wrapper" aria-hidden="true">${[...Array(lines.length)].map((_, i) => `<span class="line-number">${i + startLineNumber}</span><br>`).join("")}</div>`;
+		return rawCode.replace(/<\/div>$/, `${lineNumbersWrapper}</div>`).replace(/"(language-[^"]*?)"/, "\"$1 line-numbers-mode\"");
+	};
+}
+//#endregion
+//#region src/plugins/link.ts
+const EXTERNAL_URL_RE = /^[a-z]+:/i;
+/**
+* Adds target="_blank" and rel="noreferrer" to external links.
+* Normalizes internal .md links to route paths.
+* Ported from VitePress.
+*/
+function linkPlugin(md, options) {
+	const externalAttrs = options?.externalAttrs ?? {
+		target: "_blank",
+		rel: "noreferrer"
+	};
+	md.renderer.rules.link_open = (tokens, idx, mdOptions, _env, self) => {
+		const token = tokens[idx];
+		const hrefIndex = token.attrIndex("href");
+		if (hrefIndex < 0) return self.renderToken(tokens, idx, mdOptions);
+		const url = token.attrs?.[hrefIndex]?.[1] ?? "";
+		if (url.startsWith("#") || token.attrGet("class") === "header-anchor") return self.renderToken(tokens, idx, mdOptions);
+		if (EXTERNAL_URL_RE.test(url)) for (const [key, val] of Object.entries(externalAttrs)) token.attrSet(key, val);
+		else {
+			let normalized = url;
+			if (normalized.endsWith(".md")) normalized = normalized.slice(0, -3);
+			else if (normalized.includes(".md#")) normalized = normalized.replace(".md#", "#");
+			if (normalized !== url) token.attrs[hrefIndex][1] = normalized;
+		}
+		return self.renderToken(tokens, idx, mdOptions);
+	};
+}
+//#endregion
+//#region src/plugins/pre-wrapper.ts
+function extractLang(info) {
+	return /^[a-zA-Z0-9-_]+/.exec(info)?.[0].replace(/-vue$/, "").replace(/^vue-html$/, "template").replace(/^ansi$/, "") || "";
+}
+/**
+* Wraps fenced code blocks with a language label and copy button.
+* Ported from VitePress.
+*/
+function preWrapperPlugin(md, options) {
+	const title = options?.codeCopyButtonTitle ?? "Copy Code";
+	const fence = md.renderer.rules.fence;
+	md.renderer.rules.fence = async (...args) => {
+		const [tokens, idx] = args;
+		const token = tokens[idx];
+		token.info = token.info.replace(/\[.*\]/, "");
+		const active = / active( |$)/.test(token.info) ? " active" : "";
+		token.info = token.info.replace(/ active$/, "").replace(/ active /, " ");
+		const lang = extractLang(token.info);
+		const highlighted = await fence(...args);
+		return `<div class="language-${lang}${active}"><button title="${title}" class="copy"></button><span class="lang">${lang}</span>` + highlighted + `</div>`;
+	};
+}
+//#endregion
+//#region src/plugins/toc.ts
+function renderHeaders(headers, listTag) {
+	if (headers.length === 0) return "";
+	let result = `<${listTag}>`;
+	for (const h of headers) result += `<li><a href="#${h.slug}">${h.text}</a></li>`;
+	result += `</${listTag}>`;
+	return result;
+}
+/**
+* [[toc]] directive — renders inline table of contents.
+* Ported from VitePress.
+*/
+function tocPlugin(md, options) {
+	const pattern = options?.pattern ?? /^\[\[toc\]\]$/i;
+	const containerTag = options?.containerTag ?? "nav";
+	const containerClass = options?.containerClass ?? "table-of-contents";
+	const listTag = options?.listTag ?? "ul";
+	const level = options?.level ?? [2, 3];
+	md.block.ruler.before("heading", "toc", ((state, startLine, _endLine, silent) => {
+		const pos = state.bMarks[startLine] + state.tShift[startLine];
+		const max = state.eMarks[startLine];
+		const content = state.src.slice(pos, max).trim();
+		if (!pattern.test(content)) return false;
+		if (silent) return true;
+		state.line = startLine + 1;
+		const openToken = state.push("toc_open", containerTag, 1);
+		openToken.markup = content;
+		openToken.attrSet("class", containerClass);
+		const bodyToken = state.push("toc_body", "", 0);
+		bodyToken.markup = content;
+		const closeToken = state.push("toc_close", containerTag, -1);
+		closeToken.markup = content;
+		return true;
+	}), { alt: [
+		"paragraph",
+		"reference",
+		"blockquote"
+	] });
+	md.renderer.rules.toc_open = (tokens, idx, options, _env, self) => {
+		return self.renderToken(tokens, idx, options);
+	};
+	md.renderer.rules.toc_body = (tokens) => {
+		const headers = [];
+		for (let i = 0; i < tokens.length; i++) {
+			const token = tokens[i];
+			if (token.type === "heading_open") {
+				const depth = Number(token.tag.slice(1));
+				if (level.includes(depth)) {
+					const slug = token.attrGet?.("id") ?? "";
+					const text = (tokens[i + 1]?.children?.filter((child) => child.type === "text" || child.type === "code_inline").map((child) => child.content).join("") ?? "").trim();
+					headers.push({
+						depth,
+						slug,
+						text
+					});
+				}
+			}
+		}
+		return renderHeaders(headers, listTag);
+	};
+	md.renderer.rules.toc_close = (tokens, idx, options, _env, self) => {
+		return self.renderToken(tokens, idx, options);
+	};
+}
+//#endregion
+//#region src/compile.ts
+let compilerPromise = null;
+async function getCompiler(options) {
+	if (compilerPromise) return compilerPromise;
+	compilerPromise = createCompiler(options);
+	return compilerPromise;
+}
+async function createCompiler(options) {
+	const md = new MarkdownExit({
+		html: true,
+		linkify: true
+	});
+	const themes = options?.shiki?.themes ?? {
+		light: "github-light",
+		dark: "github-dark"
+	};
+	const highlighter = await createHighlighter({
+		engine: createJavaScriptRegexEngine(),
+		themes: [themes.light, themes.dark],
+		langs: []
+	});
+	const shikiTransformers = [
+		transformerMetaHighlight(),
+		transformerNotationDiff(),
+		transformerNotationHighlight(),
+		transformerNotationFocus(),
+		transformerNotationErrorLevel()
+	];
+	md.renderer.rules.fence = async (tokens, idx) => {
+		const token = tokens[idx];
+		const code = token.content;
+		let lang = token.info ? token.info.split(/\s+/g)[0] : "text";
+		if (!isSpecialLang(lang) && !highlighter.getLoadedLanguages().includes(lang)) if (lang in bundledLanguages) await highlighter.loadLanguage(lang);
+		else lang = "text";
+		return highlighter.codeToHtml(code, {
+			lang,
+			themes,
+			defaultColor: "light",
+			transformers: shikiTransformers,
+			meta: { __raw: token.info }
+		});
+	};
+	md.use(preWrapperPlugin);
+	md.use(containerPlugin);
+	md.use(imagePlugin, { lazyLoading: true });
+	md.use(linkPlugin);
+	md.use(lineNumberPlugin, false);
+	md.use(gitHubAlertsPlugin);
+	md.use(attrs);
+	md.use(full);
+	md.use(anchor, { permalink: anchor.permalink.ariaHidden({ placement: "before" }) });
+	md.use(tocPlugin);
+	return md;
+}
+function extractHeadings(tokens) {
+	const headings = [];
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token.type === "heading_open") {
+			const depth = Number(token.tag.slice(1));
+			const slug = token.attrGet?.("id") ?? "";
+			const text = (tokens[i + 1]?.children?.filter((child) => child.type === "text" || child.type === "code_inline").map((child) => child.content).join("") ?? "").trim();
+			headings.push({
+				depth,
+				slug,
+				text
+			});
+		}
+	}
+	return headings;
+}
+async function compile(source, options) {
+	const { data: frontmatter, content } = matter(source);
+	const compiler = await getCompiler(options);
+	const env = {};
+	const headings = extractHeadings(compiler.parse(content, env));
+	return {
+		html: await compiler.renderAsync(content, env),
+		frontmatter,
+		headings,
+		title: frontmatter.title ?? headings.find((h) => h.depth === 1)?.text ?? ""
+	};
+}
+//#endregion
+export { compile };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { FrontmatterContext, setFrontmatter, useFrontmatter } from "./runtime/index.mjs";
+import { n as MdPage } from "./plugin-BpyOmjmC.mjs";
+export { FrontmatterContext, type MdPage, setFrontmatter, useFrontmatter };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { FrontmatterContext, setFrontmatter, useFrontmatter } from "./runtime/index.mjs";
+export { FrontmatterContext, setFrontmatter, useFrontmatter };

package/dist/plugin-BpyOmjmC.d.mts

@@ -0,0 +1,56 @@
+import { Plugin } from "vite";
+
+//#region src/compile.d.ts
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+interface CompileResult {
+  html: string;
+  frontmatter: Record<string, unknown>;
+  headings: Array<Heading>;
+  title: string;
+}
+interface CompileOptions {
+  shiki?: {
+    themes?: {
+      light: string;
+      dark: string;
+    };
+    langs?: Array<string>;
+  };
+}
+//#endregion
+//#region src/extract-script.d.ts
+interface IslandImport {
+  name: string;
+  specifier: string;
+  strategy: string;
+  /** Root-relative island ID (set during transform when file context is available). */
+  islandId?: string;
+}
+interface ScriptExtraction {
+  script: string | null;
+  body: string;
+  islandImports: Array<IslandImport>;
+  clientCode: string | null;
+}
+//#endregion
+//#region src/plugin.d.ts
+interface MdPage {
+  path: string;
+  title: string;
+  frontmatter: Record<string, unknown>;
+  headings: Array<{
+    depth: number;
+    slug: string;
+    text: string;
+  }>;
+}
+interface MarkdownOptions {
+  shiki?: CompileOptions["shiki"];
+}
+declare function voidMarkdown(options?: MarkdownOptions): Array<Plugin>;
+//#endregion
+export { ScriptExtraction as a, IslandImport as i, MdPage as n, CompileOptions as o, voidMarkdown as r, CompileResult as s, MarkdownOptions as t };

package/dist/plugin.d.mts

@@ -0,0 +1,2 @@
+import { a as ScriptExtraction, i as IslandImport, n as MdPage, o as CompileOptions, r as voidMarkdown, s as CompileResult, t as MarkdownOptions } from "./plugin-BpyOmjmC.mjs";
+export { CompileOptions, CompileResult, IslandImport, MarkdownOptions, MdPage, ScriptExtraction, voidMarkdown };