npx skills add ...
npx skills add microsoft/skills --skill wiki-ado-convert
npx skills add microsoft/skills --skill wiki-ado-convert
Converts VitePress/GFM wiki markdown to Azure DevOps Wiki-compatible format. Generates a Node.js build script that transforms Mermaid syntax, strips front matter, fixes links, and outputs ADO-compatible copies to dist/ado-wiki/.
Generate a Node.js build script that transforms VitePress/GFM markdown documentation into Azure DevOps Wiki-compatible format. The source files remain untouched — the script produces transformed copies in dist/ado-wiki/.
Before generating the build script, resolve the source repository context:
git remote get-url originREPO_URL, preserve linked citations in converted outputAzure DevOps Wikis use a markdown dialect that differs from GFM and VitePress in several critical ways. Documentation that renders perfectly in VitePress will have broken diagrams, raw front matter, dead links, and rendering issues when published as an ADO Wiki.
| Issue | VitePress/GFM | ADO Wiki | Fix |
|---|---|---|---|
| Mermaid code fences | ```mermaid ... ``` | ::: mermaid ... ::: | Convert opening/closing fences |
flowchart keyword | flowchart TD | graph TD | Replace flowchart with graph (preserve direction) |
<br> in Mermaid labels | Node[Label<br>Text] | Not supported | Strip <br> variants (replace with space) |
Long arrows ----> | A ---->B | Not supported | Replace with --> |
| YAML front matter | --- ... --- at file start | Rendered as visible raw text | Strip entirely |
| Parent-relative source links | [text](../../src/file.cs) | Broken (wiki is separate) | Convert to plain text |
| VitePress container directives | ::: tip / ::: warning | Not supported | Convert to ADO alert blockquotes > [!TIP] / > [!WARNING] |
| Issue | Notes |
|---|---|
Mermaid style directives | ADO's Mermaid version may ignore inline styling. Leave as-is (cosmetic). |
Mermaid thick arrows ==> | May work. Leave as-is. |
Mermaid dotted arrows -.-> | May work. Leave as-is. |
| Subgraph linking | Links to/from subgraphs not supported, but nodes inside subgraphs work fine. |
./other-page.md)As of 2025:
sequenceDiagram, gantt, graph (NOT flowchart), classDiagramstateDiagram, stateDiagram-v2, journey, pie, erDiagramrequirementDiagram, gitGraph, timelinemindmap, sankey, quadrantChart, xychart, blockThe generated script should be a Node.js ESM module (scripts/build-ado-wiki.js) using only built-in Node.js modules (node:fs/promises, node:path, node:url). No external dependencies.
Remove --- delimited YAML blocks at file start. ADO renders these as visible text.
Process line-by-line, tracking mermaid block state. Apply fixes ONLY inside mermaid blocks:
```mermaid → ::: mermaid``` → :::flowchart → graph (preserve direction: TD, LR, TB, RL, BT)<br>, <br/>, <br /> (replace with space)----> with 4+ dashes) with -->Convert [text](../path) to plain text. Preserves same-directory .md links and external URLs.
Convert ::: tip / ::: warning / ::: danger to ADO alert blockquotes:
The script should skip: node_modules, .vitepress, .git, dist, build, out, target, and any non-documentation directories.
After the script runs, verify:
dist/ado-wiki/ matches source (minus skipped dirs)```mermaid fences remaining — all converted to ::: mermaidflowchart keywords remaining — all converted to graph.md links preservedindex.md at root is a proper wiki home page (NOT a placeholder)The ADO Wiki's index.md MUST be a proper wiki landing page, NOT a generic placeholder with "TODO" text.
index.md: Transform it (strip front matter, strip VitePress hero/features blocks). If meaningful content remains, use it.# headingindex.md contains "TODO:", "Give a short introduction", or similar placeholder text, replace it entirely.order FilesGenerate .order files in each directory to control sidebar ordering:
.md extension, one per lineThe converted ADO wiki must maintain the same quality standards:
[file:line](URL)) are standard markdown — preserve them as-is<!-- Sources: ... --> comment blocks after Mermaid diagrams — preserve (HTML comments work in ADO)dist/ado-wiki/function convertMermaidBlocks(content) {
const lines = content.split('\n');
const result = [];
let inMermaid = false;
for (const line of lines) {
const trimmed = line.trimEnd();
if (!inMermaid && /^```mermaid\s*$/.test(trimmed)) {
result.push('::: mermaid');
inMermaid = true;
continue;
}
if (inMermaid && /^```\s*$/.test(trimmed)) {
result.push(':::');
inMermaid = false;
continue;
}
if (inMermaid) {
let fixed = line;
fixed = fixed.replace(/^(\s*)flowchart(\s+)/, '$1graph$2');
fixed = fixed.replace(/<br\s*\/?>/gi, ' ');
fixed = fixed.replace(/-{4,}>/g, '-->');
result.push(fixed);
} else {
result.push(line);
}
}
return result.join('\n');
}function convertSourceLinks(content) {
return content.replace(
/\[([^\]]*)\]\(\.\.\/[^)]*\)/g,
(match, linkText) => linkText
);
}function convertContainerDirectives(content) {
// ::: tip → > [!TIP]
// ::: warning → > [!WARNING]
// ::: danger → > [!CAUTION]
// ::: info → > [!NOTE]
// closing ::: → (blank line)
}async function main() {
const files = await collectMarkdownFiles(ROOT);
const stats = { frontMatter: 0, mermaid: 0, sourceLinks: 0, containers: 0 };
for (const filePath of files) {
let content = await readFile(filePath, 'utf-8');
content = stripFrontMatter(content);
content = convertMermaidBlocks(content);
content = convertSourceLinks(content);
const outPath = join(OUTPUT, relative(ROOT, filePath));
await mkdir(dirname(outPath), { recursive: true });
await writeFile(outPath, content, 'utf-8');
}
// Print transformation statistics
}{
"scripts": {
"build:ado": "node scripts/build-ado-wiki.js"
}
}