Think in Markdown. Render in HTML.
MDS is a Markdown-based semantic authoring language. Authors write normal Markdown plus a small set of semantic blocks; MDS parses that source and renders standalone or embeddable HTML through reusable themes.
0.1.0-beta.2 is the current prerelease in the public @mds-crate npm organization. It expands the fixed release set to fourteen packages by adding the Rich, Light, and Dark themes. The beta requires Node.js 20.19 or newer and publishes ESM packages. Prerelease installation examples use the next tag; latest intentionally remains on 0.1.0-beta.1 until the stable-release decision.
The Editor is currently a local browser application launched by the mds CLI, not a native .dmg or .exe application. See the beta testing guide for supported journeys, known limitations, and feedback links.
npm install --global @mds-crate/cli@next
mds edit ./page.mdsThe command opens the packaged Editor in your browser and reads and saves real files inside the selected project root. See the Editor guide for directory mode, themes, conflict handling, and the local security boundary.
npm install @mds-crate/renderer-html@next @mds-crate/theme-default@nextimport { renderMdsResult } from "@mds-crate/renderer-html";
import { theme } from "@mds-crate/theme-default";
const result = renderMdsResult("# Hello from MDS", {
mode: "fragment",
theme
});
console.log(result.body, result.diagnostics);Starting with 0.1.0-beta.2, use @mds-crate/theme-light@next or @mds-crate/theme-dark@next when an application needs a fixed appearance independent of the operating-system preference. For data tables, charts, technical documentation, guided sequences, galleries, and conversation layouts, install @mds-crate/theme-rich@next and import its theme export instead.
npm install --global @mds-crate/cli@next
mds theme init ./my-theme
cd ./my-theme
npm install
npm run build
npm run inspectThe scaffold publishes a plain dist/theme artifact. HTML is the default authoring mode; pass --template jsx or --template react for those build-time authoring options.
The 0.1 line is organized around three user journeys:
- Theme authors can initialize, build, inspect, pack, and publish package-defined themes.
- Document authors can open, edit, preview, and save real
.mdsfiles in a local Editor. - Application developers can render MDS source in Node.js and browser projects through stable package APIs.
All three journeys pass against the published 0.1.0-beta.2 registry packages across the expanded fourteen-package set. See the release plan for acceptance evidence and the path from external beta feedback to 0.1.0.
Requirements:
- Node.js 20.19 or newer
- pnpm 10.34.5
corepack enable
pnpm install
pnpm check
pnpm test
pnpm buildStart the development Editor:
pnpm dev:editorBuild an MDS document with the workspace CLI:
pnpm --filter @mds-crate/cli exec mds build ./examples/basic/index.mdsOpen a real file in the packaged local Editor:
pnpm --filter @mds-crate/cli build
node packages/cli/dist/index.js edit ./examples/basic/index.mdsRender source directly from an application:
import { renderMdsResult } from "@mds-crate/renderer-html";
import { theme } from "@mds-crate/theme-default";
const result = renderMdsResult(source, { mode: "fragment", theme });
console.log(result.body, result.diagnostics);Build and inspect a package theme:
pnpm build:theme:default
pnpm build:theme:rich
node packages/theme-builder/dist/cli.js inspect ./themes/defaultCreate a new package theme:
pnpm --filter @mds-crate/cli exec mds theme init ./tmp/my-themeThe normal compilation path is:
MDS source
-> @mds-crate/parser
-> @mds-crate/ast
-> @mds-crate/renderer-html
-> HtmlTheme
-> HTMLTheme packages are built separately:
theme source + @mds-crate/blocks
-> @mds-crate/theme-builder
-> plain theme artifact
-> @mds-crate/theme-loader
-> HtmlThemeThe runtime consumes plain theme artifacts. TypeScript, JSX, React, Tailwind, and other authoring tools are build-time choices, not required browser runtimes.
Primary public packages:
@mds-crate/renderer-html@mds-crate/theme-default@mds-crate/theme-light@mds-crate/theme-dark@mds-crate/theme-rich@mds-crate/cli@mds-crate/theme-builder@mds-crate/theme-sdk-html@mds-crate/theme-sdk-react@mds-crate/blocks
Lower-level packages:
@mds-crate/ast@mds-crate/html-types@mds-crate/parser@mds-crate/theme-loader
- Rendering performance and preview lifecycle
- Language specification
- Implementation plan
- Release plan
- Publishing runbook
- Theme authoring
- Theme architecture
- Shared block layer
- Editor plan
- Local Editor guide
- AI authoring rules
- AI generation roadmap
MDS document source may be untrusted and must render through escaping and URL-safety rules. Themes are trusted code: package-theme builds may execute source, and built themes may intentionally provide JavaScript or head markup.
Navigation links allow relative URLs, HTTP(S), mailto:, and tel:. Media, embeds, and downloads allow relative URLs and HTTP(S). Executable or local schemes such as javascript:, data:, vbscript:, and file: are neutralized and reported as unsafe-url diagnostics.
Please read SECURITY.md before reporting a vulnerability.
Licensed under the Apache License, Version 2.0. See LICENSE.