Azure Wiki Preview

Preview an Azure DevOps Wiki in Obsidian as it will actually publish.

An Azure DevOps Wiki is a git repository of markdown files, so it can be cloned and opened as a vault. The catch is that Azure's markdown dialect differs from Obsidian's in a few places, and the differences are silent: a page looks fine locally and breaks once published, or looks broken locally and is fine. This plugin renders Azure's dialect without changing your source, so what you see is what the wiki will show.

What it handles

:::mermaid diagrams

Azure writes mermaid diagrams as a ::: block, not a fenced code block:

:::mermaid
graph TD
    A[Client] --> B[Gateway]
:::

Obsidian renders that as literal text. The plugin draws it through Obsidian's own mermaid pipeline.

Diagram source is read from the file rather than from the rendered HTML, because markdown mangles it on the way: indentation is stripped, a blank line inside the diagram splits it across several elements, and indented lines are promoted to code blocks. Reading the file avoids all of that.

An unterminated block - a :::mermaid with no closing ::: - is called out inline rather than silently swallowing the rest of the page.

Table of contents macros

[[_TOC_]] and [[_TOSP_]] are real Azure macros, but Obsidian reads them as links to pages that do not exist. They are shown as labelled chips instead.

Headings with no space

CommonMark requires a space after the hashes. Azure does not:

#🌍 Introduction to Location Flow

Azure publishes that as a heading. Obsidian reads it as body text — and as a tag when what follows is tag-shaped. Enable Treat #Heading as a heading to render these the way they will publish. Code blocks are never touched, so shebangs and comments are safe.

Leave this off unless the vault is an Azure Wiki clone. A line like #todo is an ordinary tag in most vaults, and this setting would turn it into a heading.

Encoded page names (off by default)

Azure encodes a page title into its filename: a space becomes -, and reserved characters become percent escapes - including a literal -, which becomes %2D. The result is unreadable in a file explorer:

On disk	Shown
IL-Skeleton-%2D-Standardized-Backend-Library.md	IL Skeleton - Standardized Backend Library
ADR%3A-Retry-Policy.md	ADR: Retry Policy
ai%2Dcortex	ai-cortex

Enable Decode Azure page names in settings to show the decoded form throughout the interface. Hover shows the real filename.

Matching is against the vault's actual file and folder names rather than against any particular pane's markup, so this covers the file explorer, tab titles, breadcrumbs, the quick switcher, backlinks, and third-party navigators — including ones installed after this plugin.

This is display only. Files are never renamed.

Text inside a note is left alone, so a page that quotes a filename keeps quoting it verbatim. The editable title fields show the decoded name too, but the real one is restored the moment the field takes focus, so anything you type edits the filename rather than its display form. That matters because in git a rename is a delete plus an add: it rewrites the page's history and moves its "last updated by" to whoever pushes it.

Leave this setting off unless the vault is an Azure Wiki clone. Decoding reads every - as a space, so in an ordinary vault my-kebab-note would display as my kebab note.

What it does not do

Obsidian builds its own metadata index, and a plugin can only read it. So a heading like #Overview is still recorded as a tag, and will keep appearing in the tag pane, in search, and in the graph — even though it renders correctly as a heading in both reading view and Live Preview. Azure DevOps Wiki has no tagging feature, so these tags do not exist anywhere but in Obsidian's index.

The only way to clear them is to add the space in the source, which makes the heading valid CommonMark and portable everywhere.

Installation

From the community plugins directory

Settings > Community plugins > Browse, then search for "Azure Wiki Preview".

Manually

Copy main.js, manifest.json and styles.css into <vault>/.obsidian/plugins/azure-wiki-preview/, then enable the plugin in Settings > Community plugins.

Troubleshooting

If a diagram does not appear, run Diagnose diagram rendering on the active file from the command palette. It reports how many :::mermaid blocks are in the source, how many containers were created, and how many diagrams were drawn - which separates "the block was not matched" from "mermaid failed to parse it". Per-section detail is written to the developer console.

Development

npm install
npm run dev      # watch build
npm run build    # type-check, then emit main.js

License

MIT