Markii for VS Code

Preview for Markii (.mk.md) documents: CommonMark plus a small directive syntax that renders components: callouts, cards, tabs, dashboard stats, and more. See the format guide for the full picture.

Getting started

No setup. After installing the extension:

1. Open any file ending in .mk.md (create one if you like; it's an ordinary text file).
2. Press Ctrl+Shift+V (Cmd+Shift+V on macOS). You can also click the preview icon at the right of the editor title bar, or run Markii: Open Preview from the command palette.

In a .mk.md file that shortcut opens the Markii preview; in a plain .md file it still opens VS Code's built-in markdown preview, unchanged.

The preview opens beside the editor, follows whichever .mk.md file is active, updates as you type, and matches your VS Code theme.

Configuration

Five settings decide what may run: markii.packs, markii.runOnOpen, markii.refreshIntervalSeconds, markii.scriptsDisabled, and markii.allowPrivateNetworkAddresses. All five are user-scope only. A workspace's .vscode/settings.json cannot set them, on purpose: it is what stops a repository you open from silently enabling script execution, loading a pack, or widening network access on your behalf, and it is also what stops one turning script execution back on once you have turned it off.

Two more settings are cosmetic and a workspace may set them: markii.previewWidth and markii.hideScriptBlocks.

To reach them:

• Open Settings and search for "Markii".
• Run Welcome: Open Walkthrough... from the Command Palette and pick "Get Started with Markii" for a short walkthrough that links to each setting.
• If you use profiles and want the raw JSON, run Preferences: Open Application Settings (JSON), not the usual "Open User Settings (JSON)" command; application-scope settings live there.

A worked example, in that JSON file:

{
  "markii.runOnOpen": true,
  "markii.refreshIntervalSeconds": 30,
  "markii.packs": ["/home/me/markii-packs/analytics"]
}

Three commands write these settings without opening the JSON by hand: Markii: Toggle Run On Open flips markii.runOnOpen, Markii: Enable Scheduled Refresh… prompts for a number of seconds and writes markii.refreshIntervalSeconds, and Markii: Toggle Script Execution flips markii.scriptsDisabled.

Turning scripts off

Set markii.scriptsDisabled to true and no note runs its scripts on this machine: not Markii: Run Scripts, not run on open, not the refresh timer. A blocked Markii: Run Scripts says so; a blocked automatic run is written to the Markii output channel instead of interrupting you on every note you open. Notes still preview, still export, and still show whatever values their last run produced. Your grants are untouched in both directions, so turning script execution back on re-authorizes nothing beyond what you had already granted by hand.

Hiding script blocks

Set markii.hideScriptBlocks to true and the preview leaves script markers out, for a note meant to be read rather than edited. It hides the source blocks only. A script that fails still marks the value it feeds, still flips the note's run marker to its failed state, and still writes its reason to the Markii output channel, so nothing is hidden that you would need in order to work out what went wrong.

Features

• Components. Renders the whole format: directives, the standard component set (callouts, cards, tabs, dashboard stats, and more), layout wrappers, tables, and frontmatter.
• Live preview. Opens beside the editor, follows the active .mk.md file, updates as you type, matches your VS Code theme, and highlights directive syntax in the editor too.
• Scripts, on demand. Press Markii: Run Scripts and each named Lua script block runs in a sandbox, feeding the data-bound components (stat, progress, chart, :value[...]). Scripts never run when a note is only opened, and network access is granted one host at a time, with a prompt. Until you run them, script blocks show a collapsed marker and data-bound components show their quiet empty states.
• Monitoring notes. A note's last values are remembered, so reopening it shows its figures immediately, marked stale, before any re-run. Turn on markii.runOnOpen to run a note once when its preview opens, or set markii.refreshIntervalSeconds to refresh it on an interval. Both run at the read-only tier: they reuse only the hosts you already granted by hand, never prompt on a timer, and never add network access.
• Component packs. Point the markii.packs setting, or the Markii: Add Pack Folder… command, at folders you trust as installed packs. Their prefixed components (for example :::ana_timeline) render in the preview, and their shared Lua is reachable from require "ana/..." in a note's scripts. A note that uses a pack you have not installed stays readable: the unknown component shows a labeled fallback. The setting is user-scope only, so opening someone else's project never loads a pack on your behalf. See the packs guide.
• Authoring help. Typing : or ::: suggests component names; inside a brace it suggests attribute names and, for an attribute with a fixed set of values, the values themselves. Hovering a directive name shows its documentation. The Markii: Insert Component… command inserts a chosen component's skeleton at the cursor, with every standard component and any configured pack's components on offer.
• Export. Markii: Export as HTML… writes the note as one self-contained .html file, styles embedded and the last run's values baked in, at a path you pick. Saving it beside the note keeps its relative images working. The static renderer knows the standard component set, so a pack component exports as the same labeled fallback box an uninstalled pack shows, with your own content still inside it. For a PDF, open the exported file in a browser and print it. Markii: Export as HTML cascade… does the same for a whole set: it follows the markdown links out of the note, exports every note it reaches, and writes one zip archive, with the links between those notes pointing at the exported files so the set browses offline. A link to anything outside your workspace is never followed and stays as you wrote it, and every note left out is named on the Markii output channel.
• Images. Local images resolve relative to the note (nice.png beside it, img/nice.png in a subfolder) and remote images load over https. Anything outside the note's folder and your workspace is not loaded, the same rule VS Code's own preview uses.

The extension has no rendering logic of its own: it hosts @markii/react, the format's reference renderer, so the preview shows exactly what the reference implementation renders.

Contributing

The extension lives in the Markii monorepo. Build, debug, and release details are in the repo's AGENTS.md; issues and pull requests are welcome there.