AIOS Markdown Auto-Preview

A deliberately tiny VS Code extension: when a Markdown file opens as source, automatically reopen it as rendered preview. Built for the one case settings can't fix — clicking a .md link inside the Claude Code chat panel, which force-opens source and ignores your editorAssociations.

It's the Markdown counterpart to AIOS HTML Auto-Preview: both make AI-generated artifacts open the way you actually want to read them.

Install

Search "AIOS Markdown Auto-Preview" in the Extensions view, or from a terminal:

# VS Code (Marketplace)
code --install-extension kyledunne.aios-markdown-auto-preview

# Cursor / VSCodium / Windsurf (Open VSX)
codium --install-extension kyledunne.aios-markdown-auto-preview

To opt a whole project in automatically, add it to the repo's .vscode/extensions.json recommendations:

{ "recommendations": ["kyledunne.aios-markdown-auto-preview"] }

The problem it solves

Setting "*.md": "vscode.markdown.preview.editor" makes Markdown open rendered for the Explorer, Quick Open, etc. — but the Claude Code chat panel is a closed webview that bypasses editorAssociations and force-opens source. No setting reaches it. The only lever left is to react after the file opens.

(HTML chat links have the same problem — caught by the sibling AIOS HTML Auto-Preview, which swaps them to its rendered webview the same way.)

How it works

It watches the editor tabs (window.tabGroups.onDidChangeTabs). When a Markdown file appears as a source (text) editor that it didn't expect, it closes that tab and reopens the same file with the built-in rendered preview editor (vscode.markdown.preview.editor). Net effect: click a link, it opens rendered. One click, no shortcuts, no menus. (Brief sub-100ms source flash.)

Editing source still works, because it distinguishes intent structurally rather than by timing:

• A Markdown text editor for a file it has not just shown as preview = a forced-source open (chat link) → swap to preview.
• A text editor for a file that was just preview = a deliberate downgrade ("Reopen as source file", or the command below) → leave as source.
• It branches on new tab vs existing tab changing, so a just-closed tab's decision never blocks a fresh open.

Unlike the html-preview tool, this registers no custom editor — it leans on VS Code's own Markdown preview. So it works even without the *.md association; pairing the two just means Explorer opens skip straight to preview with no flash.

Pairing it with the association (recommended)

For the cleanest behavior, associate Markdown with the rendered preview editor:

{ "workbench.editorAssociations": { "*.md": "vscode.markdown.preview.editor" } }

Reading source when you want it

• On a preview, click "Reopen as source file" — it sticks.
• Command Palette → AIOS: Open This Markdown as Source.
• Turn it off entirely: AIOS: Toggle Markdown Auto-Preview, or set markdownAutoPreview.enabled to false. (Worth doing if you edit .md source a lot; leave it on for read-mostly use.)

Known limits

• Markdown only (see the HTML sibling above).
• Brief source flash as the swap happens — unavoidable with a reactive swap.
• Fights deliberate cold source opens. It can't tell "opened .md as source on purpose" from "chat forced source," so a cold source open swaps to preview. The escape hatches above cover it; toggle off for heavy source editing.
• Reopen within ~300ms keeps source. Re-clicking a chat link within ~300ms of closing its preview lands on source — the brief recency window that lets "Reopen as source file" stick treats that close+open as the same deliberate downgrade. Effectively unreachable by hand; documented for completeness.

Troubleshooting

Set markdownAutoPreview.debug to true to log every tab event and swap decision to the "AIOS Markdown Auto-Preview" output channel.

Part of the AIOS starter pack.