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:

Type	Description	Use Case
Provisioned Wiki	Built-in wiki created per project	Quick team documentation, single wiki per project
Published Code Wiki	Git repo published as wiki	SDK docs, versioned content, multiple wikis per project

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

Practice	Description
Flat hierarchy	Keep max 3 levels deep for easy navigation
Consistent naming	Use kebab-case: api-reference, getting-started
Logical grouping	Group related pages in subfolders
Index pages	Create overview pages for each section
Home page	Always have a clear entry point

Content Guidelines

Practice	Description
Use TOC	Add [[_TOC_]] to pages with multiple sections
Descriptive titles	Use clear, searchable page titles
Cross-linking	Link related pages for discoverability
Keep updated	Archive outdated content, don't delete
Diagrams	Use Mermaid for architecture/flow visualization

File Naming

Do	Don't
getting-started.md	Getting Started.md (spaces)
api-v2-reference.md	api_v2_reference.md (underscores)
faq.md	FAQ.md (uppercase)

Searchability

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

Provisioned vs Code Wiki Comparison

Feature	Provisioned	Code Wiki
Multiple wikis per project	No (1 only)	Yes
Versioning	Git history	Git branches
Edit from Repos	No	Yes
Branch policies	Limited	Full support
Revert from wiki UI	Yes	No (use Git)
Best for	Team docs	SDK/Product docs

Troubleshooting

Issue	Solution
Page not appearing	Check .order file includes page name
Broken links	Use relative paths: ./subpage or /absolute/path
Images not showing	Upload to .attachments/ folder
TOC not rendering	Ensure [[_TOC_]] is on its own line
Mermaid not working	Use graph instead of flowchart
YAML metadata broken	Check for proper --- delimiters

File Restrictions

Restriction	Limit
Page file size	18 MB max
Attachment size	19 MB max
Path length	235 characters max
Special chars in names	No /, \, #
Period in names	Not at start/end

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

---

Gotchas

• .order file determines tab order — a misspelled entry hides the file from navigation; the file exists but is invisible.
• Nested folders require dual .order files: parent's lists the folder, folder's own lists pages. Missing either breaks navigation.
• Mermaid renders only via fenced ```mermaid blocks — inline Mermaid syntax in regular markdown isn't rendered (no error, just plain text).
• Personal Wiki vs Project Wiki have DIFFERENT git URLs — clone the wrong one and pushes go to the wrong wiki silently.
• TOC [[_TOC_]] generates from headings; subheadings >6 deep are dropped — long docs lose the bottom of the nav.
• Code Wiki vs Provisioned Wiki: code wiki syncs from a repo; provisioned wiki edits in place. Switching loses formatting differences silently.