Edit

Wiki files and file structure

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Learn about the files and file structure for project wikis and code wikis. The following guidance might specify code wikis, but it applies to both types of wiki.

When you create a team project, a wiki isn't created by default. For more information, see Create a wiki, Create a README, or Provisioned wikis vs. published code as a wiki.

Each code wiki is powered by a Git repository in the back-end. This repository stores the Markdown pages, images, attachments, and the sequence of pages and subpages. You create your wiki via the Azure DevOps user interface, and then you can edit the wiki via your Git repository URL path. For more information about publishing code wikis, see Publish a Git repository to a wiki.

Wiki file and folder structure

The team project wiki Git repositories are assigned the following labels.

  • Wiki repo for a team project: ProjectName.wiki
  • Main branch: wikiMain

Manage your wiki repo in the same way you manage any other Git repo, by defining branch policies on the wikiMain branch. But, you can make changes to your local wikiMain branch and push them directly to the remote branch without defining any policies.

The wiki repository has the following files and folders:

  • File for each Markdown page entered at the root level
  • File labeled .order at the root and under each folder
  • Folder for each page that has subpages
  • .attachments folder, storing all the attachments of the wiki

File naming conventions

Each file requires using hyphens instead of spaces in the page title. For example, the How to contribute page title corresponds to the How-to-contribute.md file name. The page name gets added to the URL, ensuring that links you share remain intact as the wiki changes over time.

Each wiki page corresponds to a file within the wiki Git repo. Names you assign to a wiki page title must conform to the following restrictions.

Restriction type Restriction
File name The fully qualified page path shouldn't exceed 235 characters.
Uniqueness Page titles are case sensitive and must be unique within the wiki hierarchy.
Special characters - Must not contain any Unicode control characters or surrogate characters.
- Must not contain the following printable characters: / \ #.
- Must not start or end with a period ..
File size Must not exceed the maximum of 18 MB.
Attachment file size Must not exceed the maximum of 19 MB.

Special characters in Wiki page titles

You can specify page titles which contain one or more of these special characters : < > * ? | -. For example, you can name a Markdown file as "FAQ?" or "Set-up guide". The characters have the following URI encoded strings:

Character Encoded string
: %3A
< %3C
> %3E
* %2A
? %3F
| %7C
- %2D
" %22

.order file

The .order file defines the sequence of pages within the wiki. The following visual shows an example of a wiki TOC and it's corresponding .order file.

Wiki TOC .order file
Screenshot of wiki TOC example. Screenshot of Wiki example order file.

The default hierarchy is in alphabetical sequence, however you can change this hierarchy in the .order file. For more information about how to reorder wiki pages, see Add and edit wiki pages, Reorder a wiki page.

Delete the .order file to revert to alphabetical sorting

When there's no .order file the pages get sorted alphabetically. To revert to alphabetical sorting, do the following steps:

  1. Copy the clone URL for the wiki and open it in a browser. Doing so opens the Git repository (files hub), which backs the wiki.
  2. Go to the .order file and delete it. The file gets automatically (re)created after deletion, for example, in a drag and drop action on an article.