azdown

Preview your Azure DevOps wiki in VS Code the way it looks in the browser.

If you keep your wiki in a Git repo, you already know the gap: you open a page locally and the diagrams are raw text, the table of contents is literal [[_TOC_]], and half the images are broken. azdown closes that gap, so you can read and write wiki pages without switching to the browser to check your work.

It extends VS Code's built-in Markdown preview rather than adding another one, so Ctrl+K V, scroll sync and your theme all keep working exactly as you expect. Everything runs locally against the files already on your disk.

Features

Azure DevOps syntax

• Mermaid diagrams, rendered — both forms Azure DevOps documents: the ::: mermaid container and a ```mermaid fenced block. Drawn in the preview and re-themed when you switch between light and dark. On VS Code 1.121 and later, fenced blocks are left to VS Code's own Mermaid support so the two never render the same block twice.
• ::: video and ::: math containers.
• KaTeX maths — $…$ inline and $$…$$ block, rendered without asking your preview to load anything extra. Prices like $5 and $10 are left alone.
• [[_TOC_]] — table of contents, nested by heading level.
• [[_TOSP_]] — table of subpages, listing the real child pages.
• :shortcode: emoji — the GitHub set Azure DevOps uses, without GitHub's custom ones, and \\:smile: escapes the conversion.
• Heading anchors following the slug algorithm Microsoft documents, including its one published worked example.
• Azure DevOps styling — type scale, heading rules, bordered tables and the boxed table of contents, all drawn from your VS Code theme so light, dark and high-contrast each look right.
• Links between pages work. Azure DevOps writes them without a .md extension and resolves root-absolute ones against the wiki, so locally they normally lead nowhere. Links to headings work too, and a link that resolves to nothing is left exactly as you wrote it.

Wiki-aware

Point azdown at your wiki folder and it understands the things a lone Markdown file cannot express:

• /.attachments/ images resolve. Azure DevOps links attachments root-absolutely, which a plain preview resolves against the wrong folder — the usual cause of broken images when you open a wiki locally.
• A page tree in the activity bar, with pages named the way the wiki names them: Build-And-Release.md shows as "Build And Release", and %2D stays a literal dash.
• .order is respected, so the tree matches your wiki's real page order.
• The tree is for writing, not just reading. The page you are editing stays highlighted, and each page offers edit, preview to the side, copy wiki link, and new subpage — which creates the file and registers it in .order for you.

The wiki root is detected automatically from .order files. Override it with azdown.wikiRoot in User Settings or the folder picker in the panel. The chosen folder is shared across projects in the same VS Code profile on this machine. The picker never writes to .vscode/settings.json or a .code-workspace file, and the path is excluded from Settings Sync.

In Remote - SSH, install azdown on the SSH host. It runs alongside the remote files and keeps a separate wiki list, nicknames and active selection for each server and account. A local macOS path such as /Users/me/Documents/wiki is never imported into that list. Add the server's folder from the Wikis section; it displays SSH: server-name to identify the current environment. Local windows retain their local wikis. Existing remote selections from older versions must be added once again to store them separately.

In WSL, install azdown in the distribution. The Wikis header shows WSL: distribution-name, and selections are saved per distribution and Linux account, independently of Windows, SSH and other distributions. Git runs inside that distribution. If a WSL selection was saved by 0.2.0 under the shared hostname, add it once again to associate it with the distribution.

The Wikis section below Pages lists saved folders by nickname and marks the active one. Click a wiki to use it; hover to see its full path or use the pencil action to rename it directly. The + button adds a folder. The context menu offers Remove from Saved Wikis, which leaves all files on disk.

You can also use Switch Wiki for a searchable picker. Enter an optional nickname when adding a folder; leave it empty to use the folder name. The nickname appears in the picker and beside the panel title, while the full path remains visible in the picker. Use Rename Saved Wiki from the Wikis menu or Command Palette to change or clear a nickname later. Existing saved folders keep working without a nickname. Remove Saved Wikis removes entries from the list without deleting files. Detect Wiki in Workspace returns to automatic detection.

You can select any folder: .order is optional. Markdown pages, subfolders without matching pages and other files appear in the tree. The .attachments folder, hidden repository/editor metadata and node_modules are omitted. Pages open in the preview; other files use their default editor. Previously opened pages retain their own saved wiki's links, images and subpage lists when you switch wikis.

The documentation tree uses the theme's normal foreground, without Git or problem colors and badges. All files use the same generic file icon. Folders keep their folder icon. The first root Markdown page has a house icon: the root .order determines it when present, otherwise the first page alphabetically is Home. Subfolders do not get their own house icon. This follows the documented home-page rule. Open Edit Page to change a page's contents and save in the editor as usual.

The Update Wiki (Pull) button in the Pages header updates the selected wiki with git pull --ff-only. It uses the wiki's own root and the Git installation in the current local, SSH or WSL environment. The folder must be an independent clone with its own .git directory; parent repositories, linked worktrees and submodules are not eligible because they can share metadata with the project. Configure the clone's upstream and authentication using Git in that environment.

Updates stop when files are unsaved, tracked/untracked changes exist, or branches have diverged. Resolve those conditions manually in Git. The action does not commit, push, stash, rebase, run hooks or update submodules. Successful updates refresh the tree and open previews. No Git operation runs automatically while browsing the documentation.

For a wiki outside the workspace, nested pages may need images outside VS Code's allowed preview folders. azdown embeds PNG, JPEG, GIF, SVG, WebP, AVIF, BMP and ICO images from within that wiki when needed, up to 10 MiB per image. Larger images can be viewed by opening the wiki root as a workspace folder. Symbolic links outside the wiki are not embedded. Raw HTML <img> elements are not rewritten.

If you used an earlier version, choose your wiki once to save it globally and remove any old azdown.wikiRoot entry from your project's settings. Workspace values are now ignored. Clear the user setting to return to automatic detection.

Not yet implemented

Being honest about scope:

• [[_TOSP_]] outside a wiki: subpages need a wiki root, so the table stays empty when azdown cannot find one

Settings

Commands

Each page's context menu also offers Edit Page, Open Preview to the Side, Copy Wiki Link, New Subpage, Move Page Up, and Move Page Down. The move actions reorder sibling pages through .order, preserving its newline style and entries for missing pages. They do not move or rename page files. Changes to .order refresh open previews as well as the tree, including for a selected wiki outside the workspace.

Use Change Wiki Folder in a saved wiki's context menu when its folder has moved. Choose the new location in the current local or remote environment; azdown retains the nickname and active selection. A folder already saved as another wiki cannot replace that entry accidentally.

While editing a wiki page, type a Markdown destination such as [Guide](https://github.com/leozamarron/azdown/blob/HEAD/ or invoke Trigger Suggest inside a link. Suggestions insert page paths without .md, including Azure DevOps percent escapes. Relative destinations remain relative, and an existing heading fragment is preserved.

Missing local destinations appear as warnings in the editor and Problems panel. Checks include inline links, images and reference definitions, and refresh when the document changes or a target is created or deleted. Code examples and Mermaid containers are excluded. External URLs and heading existence are not checked. Disable azdown.validateLinks to turn off these warnings. Editor link features skip documents larger than 1 MiB; preview rendering is unaffected.

Known limitations

Heading anchors match the algorithm Microsoft documents, and its one published example. The documentation stops short of specifying what happens to non-Latin scripts, emoji, or punctuation left stranded at the end of a heading, so those may still differ from a live wiki. If you hit a mismatch, open an issue with the heading and the anchor Azure DevOps generated — that is the fastest way to close one.

::: math is supported but is not documented Azure DevOps syntax; Microsoft documents $…$ and $$…$$, which are what you should prefer.

License

MIT