Skip to content

wiki-file-structure.md

Latest commit

 

History

History
106 lines (70 loc) · 5.46 KB

wiki-file-structure.md

File metadata and controls

106 lines (70 loc) · 5.46 KB
title Wiki Files, Folder Structure, Git Repo Conventions
titleSuffix Azure DevOps
description Explore the file and folder structure for provisioned wikis or wikis published as code in Azure DevOps, including naming and location conventions for the Git repository.
ms.subservice azure-devops-wiki
ms.custom wiki, devdivchpfy22
ms.topic concept-article
ms.author chcomley
ms.reviewer gopinach
author chcomley
ms.date 09/25/2025

Wiki file and folder structure in Git

[!INCLUDE version-lt-eq-azure-devops]

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>.wiki where <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.

[!INCLUDE temp]

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.

Important

When a parent folder contains only subfolders and no files of its own, the wiki displays the parent folder as blank—even if the subfolders include markdown files. To ensure visibility of markdown files within subfolders, always place at least one file (such as a .order file or any other file with content) in the parent folder.

|- parent-folder
|-- sub-folder1
|   |-- file1.md
|   |-- file2.md
|-- sub-folder2
|   |-- file3.md
|   |-- file4.md
|-- .order

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.

:::row::: :::column span="":::

Wiki TOC displays in the web browser

:::image type="content" source="media/wiki/wiki-toc-example.png" border="false" alt-text="Screenshot of the TOC for a wiki with several folders expanded to show subfolders.":::

:::column-end::: :::column span="":::

.order file defines the TOC page sequence

:::image type="content" source="media/wiki/wiki-repo-order-file-example.png" border="false" alt-text="Screenshot of a wiki folder and file list in a Git repository. The .order file is open and shows the definition for the TOC page sequence.":::

:::column-end::: :::row-end:::

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:

  1. Copy the clone URL for the wiki and open it in a browser. The Git repository for the wiki opens.

  2. 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.

Related content