Skip to main content
skill CX Codex

wiki-ado-convert — Claude Code skill: what it does, how to install

wiki-ado-convert builds a Node.js script that turns VitePress and GFM markdown docs into Azure DevOps Wiki format. Fixes Mermaid diagrams, links and front matter before publishing to the wiki.

MIT 4 installs ★ 3,232 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add microsoft/skills --skill wiki-ado-convert -a claude-code
Open on GitHub

What wiki-ado-convert does

The skill leaves source files untouched and instead writes a build script that copies docs into dist/ado-wiki/ with the needed fixes applied. It rewrites Mermaid syntax (for instance swapping flowchart for graph and wrapping code in ::: mermaid instead of a fenced block), drops YAML front matter that ADO would otherwise render as visible text, and turns links pointing at parent-directory source files into plain text, since an ADO wiki sits apart from the code repository.

Before writing the script, it runs git remote get-url origin and asks whether the repository is local-only or has a remote address, so links back to the source stay intact in the converted files. The script itself is a dependency-free ESM module built on Node's own fs, path and url modules, and it skips folders like node_modules, .vitepress, .git, dist and build.

Some Mermaid diagram types render poorly or not at all on Azure DevOps: mind maps, sankey diagrams, quadrant charts and block diagrams won't show up, and links drawn to or from a subgraph get dropped even though nodes inside a subgraph still work.

What it helps with

  • port VitePress markdown docs to Azure DevOps Wiki format
  • fix Mermaid diagram syntax so it renders in ADO
  • strip YAML front matter that ADO displays as raw text
  • turn source-code links into plain text for the wiki
  • generate a conversion script with no npm dependencies

Example prompts for the agent

  • Generate a script that converts our docs to Azure DevOps Wiki format
  • Build the docs into dist/ado-wiki with fixed Mermaid diagrams
  • Check which Mermaid diagrams won't render correctly in Azure DevOps Wiki

How to install wiki-ado-convert

1Skills CLI (Vercel)

npx skills add microsoft/skills --skill wiki-ado-convert -a claude-code

2Manually: put the files in place

~/.claude/skills/wiki-ado-convert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/wiki-ado-convert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about wiki-ado-convert

How do I install wiki-ado-convert in Claude Code?

Run npx skills add microsoft/skills --skill wiki-ado-convert -a claude-code; the skill lands at ~/.claude/skills/wiki-ado-convert/SKILL.md.

What does wiki-ado-convert do?

It generates a Node.js script that copies markdown docs into dist/ado-wiki/ while rewriting Mermaid syntax, removing front matter, and fixing source-code links so the files display correctly in Azure DevOps Wiki.

Which Mermaid diagrams does Azure DevOps Wiki not support?

As of 2025, ADO can't render mind maps, sankey diagrams, quadrant charts, xy charts or block diagrams, and links between subgraphs are dropped even though nodes inside a subgraph still display fine.

Source text

SKILL.md · MIT
---
name: wiki-ado-convert
description: 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/.
license: MIT
metadata:
  author: Microsoft
  version: "1.0.0"
---

# ADO Wiki Converter

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/`.

## Source Repository Resolution (MUST DO FIRST)

Before generating the build script, resolve the source repository context:

1. **Check for git remote**: Run `git remote get-url origin`
2. **Ask the user**: _"Is this a local-only repository, or do you have a source repository URL?"_
   - Remote URL → store as `REPO_URL`, preserve linked citations in converted output
   - Local → preserve local citations as-is
3. **Do NOT proceed** until resolved

## Why This Is Needed

Azure 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.

## ADO Wiki Incompatibilities

### CRITICAL — Will Break Rendering

| 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]` |

### MODERATE — May Not Render Optimally

| 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. |

### NOT AN ISSUE (Compatible As-Is)

- ✅ Standard markdown tables, blockquotes, horizontal rules
- ✅ Unicode emoji, fenced code blocks with language identifiers
- ✅ Same-directory relative links (`./other-page.md`)
- ✅ External HTTP/HTTPS links
- ✅ Bold, italic, strikethrough, inline code
- ✅ Lists (ordered, unordered, nested), headings 1-6
- ✅ Images with relative paths

## ADO Wiki Mermaid Supported Diagram Types

As of 2025:
- ✅ `sequenceDiagram`, `gantt`, `graph` (NOT `flowchart`), `classDiagram`
- ✅ `stateDiagram`, `stateDiagram-v2`, `journey`, `pie`, `erDiagram`
- ✅ `requirementDiagram`, `gitGraph`, `timeline`
- ❌ `mindmap`, `sankey`, `quadrantChart`, `xychart`, `block`

## Build Script Structure

The 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.

### Transformation Functions

#### 1. Strip YAML Front Matter

Remove `---` delimited YAML blocks at file start. ADO renders these as visible text.

```javascript
function stripFrontMatter(content) {
  if (!content.startsWith('---')) return content;
  const endIndex = content.indexOf('\n---', 3);
  if (endIndex === -1) return content;
  let rest = content.slice(endIndex + 4);
  if (rest.startsWith('\n')) rest = rest.slice(1);
  return rest;
}
```

#### 2. Convert Mermaid Blocks

Process line-by-line, tracking mermaid block state. Apply fixes ONLY inside mermaid blocks:

- Opening: ` ```mermaid ` → `::: mermaid`
- Closing: ` ``` ` → `:::`
- `flowchart` → `graph` (preserve direction: TD, LR, TB, RL, BT)
- Strip `<br>`, `<br/>`, `<br />` (replace with space)
- Replace long arrows (`---->` with 4+ dashes) with `-->`

