graphite.md

A Markdown preview for people who read a lot of Markdown: collapsible sections, a git-graph style outline, checklists, math, and diagrams — in a dark, distraction-free theme.

Documentation · Marketplace · Issues

Features

Collapsible sections. Every heading in your document collapses and expands independently. Long specs and READMEs stop being one giant scroll.

A git-graph outline. The right-hand "On this page" pane shows your document's structure as a connected graph — not a flat list — split into three views:

• Content — your heading structure, nested exactly as it is in the doc
• Tables — every table in the document, jump straight to any of them
• Diagrams — every diagram, same idea

Only one view is open at a time. Click any node to soft-scroll to that part of the document; the outline highlights where you are as you scroll.

It also folds away when you want the width back — the chevron in the preview's top-right corner, graphite.md: Toggle Outline from the Command Palette, or Ctrl+G O. With the pane gone the reading column takes the whole width and your text re-wraps to match, and which panels you folded is remembered per preview.

Front matter, as a table. A YAML block at the top of a document — a title, a date, tags — arrives as key/value rows rather than as a stray heading in the outline, the same treatment VS Code's own preview gives it. Front matter that won't parse is reported as an error block instead of half a table.

Checklists. Write - [ ] and - [x] as usual. In the preview they render as real, clickable checkboxes — checking one off edits your markdown file directly, so your task list and your document never drift apart.

Math. Inline ($...$) and block ($$...$$) math, rendered with KaTeX.

Diagrams. Fenced ```mermaid code blocks render as live diagrams.

Images. ![alt](https://github.com/ROG-stdioh/graphite-md/raw/HEAD/diagram.png) renders, resolved against the document it is written in — so a file in a subfolder finds the pictures beside it, and one that reaches up a level works whenever you have that folder open. Images from the network are a separate matter, and off by default; see Settings.

Callouts. Blockquotes (>) get a distinct treatment so notes and asides stand out from body text.

Rich inline syntax. Superscript (^2^), subscript (~2~), underline (++text++), highlighting (==text==), strikethrough (~~text~~), and footnotes ([^1]) all render natively.

Raw HTML renders. <mark>, <kbd>, <details>, a hand-written <table>, an <img> pointing at a file beside the document — markup you write arrives as markup, the same way VS Code's own Markdown preview treats it, rather than as visible angle brackets. What does not run is script: <script>, an onclick= attribute and an <iframe> are all refused by the preview's Content-Security-Policy, and a <form> can't post anywhere. The boundary is the policy, not the renderer.

Links that go where you meant them to. A relative link opens the file it points at, resolved against the document you're previewing — the same way VS Code's own Markdown preview resolves it. Absolute URLs open in your browser. And a bare filename stays a filename: README.md in a sentence is not turned into a link to http://README.md, which matters because plenty of country domains (.md, .sh, .rs, .pl, .so, .cc) are also file extensions.

Syntax highlighting. Fenced code blocks are highlighted with highlight.js, tinted to match the graphite theme.

Tunable reading width. Set it once in settings.json:

"graphiteMd.contentWidth": 60

Usage

1. Open a .md file.
2. Run graphite.md: Open Preview to the Side from the Command Palette, or press Ctrl+G S. Ctrl+G P opens the preview in the current editor group instead, and Ctrl+G O folds the outline pane away.
3. The preview updates live as you type.

If the preview ever misbehaves, the graphite.md output channel is where to look — run graphite.md: Show Output from the Command Palette, or pick it from the dropdown in the Output panel. It records which version you're on, every preview opened and closed, every render with how long it took and what it found, and every image the preview declined to load with the reason it declined.

Settings

Requirements

VS Code 1.134.0 or later. No other setup — everything the preview needs (KaTeX, Mermaid) ships bundled with the extension.

Known limitations

• Images from the network (https://…) don't load unless you turn on graphiteMd.remoteImages. That default is deliberate: previewing a file shouldn't quietly tell a stranger's server that you opened it. Images stored beside the document are unaffected by the setting.
• An image referenced by an absolute path — C:\pics\x.png, or a file:// URL — isn't loaded. The preview only resolves paths written relative to the document, and leaves anything absolute alone.
• An image outside the folder you have open doesn't load, and you get an empty box rather than an error. Open a workspace of docs/ by itself, preview docs/setup.md, and ![logo](https://github.com/ROG-stdioh/graphite-md/raw/HEAD/../images/logo.png) stays blank — images/ isn't in the folder you opened. Open the parent that holds both docs/ and images/, and the picture loads. VS Code's built-in Markdown preview draws the line in the same place.
• Script in raw HTML never runs. <script>, onclick=, <iframe> and a posting <form> are all refused, whether they were written in the document or injected into it. That is deliberate — a preview is a reading surface, not a place a document gets to execute — and it matches VS Code's own Markdown preview. Markup still renders; only the executing parts don't.
• The first preview opened in a window can pause for a few seconds if the document contains a diagram. The host reads and hashes the 3.18 MB Mermaid bundle to derive the version in its URL, and on a cold file cache that read is slow. It is paid once per window, not once per render, and a document without a diagram never loads Mermaid at all. (#25)
• An image inside a heading isn't resolved. ## The ![logo](https://github.com/ROG-stdioh/graphite-md/raw/HEAD/logo.png) release shows a broken box, though the same image in a paragraph below renders fine. (#28)
• Merged-cell tables (rowspan / colspan) aren't supported yet — a syntax for them is still being designed. (#8)
• The preview doesn't follow the editor cursor, or the editor the preview. Re-rendering after an edit does preserve your scroll position, so you aren't thrown back to the top.

Contributing

See DEVELOPMENT.md for build instructions and an overview of how the extension is put together.

License

MIT