Skip to content

Latest commit

 

History

History
71 lines (49 loc) · 4.04 KB

wiki-file-structure.md

File metadata and controls

71 lines (49 loc) · 4.04 KB
title titleSuffix description ms.subservice ms.custom ms.topic ms.author ms.reviewer author monikerRange ms.date
Wiki files, structure, and conventions
Azure DevOps
Learn about the file conventions of the Git repository and project wikis in Azure DevOps.
azure-devops-wiki
wiki, devdivchpfy22
conceptual
chcomley
gopinach
chcomley
<=azure-devops
01/05/2024

Wiki files and file structure

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

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.

[!INCLUDE temp]

.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
:::image type="content" source="media/wiki/wiki-toc-example.png" alt-text="Screenshot of wiki TOC example."::: :::image type="content" source="media/wiki/wiki-repo-order-file-example.png" alt-text="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.

Related articles