Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
This article describes the files and folder structure for provisioned wikis and wikis published as code. For both types of wiki, the files are stored in a Git repository. Files can include Markdown pages, code, images, attachments, or other artifacts. To establish the presentation sequence of the files, Git adds a special file (.order) in each repo folder.
When you create a project, a wiki isn't created by default. You can provision a wiki, create a README, or publish project code as a wiki.
You create your wiki by using the Azure DevOps user interface. Then you can edit the wiki from your Git repository URL path.
Repository files and folder structure
The Git repository for a wiki has two naming conventions:
- The wiki repo name is
<ProjectName>.wikiwhere<ProjectName>is the name of your project. - The name of the root branch for the wiki repo is
wikiMain.
You manage a wiki repo in the same way you manage other Git repos by defining branch policies on the wikiMain branch. You can also make changes to your local wikiMain branch and push them directly to the remote branch without defining any policies.
A wiki repo consists of the following files and folders:
- A file for each Markdown page located at the root level
- A file named .order located at the root level and also within each subfolder
- A subfolder for each wiki page that has subpages
- A folder named .attachments to store all attachments used in the wiki
File naming conventions
The file name for each wiki page corresponds to the wiki page title. In the file name, a hyphen (-) represents a space in the page title. For example, the page title "How to contribute" corresponds to the file name How-to-contribute.md. The URL path to the wiki page includes the file name. For example, https://github.com/ExampleWiki/How-To/How-to-contribute.md. This approach helps ensure bookmark links to the page remain intact as the wiki changes over time.
Each wiki page corresponds to a file in the wiki Git repository. The following restrictions apply to page file names and the file size:
File name: When choosing a name for the page file, keep in mind that the fully qualified path to the file should be 235 characters or less. The full path to the page consists of the repo URL, the folder path to the page file, and the page file name. For example,
https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md.Uniqueness: The page file name must be unique within its folder ___location in the wiki repo hierarchy. The name is case sensitive.
Special characters: The page file name has restrictions about the following special characters:
- No Unicode control characters or surrogate characters
- No printable characters: forward slash
/, back slash\, hash# - No period
.symbol at the start or end of the name
File size: The maximum page file size is 18 MB.
Attachment file size: The maximum size for any attachment to a page file is 19 MB.
Allowed special characters
Several special characters are allowed in a page file name, such as the colon : and hyphen -. For example, you might name a Markdown file as FAQ:0525 or Setup-Guide.
Important
To avoid errors in page syntax and browser navigation, don't use the space character ( ) in page file names. If you name your page files based on the page title, replace any spaces in the page title with a hyphen (-) in the file name.
The following table lists the special characters allowed in wiki page file names and the corresponding URI encoded string:
| Character | Symbol | URI string |
|---|---|---|
| Colon | : |
%3A |
| Left angle bracket | < |
%3C |
| Right angle bracket | > |
%3E |
| Asterisk (wildcard) | * |
%2A |
| Question mark | ? |
%3F |
| Pipe | | |
%7C |
| Hyphen (dash) | - |
%2D |
| Double quote | " |
%22 |
For example, the file name FAQ:0525 is encoded as FAQ%3A0525.
Page sequence and the .order file
The .order file defines the wiki page sequence. Git looks for this file in each folder to identify the sequence to present files at that ___location. The default page sequence is alphabetical order (A to Z) by file name.
Define custom page sequence
When a folder doesn't have an .order file, Git uses the default alphabetical sequence.
You can define a custom sequence for any folder by updating the .order file in the folder, including at the root level.
The following visual shows an example of a wiki table of contents (TOC) and the corresponding .order file that creates the TOC.
Wiki TOC displays in the web browser
.order file defines the TOC page sequence
The .order file changes the sequence from alphabetical to "Marketing" followed by "Fabrikam Fiber."
For more information about how to reorder wiki pages, see Add, edit, and reorder wiki pages.
Restore alphabetical sequence
If a folder has a custom sequence, you can revert the sort method to alphabetical by following these steps:
Copy the clone URL for the wiki and open it in a browser. The Git repository for the wiki opens.
Go to the .order file that you want to revert and delete the file. After the file is deleted, Git automatically creates a new .order file for that ___location. The new file uses the default sequence.