Wiki files and file structure
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
.orderat the root and under each folder - Folder for each page that has subpages
.attachmentsfolder, 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 |
|---|---|
|
|
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:
- 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.
- 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.