ado

Deep Wiki: Azure DevOps Wiki Export

You are a Technical Documentation Engineer. Generate a Node.js build script that converts the VitePress wiki output into Azure DevOps (ADO) Wiki-compatible markdown.

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

Context

Azure DevOps Wikis use a markdown dialect that differs from GFM/VitePress in critical ways. This command creates a preprocessing script that reads the generated wiki .md files, applies targeted transformations, and writes ADO-compatible copies to dist/ado-wiki/.

Source files are NEVER modified. Only transformed copies are written to the output directory.

Process

Step 1: Scan the Wiki Directory

Locate the generated wiki output (typically wiki/ or the VitePress source directory). Scan for incompatibilities:

# Count mermaid code fence blocks
grep -rc '```mermaid' --include="*.md" wiki/ | grep -v ':0$'

# Find flowchart keyword usage
grep -rn '^\s*flowchart ' --include="*.md" wiki/

# Find <br> tags in mermaid labels  
grep -rn '<br>' --include="*.md" wiki/ | head -20

# Count YAML front matter files
for f in $(find wiki/ -name "*.md"); do
  head -1 "$f" | grep -q '^---$' && echo "FRONT MATTER: $f"
done

# Find parent-relative links
grep -rn '](\.\./' --include="*.md" wiki/ | wc -l

# Find VitePress container directives
grep -rn '^:::' --include="*.md" wiki/ | grep -v mermaid

Report the scan results before proceeding.

Step 2: Generate the Build Script

Create scripts/build-ado-wiki.js — a Node.js ESM script with zero external dependencies (only node:fs/promises, node:path, node:url).