@robino/md

npm i @robino/md

• Processor - markdown processor
• md - Vite plugin

Overview

An extended markdown-it instance with the following features.

• process markdown with headings and frontmatter using a Standard Schema validator
• Syntax highlighting with shiki using the CSS variables theme to style
• Adds <div style="overflow-x: auto;">...</div> around each table element to prevent overflow
• Adds anchors and id attributes to headings
• stream and generate functions to render and highlight a stream or iterable of markdown
• Vite plugin to process markdown at build time
• A ?frontmatter Vite query for importing metadata without eagerly loading full Markdown modules

Processor

import { Processor } from "@robino/md";
import langJs from "@shikijs/langs/js";

const processor = new Processor({
	markdownIt: {
		// markdown-it options
	},
	highlighter: {
		// shiki langs
		langs: [langJs],
	},
});

processor.use(SomeOtherPlugin); // use other plugins

process

The process method provides extra meta data in addition to the HTML result.

// example using zod, any Standard Schema validator is supported
import { z } from "zod";

const FrontmatterSchema = z
	.object({
		title: z.string(),
		description: z.string(),
		keywords: z
			.string()
			.transform((val) => val.split(",").map((s) => s.trim().toLowerCase())),
		date: z.string(),
	})
	.strict();

const result = await processor.process(md, FrontmatterSchema);

result.html; // processed HTML article
result.headings; // { id: string, name: string, level: number }[]
result.frontmatter; // type-safe/validated frontmatter based on the schema

render

Use the render method to render highlighted HTML.

const html = processor.render(md);

stream

stream streams the result of a markdown stream through the renderer/highlighter. You can easily render/highlight and stream the output from an LLM on the server.

Headings and horizontal rules can render as soon as their lines finish. Paragraphs, lists, and other blocks wait until their structure is stable.

generate is also available to transform a generator of markdown into a generator of HTML.

Top-level fenced code blocks emit complete code lines, preserving syntax highlighting across multiline comments and strings. Top-level tables emit their header after the alignment row, then complete body rows as they arrive. Blocks inside lists or blockquotes wait until their enclosing block is stable.

const htmlStream = processor.stream(mdStream);

return new Response(htmlStream.pipeThrough(new TextEncoderStream()), {
	headers: { "Content-Type": "text/html; charset=utf-8" },
});

The browser parses this as one continuous HTML response; no client-side JavaScript is required. Incremental chunks can contain open <pre>, <code>, or table containers. Write them in order to the same response, without parsing each chunk as a separate HTML fragment. The concatenated result matches render for the same input.

for await (const html of processor.generate(mdIterable)) {
	// Write html to the same response.
}

Markdown that depends on later input stays buffered. Potential reference links and link definitions keep the remaining document together until the input ends. Tables with missing or extra cells also buffer their remaining content to preserve the parser's limits. Custom plugins, highlighting callbacks, or modified parser/renderer rules use a full render at the end of the input.

ai-sdk

import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";

const { textStream } = streamText({
	model: openai("gpt-4o-mini"),
	prompt: "write some js code",
});

const htmlStream = processor.stream(textStream);

openai

import { OpenAI } from "openai";

const openai = new OpenAI({ apiKey: OPENAI_API_KEY });

const response = await openai.responses.create({
	input: [
		{
			role: "user",
			content: "write some sample prose, a list, js code, table, etc.",
		},
	],
	model: "gpt-4o-mini",
	stream: true,
});

const mdStream = new ReadableStream<string>({
	async start(c) {
		for await (const event of response) {
			if (event.type === "response.output_text.delta") {
				if (event.delta) c.enqueue(event.delta);
			}
		}
		c.close();
	},
});

const htmlStream = processor.stream(mdStream);

Plugin

Configuration

Add the plugin to your vite.config to render markdown at build time.

// vite.config.ts
import { FrontmatterSchema } from "./src/lib/schema";
import { md } from "@robino/md";
import langJs from "@shikijs/langs/js";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [
		md({
			markdownIt: {
				// markdown-it options
			},
			highlighter: {
				// shiki langs
				langs: [langJs],
			},
			FrontmatterSchema,
		}),
	],
});

Usage

Import a directory of processed markdown using a glob import.

import { FrontmatterSchema } from "./schema";
import type { Result } from "@robino/md";

const content = import.meta.glob<Result<typeof FrontmatterSchema>>(
	"./content/*.md",
	{ eager: true },
);

Lazy content with eager frontmatter

Use the ?frontmatter query when a listing needs all post metadata eagerly while the complete posts should remain lazy. The md plugin includes separate transforms for Markdown and frontmatter imports. The frontmatter transform validates with the configured FrontmatterSchema and exports the result without rendering the Markdown.

The query requires FrontmatterSchema and throws an error if it is not configured. Regular Markdown imports continue to work without a schema.

import type { Frontmatter } from "./schema";

const content = import.meta.glob("./content/*.md");

const metadata = import.meta.glob<Frontmatter>("./content/*.md", {
	eager: true,
	import: "frontmatter",
	query: "?frontmatter",
});

Importing the frontmatter named export eagerly from the same .md module would make that module static and prevent its other exports from being split into a lazy chunk. The query creates a separate module boundary for the metadata.

You can also import normally, add a d.ts file for type safety.

// d.ts
declare module "*.md" {
	import type { Heading } from "@robino/md";

	export const source: string;
	export const html: string;
	export const article: string;
	export const headings: Heading[];
	export const frontmatter: Frontmatter; // inferred output type from your schema
}

declare module "*.md?frontmatter" {
	export const frontmatter: Frontmatter;
}

import { article, frontmatter, headings, html, source } from "./post.md";
import { frontmatter } from "./post.md?frontmatter";