@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
• Vite plugin to process markdown at build time
• stream function to render and highlight a stream of markdown

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.

The result will come in chunks of elements instead of by word since the entire element needs to be present to render and highlight correctly.

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

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 },
);

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 html: string;
	export const article: string;
	export const headings: Heading[];
	export const frontmatter: Frontmatter; // inferred output type from your schema
}

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