Azure Devops Wiki

name: azure-devops-wiki description: Azure DevOps Wiki management skill. Use when working with Azure DevOps wikis for: (1) Creating and organizing wiki pages - provisioned or code-as-wiki, (2) Markdown formatting - TOC, Mermaid diagrams, YAML metadata, code blocks, (3) Wiki structure - .order files, subpages, attachments, (4) Best practices - naming conventions, navigation, searchability, (5) CLI operations - az devops wiki commands, (6) Git-based wiki workflows - clone, edit offline, push changes. Supports both provisioned wikis and published code wikis.

Azure DevOps Wiki Skill

Complete guide for managing Azure DevOps wikis with best practices and CLI operations.

Wiki Types

Azure DevOps supports two wiki types:

Quick Start

Create Provisioned Wiki

# Via Azure DevOps CLI
az devops wiki create --name "Project Wiki" --type projectwiki \
  --org https://dev.azure.com/ORG --project PROJECT

Publish Code as Wiki

# Publish existing Git repo as wiki
az devops wiki create --name "API Docs" --type codewiki \
  --repository REPO_NAME --mapped-path / --version main \
  --org https://dev.azure.com/ORG --project PROJECT

Repository Structure

Wiki files are stored in Git with this structure:

ProjectName.wiki/
├── .attachments/           # All attachments
├── .order                  # Root page sequence
├── Home.md                 # Home page
├── Getting-Started.md      # Top-level page
├── Getting-Started/        # Folder for subpages
│   ├── .order              # Subpage sequence
│   ├── Installation.md     # Subpage
│   └── Configuration.md    # Subpage
└── API-Reference.md        # Another top-level page

Key conventions:

• Wiki repo name: <ProjectName>.wiki
• Root branch: wikiMain
• Spaces in titles → hyphens in filenames: Getting Started → Getting-Started.md
• Subpages require matching folder: Page.md + Page/ folder

The .order File

Controls page sequence in table of contents:

Home
Getting-Started
API-Reference
Troubleshooting

Rules:

• One page name per line (without .md extension)
• Pages not listed appear alphabetically at the end
• Delete .order to restore alphabetical sorting

Essential Markdown Features

Table of Contents

Add auto-generated TOC to any page:

[[_TOC_]]

## Section 1
Content here...

## Section 2
More content...

Mermaid Diagrams

::: mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
:::

Supported diagram types:

• Sequence diagrams
• Flowcharts (graph not flowchart)
• Gantt charts
• Class diagrams
• State diagrams
• User journeys
• Pie charts
• Entity Relationship diagrams
• Timeline diagrams

YAML Metadata

Add searchable metadata at page start:

---
title: API Reference
author: Team Name
tags:
  - api
  - reference
  - v2
---

# Page Content

Code Blocks with Syntax Highlighting

```javascript
const config = {
  baseUrl: 'https://api.example.com',
  timeout: 5000
};

Supported languages: `javascript`, `typescript`, `python`, `csharp`, `bash`, `yaml`, `json`, `sql`, and [more](https://github.com/highlightjs/highlight.js/tree/stable-11/src/languages).

### Collapsible Sections

```html
<details>
<summary>Click to expand</summary>

Hidden content here...

</details>

Work Item Links

Link to work item: #123
Link with text: [User Story #123](#123)

User Mentions

@<alias> - mentions user
@<GroupName> - mentions group

Images with Sizing

![Alt text](/.attachments/image.png =500x300)
![Width only](/.attachments/image.png =500x)

CLI Operations

List Wikis

az devops wiki list --org https://dev.azure.com/ORG --project PROJECT -o table

Create Page

az devops wiki page create --wiki "Project Wiki" --path "NewPage" \
  --content "# Page Title\n\nPage content here" \
  --org https://dev.azure.com/ORG --project PROJECT

Update Page

az devops wiki page update --wiki "Project Wiki" --path "ExistingPage" \
  --content "Updated content" --version ETAG \
  --org https://dev.azure.com/ORG --project PROJECT

Delete Page

az devops wiki page delete --wiki "Project Wiki" --path "PageToDelete" \
  --org https://dev.azure.com/ORG --project PROJECT -y

Show Page

az devops wiki page show --wiki "Project Wiki" --path "PageName" \
  --org https://dev.azure.com/ORG --project PROJECT

Git-Based Workflow

Clone Wiki Locally

# Get wiki clone URL
az devops wiki show --wiki "Project Wiki" \
  --org https://dev.azure.com/ORG --project PROJECT \
  --query remoteUrl -o tsv

# Clone
git clone https://dev.azure.com/ORG/PROJECT/_git/PROJECT.wiki
cd PROJECT.wiki

Edit and Push

# Create/edit pages
echo "# New Page\n\nContent" > New-Page.md

# Update .order
echo -e "Home\nNew-Page\nExisting-Page" > .order

# Commit and push
git add .
git commit -m "Add new documentation page"
git push origin wikiMain

Best Practices

Structure & Organization

Content Guidelines

File Naming

Searchability

• Add YAML metadata with tags
• Use descriptive headings
• Include keywords in content
• Link work items for context

Provisioned vs Code Wiki Comparison

Troubleshooting

File Restrictions

Scripts

• scripts/wiki-clone.sh <project> <wiki-name> - Clone wiki repository
• scripts/wiki-publish.sh <project> <repo> <path> - Publish repo as wiki

References

For detailed documentation:

• references/best-practices.md - Comprehensive best practices guide
• references/markdown-syntax.md - Complete Markdown reference
• Official Azure DevOps Wiki Docs