Markii

Markii is markdown that renders your own components. A .mk.md file is plain CommonMark plus one small directive syntax, so it opens as readable markdown in any editor, and opens as a living document, with callouts, tabs, charts, and sandboxed scripts feeding them live data, in anything that speaks Markii.

# Example Markii note

## you can use custom components

:::callout{type=warning title="Heads up"}
This ships **Tuesday**.
:::

## you can also run `Lua` code to dynamically render your notes

```lua {name=repo}
local r = net.fetch_json("https://api.github.com/repos/facebook/react")
return { stars = r.stargazers_count }
```

## this is an example of inline substitution. see `docs/format.md`

facebook/react has :value[repo.stars] stars.

Tip

For more details on how Markii works, try the guided tour in the vault playground.

Delete every directive and script and a coherent note remains. That is the line Markii holds: components and scripts feed the document; they never become the document. Unknown components degrade to a labeled box, scripts never run on open, and nothing in a note can break the page.

Identity

Markii is an extensible plain-text document format: CommonMark plus one small directive syntax that renders components you define, with packs as the unit of sharing them. Its identity is in three refusals.

• The syntax is not a programming language. Directives carry no expressions, conditionals, or loops. Scripting exists, but in a separate sandboxed Lua layer that most files never touch.
• Nothing stands between you and the note. A .mk.md file is valid CommonMark and stays readable in any editor, with or without Markii installed. An unknown component renders as a quiet labeled box, never an error.
• The target is a living note, not a typeset page. Components render live in the host and can bind to data that refreshes. Static HTML or PDF is an export, not the product.

If you know LaTeX, Markii wants that extensibility without the macro language or the compiler. If you know MDX, it wants those custom components without putting a program inside the file.

Getting started

Apps

Ways to use Markii with no coding:

Playground Try Markii live in the browser: source, rendered view, Run. Open the playground →

VS Code extension Preview and run .mk.md files and .mkz bundles in the editor. Get it on the Marketplace →

Obsidian plugin Markii components inside an Obsidian vault. Download for Obsidian →

Command line View, export and run a note straight in the terminal. Build it from source →

To render Markii documents in your own React app:

import { defaultRegistry } from '@markii/react/components';
import { renderMark } from '@markii/react';

const view = renderMark(source, defaultRegistry);

Engines

React @markii/react renders an interactive DOM view. Available

Static HTML @markii/html emits a static HTML for publish, CI, archive. Available

Terminal @markii/ansi renders a note as text you can pipe, or as a live view you can read at a prompt. Available

Other toolkits Vue, native, print: the format is engine-neutral. Planned

Components

Every Markii app ships the standard set: callout, card, badge, details, figure, tabs, kbd, rating, divider, and the data-bound stat, progress, and chart. They cover everyday notes, and they are defaults, not the ceiling.

When you outgrow them, components travel as a pack: a folder with a manifest and ordinary components for your engine, built once and pointed at your app. On a machine without the pack, the same note shows a labeled fallback and stays readable. The contract lives in docs/packs.md.

Both apps also ship three packs by default, no configuration needed: read (citation cards, quotes, inline marks and terms), dash (sparklines, gauges, status dots, an uptime bar) and prep (question cards, topic confidence, a self-test quiz). Their sources live at packs/ in this repository.

Integrating and extending

Markii is a format first and a library second. The definition is the spec plus a language-agnostic conformance corpus, so a renderer in any language can claim support by passing the same fixtures this repo tests against.

• Registering your own components, layout, scripting, bundles: start at docs/format.md and the docs index.
• Embedding the libraries or writing a new renderer: docs/integration.md.
• Sharing components as packs: docs/packs.md.
• The normative rules: docs/spec.md.

Development

npm install
npm test       # every workspace
npm run dev    # playground

The repo is an npm-workspaces monorepo: eight @markii/* packages split along the format's seams, a conformance corpus, and a thin playground. Read AGENTS.md and the docs before changing parser or renderer behavior.

License and contributing

MIT. Issues and pull requests are welcome; changes to parser-visible behavior need a conformance fixture, and the docs pages are the source of truth for what the format is.