8000 GitHub - ziyu/mds: a new markup language · GitHub
[go: up one dir, main page]

Skip to content
ziyuPublic

About

a new markup language

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

MDS

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.

Public Beta

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.

Quick Starts

Edit an MDS file

npm install --global @mds-crate/cli@next
mds edit ./page.mds

The 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.

Render MDS in an application

npm install @mds-crate/renderer-html@next @mds-crate/theme-default@next
import { 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.

Create a package-defined theme

npm install --global @mds-crate/cli@next
mds theme init ./my-theme
cd ./my-theme
npm install
npm run build
npm run inspect

The 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.

Product Surfaces

The 0.1 line is organized around three user journeys:

  1. Theme authors can initialize, build, inspect, pack, and publish package-defined themes.
  2. Document authors can open, edit, preview, and save real .mds files in a local Editor.
  3. 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.

Repository Quick Start

Requirements:

  • Node.js 20.19 or newer
  • pnpm 10.34.5
corepack enable
pnpm install
pnpm check
pnpm test
pnpm build

Start the development Editor:

pnpm dev:editor

Build an MDS document with the workspace CLI:

pnpm --filter @mds-crate/cli exec mds build ./examples/basic/index.mds

Open a real file in the packaged local Editor:

pnpm --filter @mds-crate/cli build
node packages/cli/dist/index.js edit ./examples/basic/index.mds

Render 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/default

Create a new package theme:

pnpm --filter @mds-crate/cli exec mds theme init ./tmp/my-theme

Architecture

The normal compilation path is:

MDS source
  -> @mds-crate/parser
  -> @mds-crate/ast
  -> @mds-crate/renderer-html
  -> HtmlTheme
  -> HTML

Theme packages are built separately:

theme source + @mds-crate/blocks
  -> @mds-crate/theme-builder
  -> plain theme artifact
  -> @mds-crate/theme-loader
  -> HtmlTheme

The runtime consumes plain theme artifacts. TypeScript, JSX, React, Tailwind, and other authoring tools are build-time choices, not required browser runtimes.

Packages

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

Documentation

Security Model

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.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

About

a new markup language

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0