Wiki Git repository files and file structure

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

When you create a team project, a Wiki Git repo isn't created by default. To start using a Wiki, you must first provision it. Each 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.

Wiki file and folder structure

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

  • Wiki repo for a team project: ProjectName.wiki
  • Master branch: wikiMaster

Note

You can manage your Wiki repo in the same way you manage any other Git repo, by defining branch policies on the wikiMaster branch. However, you can make changes to your local wikiMaster 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 dashes 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 is 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
  1. Must not contain any Unicode control characters or surrogate characters
  2. Must not contain the following printable characters: / \ #
  3. 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 following characters are translated to their URI encoded strings:

Character Encoded string
: %3A
< %3C
> %3E
* %2A
? %3F
| %7C
- %2D
" %22
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
  1. Must not contain any Unicode control characters or surrogate characters
  2. Must not contain the following printable characters: / : < \ * ? \ | - #
  3. Must not start or end with a period (.)
  4. Titles of pages added offline must not contain a blank space.
File size Must not exceed the maximum of 18 MB
Attachment file size Must not exceed the maximum of 19 MB

.order file

The .order file is used to set the order of the Wiki pages in a particular hierarchy. With order files, you can set your own order for the Wiki pages according to the information flow on that hierarchy.

For example, the images below show the default order for a hierarchy, which is in alphabetical order and the order in which the content needs to be arranged for a logical information flow.

Wiki page hierarchy without .order file Wiki page hierarchy with .order file

To change the order of the Wiki pages in the hierarchy, the .order file is required at the same level of the pages.

Order file in repo

The content of the order file contains the list of files in the required order (without the ".md" extension). In this case, it is as follows:

Home
Readme
Boards
Pipelines
Test
Wiki
More-Articles

When there's no .order file the pages are 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 Repo (Files Hub), which backs the Wiki.
  2. Navigate to the .order file and delete it. The .order file is automatically (re)created after deletion, for example, in a drag and drop action on an article.