Wiki Ado Convert

職業

分類

Full Stack

ADO Wiki Incompatibilities

CRITICAL — Will Break Rendering

MODERATE — May Not Render Optimally

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.

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

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.

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

4. Convert VitePress Container Directives (Optional)

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

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

Script Main Flow

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

{
  "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