@effront/markdown

Turn Vite-loaded Markdown into linked pages and standard Comark documents, with file-relative asset URLs and typed Effect failures ready for React rendering.

Usage

Resolve a guide's relative link and image before rendering it:

import { createMarkdownCollection, parseMarkdown } from "@effront/markdown";
import { Effect } from "effect";

const collection = await Effect.runPromise(
  createMarkdownCollection({
    basePath: "/manual",
    documents: {
      "./start.md": "[Guide](./guide.md#intro)\n\n![Logo](./logo.svg)",
      "./guide.md": "# Intro",
    },
    assets: { "./logo.svg": "/assets/logo.hash.svg" },
  }),
);
const entry = collection.get("/manual/start");
if (entry) {
  const document = await Effect.runPromise(parseMarkdown(entry));
  console.log(JSON.stringify(document.nodes));
  // Link href: /manual/guide#intro
  // Image src: /assets/logo.hash.svg
}

In a Vite application, supply the maps with eager import.meta.glob imports using ?raw for documents and ?url for assets. Pass the parsed document to MarkdownDocument from @comark/react/components/MarkdownDocument to render it. Use trusted authored Markdown and parser plugins; this integration does not sanitize untrusted submissions. See the collection and React rendering guide for the complete integration.

Key features

• Maps Markdown filenames to public routes without losing directory structure.
• Resolves document links, image references, queries, and fragments relative to each source file.
• Uses Vite's asset URLs without a runtime filesystem loader or asset-copying step.
• Preserves Comark's standard document format and typed Effect error handling.
• Includes footnotes, math, Mermaid parsing, and Shiki highlighting.

Prerequisites

• Content loading: A Vite application when using import.meta.glob to supply document and asset maps.
• Server runtime: Support for node:path and node:url. Cloudflare Workers requires the nodejs_compat compatibility flag.
• React rendering: Compatible React and React DOM installations when using Comark's React renderer.

Setup

Install the collection package and Effect in your application:

npm install @effront/[email protected] [email protected]

For React rendering, also install Comark's renderer:

npm install @comark/[email protected]

API

The public API guide covers collection options and types, lookups, reference resolution, parseMarkdown, MarkdownError, and standard Comark component mappings. It also documents URL encoding, missing-reference failures, and current Math and Mermaid rendering constraints.

Development

See AGENTS.md.

License

MIT License.

This README was generated from the share-artifact skill and README template.