@williamcachamwri/markui-vite

Vite transformation, strict Markdown validation, page-structure HMR, and typed virtual:markui/routes generation for MarkUI pages.

Install

npm install \
  @williamcachamwri/markui-vite \
  @williamcachamwri/markui-react \
  react react-dom

Supported Vite versions are 7 and 8.

Configure Vite

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { markUI } from '@williamcachamwri/markui-vite'

export default defineConfig({
  plugins: [
    react(),
    markUI({ pagesDir: 'src/pages' }),
  ],
})

Add packaged module declarations to src/vite-env.d.ts:

/// <reference types="vite/client" />
/// <reference types="@williamcachamwri/markui-vite/client" />

Markdown files can then be imported as React page components:

import AccountPage from './pages/account.md'

export function App() {
  return <AccountPage resetKey="account" />
}

Use with the official CLI

Install @williamcachamwri/markui-cli and use:

{
  "scripts": {
    "dev": "markui dev",
    "check": "markui check",
    "build": "markui build",
    "preview": "markui preview"
  }
}

The CLI loads the same vite.config.ts, registry, plugin options, and page directory. markui check calls the project validator without creating a bundle. markui build validates all pages before invoking Vite's build API.

Strict directive diagnostics

Every .md transform runs the shared compiler validator before code generation. Invalid directive syntax fails both development transforms and production builds.

Detected cases include:

• unclosed containers;
• unexpected or extra closing markers;
• equal-width or otherwise ambiguous nested fences;
• leaf-only components used as containers;
• malformed or duplicate attributes;
• unknown directives;
• leaked standalone directive markers.

A Vite-compatible error receives:

interface MarkUIViteError extends Error {
  id: string
  code: string
  loc: {
    file: string
    line: number
    column: number
  }
  frame: string
}

This allows the Vite development overlay and terminal logger to highlight the exact Markdown location. Once the source is corrected, normal HMR resumes; the server does not need to restart.

Markers inside inline code and fenced code blocks remain literal content.

Project checks

The package exports the same validator used by the plugin and CLI:

import { checkMarkUIProject } from '@williamcachamwri/markui-vite'

const result = await checkMarkUIProject({
  root: process.cwd(),
  pagesDir: 'src/pages',
})

if (!result.valid) {
  console.error(result.diagnostics)
}

The result reports all discovered files and all diagnostics rather than stopping at the first invalid page.

Sidecar logic

---
logic: ./account.logic.ts
---

# Account

The logic value must begin with ./ or ../. Bare package imports and absolute paths are rejected so Markdown cannot select arbitrary modules.

File routes

With the default src/pages directory:

src/pages/index.md          -> /
src/pages/about.md          -> /about
src/pages/users/[id].md     -> /users/:id
src/pages/docs/[...slug].md -> /docs/:slug*

import routes, { type MarkUIRoute } from 'virtual:markui/routes'

Generated records expose only path and a lazy component import. Absolute filesystem paths remain internal to the build. Static routes are ordered before dynamic routes, and dynamic routes before catch-all routes. Duplicate URL patterns fail the build and name both source files.

The virtual routes module is generated only from valid pages. Adding, removing, or renaming a Markdown page invalidates the virtual module and triggers a full reload. Editing an existing page participates in normal Vite HMR.

Generated module source maps

Each transformed Markdown page includes a source map with the original .md filename and source content. Component, element, and text nodes are mapped near their original directive or Markdown line, allowing development and production stack traces to resolve generated data back to the page source.

The map is returned through the normal Vite transform result and does not require a separate plugin option. Consumers still control whether production browser source maps are emitted through Vite's build.sourcemap setting.

Development recovery guarantees

Editing an existing page preserves its normal module HMR path and does not invalidate the virtual route module. Invalid Markdown appears in Vite's standard error overlay with a MarkUI diagnostic code. Correcting the source recovers without restarting the server.

Adding or deleting a page is different because route structure changed: MarkUI invalidates virtual:markui/routes and requests a full reload. Browser integration tests exercise invalid-overlay recovery, content HMR, page addition/removal, and the invariant that malformed ::: markers never enter the DOM.

Options

interface MarkUIPluginOptions {
  include?: RegExp
  pagesDir?: string
  runtimeImport?: string
  allowHtml?: boolean
  components?: ComponentDefinition[]
  registry?: ComponentRegistry
}

• include controls transformed Markdown files.
• pagesDir controls project checks and virtual route discovery.
• runtimeImport replaces the default @williamcachamwri/markui-react runtime import.
• allowHtml preserves raw HTML nodes; the React page still requires sanitizeHtml to render them as HTML.
• components and registry extend build-time component validation.

Production behavior

Compiler errors stop the Vite transform and exit production builds nonzero. Warnings include the filename and source position. Production output contains lazy imports for discovered valid pages and never publishes the internal source-path field used during route generation.