Markdown OKF-Schema Studio

Markdown OKF-Schema Studio logo

VS Code Marketplace | Screenshot report/gallery | Requirements

Markdown OKF-Schema Studio is a visual Markdown editor for VS Code. You read a clean rendered page and click any block to edit its source. It renders CommonMark, GitHub Flavored Markdown, Sphinx MyST, OKF and OKF-Schema.

Tip

Version 1.0.0 is out. See what's new in the release notes.

Example of complex Markdown rendering

A long Cream page in Auto width: figure, tables, a wide table breaking out of the column, a chart and a diagram

Why Markdown OKF-Schema Studio?

Important

TL;DR: I love MyST. It is underrated, it allows complex Markdown structures, and LLMs know it very well.

I also use OKF bundles a lot, and I added JSON Schema validation to them with OKF-Schema, so I needed an elegant way to view their front matter.

With the rise of agentic coding, I also review Markdown documents all day long, and it strains the eyes. HTML artifacts (asking the agent to generate HTML) are not collaborative: you cannot annotate them. In one sentence: I need (and hopefully many others do too) a beautiful, rich and collaborative surface between me and my agents.

And I wanted Mermaid, PlantUML, Vega-Lite, tables and rich admonitions.

Note

The Markdown rendering and editing experience of Obsidian is nice, but I hate having to work through a "vault" and to install a plugin for everything.

Markdown is the natural language of coding agents

LLMs love Markdown. It is an ideal format for collaborating on documents. But plain Markdown lacks rich capabilities such as structured grids and columns, so we usually end up asking the agent for an HTML specification instead.

And we lose collaboration instantly.

Highest respect for the raw Markdown

Edits touch only the block you change, in one undo step. This editor never rewraps or reformats the rest of the file, so edits stay small and the diff stays clean.

Edit MyST visually

Sphinx MyST is an awesome but underrated Markdown extension that gives just the right amount of structure to Markdown documents:

grids, columns
admonitions
figures
{list-table}

Here is an example of edition on a MyST documentation, that will be later published on ReadTheDocs for instance:

Editing a MyST admonition while the card grid and figure stay rendered

{versionadded}, {versionchanged} and {deprecated} get their title ("Added in version 0.47"), a standalone {card} shows its :header: and :footer:, and a {tab-set} becomes a tab bar with one panel at a time: click a tab, or move with the arrow keys, Home and End. In edit mode each tab item is a block of its own.

Cream	Dark
Version notes, a card with header and footer, and a tab set on the cream page	The same version notes, card and tab set on the dark page

Edit schema-aware properties

Agents loves markdown with frontmatter but lack structure. OKF-Schema is an external tool that adds a customizable schema these frontmatter that become a properties table with description, enum controls and typed editors.

x-okf-link is an optional extension from OKF-Schema that allows to dynamically show metadata and line numbers of related links.

The OKF properties table with type icons and field descriptions

Read wide tables and text

In Auto width the text keeps a comfortable narrow column, while a wide table or figure breaks out of it and is centred (heavily inspired by Medium user experience)

A narrow text column with a wide table and a wide figure breaking out of it

See what changed since the last commit

Blocks changed since the last Git commit, unsaved edits included, are marked with a green bar in the live preview, and so is each changed or added front matter field in the properties table. A toolbar button toggles the marks.

Blocks changed since the last commit marked with a green bar

Review with comment threads

Select a passage of the document and start a comment thread on it. The thread is anchored to that passage, follows it when the text moves, and is stored in a .comments.json file next to the document, so it is versioned with the Markdown in Git and needs no server. Readers can reply, resolve and delete threads from the popover that opens on the highlighted text.

An open comment thread on a passage, with a comment, a reply, and the Resolve, Delete and Reply controls

Comments are signed with the markdownOkfSchemaStudio.comments.authorName setting. Left empty, it falls back to your Git user.name, then to your operating system user name, and you can override it per user, workspace or folder. Comment threads are the groundwork for future interactive multi-user capabilities, a direction we are exploring with no date attached.

Mermaid and PlantUML, no Java

