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.