```javascript
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');
}
```

#### 3. Convert Parent-Relative Source Links

Convert `[text](../path)` to plain text. Preserves same-directory `.md` links and external URLs.

```javascript
function convertSourceLinks(content) {
  return content.replace(
    /\[([^\]]*)\]\(\.\.\/[^)]*\)/g,
    (match, linkText) => linkText
  );
}
```

#### 4. Convert VitePress Container Directives (Optional)

Convert `::: tip` / `::: warning` / `::: danger` to ADO alert blockquotes:

```javascript
function convertContainerDirectives(content) {
  // ::: tip → > [!TIP]
  // ::: warning → > [!WARNING]
  // ::: danger → > [!CAUTION]
  // ::: info → > [!NOTE]
  // closing ::: → (blank line)
}
```

### Script Main Flow

```javascript
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
}
```

### Skip Directories

The script should skip: `node_modules`, `.vitepress`, `.git`, `dist`, `build`, `out`, `target`, and any non-documentation directories.

### npm Script Integration

```json
{
  "scripts": {
    "build:ado": "node scripts/build-ado-wiki.js"
  }
}
```

## Verification Checklist

After the script runs, verify:
1. File count in `dist/ado-wiki/` matches source (minus skipped dirs)
2. Zero ` ```mermaid ` fences remaining — all converted to `::: mermaid`
3. Zero `flowchart` keywords remaining — all converted to `graph`
4. No YAML front matter in output files
5. Parent-relative links converted to plain text
6. Same-directory `.md` links preserved
7. Directory structure preserved
8. Non-markdown files (images, etc.) copied as-is
9. `index.md` at root is a proper wiki home page (NOT a placeholder)

## Index Page Generation (CRITICAL)

The ADO Wiki's `index.md` **MUST be a proper wiki landing page**, NOT a generic placeholder with "TODO" text.

### Logic

1. **If VitePress source has `index.md`**: Transform it (strip front matter, strip VitePress hero/features blocks). If meaningful content remains, use it.
2. **If no meaningful content remains** (empty after stripping, or only VitePress hero markup): Generate a proper landing page with:
   - Project title as `# heading`
   - Overview paragraph (from README or wiki overview page)
   - Quick Navigation table (Section, Description columns linking to wiki sections)
   - Links to onboarding guides if they exist
3. **NEVER leave a placeholder** — if `index.md` contains "TODO:", "Give a short introduction", or similar placeholder text, **replace it entirely**

### ADO Wiki `.order` Files

Generate `.order` files in each directory to control sidebar ordering:
- Onboarding guides first, then numbered sections
- List page names without `.md` extension, one per line

## Citation & Diagram Preservation

The converted ADO wiki must maintain the same quality standards:

- **Linked citations** (`[file:line](URL)`) are standard markdown — preserve them as-is
- **`<!-- Sources: ... -->` comment blocks** after Mermaid diagrams — preserve (HTML comments work in ADO)
- **Tables with "Source" columns** — preserve as-is (standard markdown tables)
- **Mermaid diagrams** — convert fences only; diagram content, types, and structure are preserved
- All Mermaid diagram types supported by ADO (graph, sequenceDiagram, classDiagram, stateDiagram, erDiagram, etc.) pass through unchanged

## Important Notes

- **Source files are NEVER modified** — only copies in `dist/ado-wiki/`
- **Images must be copied too** — if source has images, copy them with same relative paths
- The script should work with **any VitePress wiki**, not just this specific one
- Print statistics at the end showing count of each transformation type
- Script uses zero external dependencies — only Node.js builtins

© Microsoft · MIT · microsoft/skills

Similar skills

All skills for Writing and docs →

From the same set250

The whole set →
azure-identity-rust azure-identity-rust — a skill that tells your agent how to wire Microsoft Entra ID into a Rust app: which credential fits local work and which one belongs in production. CX Codex +1 5installs azure-eventhub-rust azure-eventhub-rust guides Claude Code and GitHub Copilot on using the official azure_messaging_eventhubs Rust crate. Useful for event streaming, batching, and partition reads. CX Codex +1 5installs azure-cosmos-rust azure-cosmos-rust tells the agent how to talk to Azure Cosmos DB NoSQL API from Rust: item CRUD, containers, partition keys, and credentials. CX Codex +1 5installs pydantic-models-py pydantic-models-py — a skill that lays out Pydantic v2 models in five variants: Base, Create, Update, Response and InDB. Useful when you need request and response schemas for an API. CX Codex +1 5installs azure-validate The azure-validate skill for Claude Code and GitHub Copilot checks whether an Azure project is ready to deploy. It runs preflight checks on configuration, infrastructure, and access permissions. CX Codex +1 4installs azure-deploy azure-deploy — a skill for Claude Code and GitHub Copilot that runs deployments of already-prepared apps to Azure. CX Codex +1 4installs fastapi-router-py The fastapi-router-py skill builds FastAPI routers with CRUD handlers, auth dependencies, and response models. Use it when adding REST endpoints or protected routes. CX Codex +1 4installs azure-storage Manages Azure Storage services, access tiers, and blob transfers directly from coding assistants. Useful when provisioning cloud storage or writing SDK code. CX Codex +1 3installs

More in the catalog

Project sponsors

Companies that keep this analytics open