Mermaid and PlantUML diagrams are drawn by built-in engines. PlantUML needs no Java, no server and no network, and it works in Restricted Mode.

A Mermaid flowchart and a PlantUML sequence diagram rendered inline

Charts, no executable

vega-lite and vega fences are drawn as charts in the preview, themed like the page, from inline data or a CSV file next to the document. The runtime is bundled and loads only on a page that has a chart; nothing runs outside VS Code and nothing is fetched. The new Full palette mode adds the Vega-Lite chart and Vega chart commands (/chart, /vega).

Cream	Dark
A Vega-Lite bar chart and a Vega line chart on the cream page	The same charts on the dark page

Themes

Cream, a warm low-glare paper palette, is the default; Dark, White and the current VS Code theme are one button away.

Dark	White	Cream
Dark theme	White theme	Cream theme

And more

A Notion-style slash menu and an edition palette (Strict, GFM, MyST or Full buttons).
Block selection, multi-block copy, cut, paste and move.
Rich paste from Google Docs, Word or a web page, converted to Markdown.
Pasting a URL makes a link (over selected text), an autolink or, for an image address, an image.
A Sphinx check of the syntax you use against myst_enable_extensions in conf.py.

Install

Install Markdown OKF-Schema Studio from the VS Code Marketplace, or search for it in the Extensions view and select Install.

Usage with coding agent

The repository also ships an agent skill, writing-for-markdown-okf-schema-studio, that teaches an AI agent which Markdown Studio renders well (cards, tabs, admonitions, charts, diagrams). The repository root is a plugin, so every host below reads the same skills/ folder. Install the plugin with your host; copying the skill folder is only a last resort.

Claude Code: add the repository as a marketplace, then install the plugin from it.
```
/plugin marketplace add gsemet/markdown-okf-schema-studio
/plugin install markdown-okf-schema-studio@markdown-okf-schema-studio
```
From a shell: claude plugin marketplace add gsemet/markdown-okf-schema-studio, then claude plugin install markdown-okf-schema-studio@markdown-okf-schema-studio.
GitHub Copilot, in one of three ways depending on the harness.
- (a) Copilot CLI (terminal): add the marketplace, then install the plugin as PLUGIN-NAME@MARKETPLACE-NAME.
```
copilot plugin marketplace add gsemet/markdown-okf-schema-studio
copilot plugin install markdown-okf-schema-studio@markdown-okf-schema-studio
```
  A direct install also works: copilot plugin install gsemet/markdown-okf-schema-studio. The accepted sources are plugin@marketplace, owner/repo, owner/repo:path and a git URL (see copilot plugin install --help and Finding and installing plugins).
- (b) VS Code with the local Copilot harness, per the VS Code agent plugins page: add gsemet/markdown-okf-schema-studio to the setting chat.plugins.marketplaces, then open the Extensions view, search @agentPlugins and select Install. Alternatively, run the Command Palette command Chat: Install Plugin From Source with the repository URL.
- (c) VS Code with the Copilot CLI or Copilot SDK harness: in the session, run /plugin marketplace add gsemet/markdown-okf-schema-studio, then /plugin install markdown-okf-schema-studio@markdown-okf-schema-studio. VS Code also discovers plugins installed by Copilot CLI (~/.copilot/installed-plugins/).
OpenAI Codex: codex plugin marketplace add gsemet/markdown-okf-schema-studio. The documentation gives no further CLI install command.
Agent Plugins (any compatible client): the root plugin.json follows the open Agent Plugins 1.0.0 format. The specification defines no install command, so use your client's own.

Last resort, for a host without plugin support: copy the folder skills/writing-for-markdown-okf-schema-studio/ into .agents/skills/ (or .github/skills/, .claude/skills/) of your project or home folder.

The plugin version always equals the extension version.

Documentation

User guide: the index of all pages below, including install and open Studio with screenshots.
Features and inline editing, toolbar, folding sections, find and replace and slash menu
Themes and motion and wide tables
PlantUML, charts and review comments
OKF and linked-file annotations and Sphinx projects
Settings and comparison
CONTRIBUTING.md: development setup, validation, packaging and release evidence.