Azure DevOps Wiki's New Editor: An Admin Rollout Guide

The Azure DevOps Wiki editor has always been the part of the product people tolerate rather than enjoy. Undo that forgets half your changes, no proper find and replace, and Markdown that looks like plain text until you hit preview. On 8 October 2026 Microsoft announced a replacement built on Monaco, the same editor that powers VS Code, and it is now in public preview.

If you administer an Azure DevOps organization, that leaves you with a small but real decision: turn it on for everyone, wait, or pilot it first. And if your team keeps its Definition of Done on a wiki page, it is also a good moment to ask whether that page is doing any work at all.

In this guide I cover what actually changes, how to enable it per user or for the organization, what to test on your existing pages, how to use the new autocomplete to tie the wiki to Boards, and where a wiki page stops being enough.

What the new wiki editor actually changes

The official announcement on the Azure DevOps blog describes it as a replacement of the existing editor, not an optional extra. During the preview you opt in; the direction of travel is clear.

Monaco under the hood

Monaco gives the wiki the editing basics developers already expect from VS Code:

• Syntax highlighting for Markdown, so headings, links and code blocks are readable while you type.
• Line numbers, which sound trivial until you are pairing on a long runbook and want to say "check line 84".
• Native find and replace, so renaming a service or an environment across a page no longer means copy, paste and hope.

Undo that finally behaves

Microsoft calls out improved undo and redo for formatting, pasting, attachments and autocomplete. In the old editor, undo after pasting a screenshot or applying formatting was unpredictable enough that many people simply stopped trusting it. Reliable undo is the least glamorous change and probably the one your team will notice first.

Autocomplete that connects the wiki to the rest of Azure DevOps

This is the change I care about most. The new editor triggers suggestions on:

• # for work items
• @ for people
• ! for pull requests
• plus suggestions for wiki links and templates

Linking work items and mentioning people already worked in the wiki, but the suggestions now live inside a real editor rather than a text box with extras. That lowers the effort of linking, and links are what turn a wiki from a document dump into something that stays connected to the work.

What stays the same

The announcement says the new editor keeps the existing editor's functionality. Your pages are still Markdown, so the syntax documented in Microsoft Learn's Markdown guidance for Azure DevOps still applies: [[_TOC_]] for a table of contents, [[_TOSP_]] for a list of child pages, query-table blocks for live Boards query results, and Mermaid diagrams. The editor changes; the content format does not.

Enabling it: per user or for the whole organization

The new editor sits under Preview features. How that switch works matters for your rollout.

How preview features work

According to Microsoft's documentation on managing preview features:

• Any user with at least Basic access can turn a preview feature on or off for themselves via the profile menu and Manage features.
• Only Project Collection Administrators can turn a feature on for the whole organization.
• When an admin turns a feature on at organization level, it applies to everyone, but individuals can still turn it off for themselves.
• Turning it off at organization level does not override users who switched it on personally.

Once enabled, the new editor applies to all wiki pages for that user.

Why I would start with a pilot group

Because individuals can opt in on their own, you do not need an organization-wide switch to learn anything. My approach:

1. Ask the people who edit the wiki most (usually tech leads, the scrum master and whoever owns the runbooks) to enable it for themselves.
2. Let them use it for a week on real pages.
3. Only then flip it for the organization, knowing anyone who hits a problem can still switch back personally.

That turns "a preview feature changed my editor overnight" into "the people who live in the wiki already vouched for it".

What to test on your existing pages first

Microsoft does not list known limitations, and the feature is new. That is not a reason to wait, but it is a reason to spend thirty minutes checking the pages you depend on. Open each of these in the new editor, make a small edit, save, and compare the rendered result:

• Pages with [[_TOC_]] and nested headings. Note the tag is case-sensitive.
• Pages with query-table blocks that show live Boards results, such as a release status page.
• Mermaid diagrams, especially larger architecture or sequence diagrams.
• Pages with attachments and pasted images, since attachment handling is one of the areas Microsoft reworked.
• Your longest pages, where performance differences show first.
• Tables containing work item or pull request mentions. Microsoft's guidance is to put a blank space before and after a mention inside table text.
• Pages with hex colour codes or other literal # characters, which can now trigger work item suggestions.

If something looks wrong, report it through the feedback channels named in the announcement. That is exactly what a public preview is for.

Make the wiki part of Boards with #, @ and !

Most team wikis decay for one reason: pages are not connected to the work. A decision record that never mentions the user story it came from is impossible to find six months later. Faster autocomplete is a good excuse to fix that habit.

Link decisions and runbooks to the work they belong to

A few patterns that work well:

• Decision records: start every page with the work item that triggered the decision (# plus the ID) and the pull request that implemented it (!).
• Runbooks: mention the owning person or team with @, so it is obvious who to ask when the runbook is wrong.
• Release notes pages: combine a query-table block for the live list with a short written summary that links the few work items worth explaining.
• Onboarding pages: link to the Boards queries and repos a new developer actually needs, instead of describing them in prose that goes stale.

Gotchas worth knowing

• Any literal # followed by text can trigger work item suggestions. Microsoft's guidance is to escape it with a backslash, for example in colour codes.
• When you edit a page directly in Git rather than through the editor, mentions are stored as @<{identity-guid}>, not as readable names. Keep that in mind if you generate wiki pages from scripts.

Templates for DoR, DoD and runbooks people actually reuse

The announcement lists autocomplete for templates alongside work items and people. Whether or not you use that feature, the bigger win is agreeing on what a good process page contains. For a Definition of Ready, Definition of Done or runbook page, I use this skeleton:

• Owner (an @ mention) and last reviewed date at the top.
• Purpose in two sentences: when this applies and when it does not.
• The actual list, short enough to read in a minute.
• A live query-table showing work items that are in scope right now, so the page points at real work.
• Change history: link the work item or pull request (#, !) behind each change.

A page with an owner and a review date gets maintained. A page without them becomes the 2024 DoD page nobody has opened since it was written.

Where a wiki page stops helping: documenting vs enforcing

This is the part most wiki guides skip, and it is where I spend my time as an extension builder.

A DoD page does not stop a story moving to Done

A wiki page is excellent at explaining a rule: why the team has it, what each item means, what good looks like. It is useless at enforcing it. Nothing in Azure Boards reads your Definition of Done page before someone drags a user story into Done. The page and the work item live side by side and never talk to each other.

I wrote about this gap in Make "Done" Mean Done in Azure DevOps Boards: teams with a beautifully written DoD still ship stories without tests or docs, simply because the rule sits one click away from where the decision happens.

Put the rule on the work item

The fix is to keep the explanation in the wiki and move the checklist onto the work item. That is why I built the Checklist Extension for Azure DevOps. It adds reusable checklist templates to work items, tracks progress, and can block a state transition until the checklist is complete, with an audit trail of who ticked what.

The two work well together:

• The wiki page holds the why, the examples and the history, linked with # to the work items it governs.
• The checklist on the work item holds the short, tickable version and makes sure it is actually done.

If you are still shaping the content of the list itself, my Definition of Done example guide is a good starting point.

A one-week rollout plan

• Day 1: Enable the new editor for yourself and two or three heavy wiki editors.
• Day 2: Run the test list above on your ten most important pages.
• Day 3: Agree on the process page skeleton and update your DoR and DoD pages to it.
• Day 4: Add # and ! links to your most recent decision records and runbooks.
• Day 5: Enable the editor for the organization and post a short note to the teams: what changed, how to switch back personally, and where to report issues.
• Following sprint: Move your Definition of Done from "page we link to" to "checklist on the work item".

Conclusion

The new Monaco-based wiki editor is a quality-of-life upgrade that is easy to adopt: better highlighting, real find and replace, undo you can trust, and autocomplete that makes linking wiki pages to work items and pull requests almost free. Pilot it with your heaviest editors, test the pages you depend on, and then turn it on for everyone.

Use the moment for one more improvement. Keep the wiki for explaining your process and move the rules that matter onto the work items themselves. If your Definition of Done currently lives only on a wiki page, install the free Checklist Extension from the Visual Studio Marketplace and turn that page into a checklist your board actually respects.

Frequently asked questions