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
You can publish content that you already maintain in a Git repository to an Azure DevOps wiki. Your repo might contain files for a software development kit (SDK), product documentation, README content, and so on. You can also publish multiple wikis for a single team project.
When you publish your Markdown (.md) files to a wiki, you gain several benefits:
- Organize the content into a managed page sequence structure
- Browse and filter the table of contents
- Publish new versions of the content
- Manage content in the same way you manage your code base
- Search the wiki easily by using the wiki Search feature
For more information, see Provisioned wiki versus published code as wiki.
This article describes how to add and edit content published to a wiki by using the Azure DevOps web portal and the Azure DevOps CLI. You can also work offline and update your wiki content in the same way that you collaborate on code within a Git repo. For more information, see Update wiki pages offline.
Prerequisites
| Category | Requirements |
|---|---|
| Project access | Member of the project where the wiki is located. You can request access from your project administrator, as needed. |
| Permissions | Member of the Contributors group. |
| Git repository | A Git repo defined in your team project. Ideally, the repo contains at least one Markdown file that you want to publish to your wiki. For more information, see Create a new Git repo in your project. |
Open the wiki
Connect to your Azure DevOps project by using a supported web browser and select Wiki:
If you need to switch your team project, select 
Azure DevOps to browse all team projects and teams.
Publish a Git repository to a wiki
This section describes how to publish your Git repository to a wiki. You can work directly with the Azure DevOps UI in the browser or use the Azure DevOps CLI.
To publish the Markdown files in your Git repo to a wiki, follow these steps:
From the Wiki landing page, select Publish code as wiki:
If you don't see the Publish code as wiki option, you might need to first define a Git repo for your project. Follow the instructions in Create a new Git repo, refresh the Wiki page, and then return to this procedure.
If you already have a team project wiki, you can expand the project dropdown menu and select Publish code wiki:
In the Publish code as wiki dialog, select the repo, branch, and folder that contain the Markdown files. The Git repo must be within the team project. If you want to publish all Markdown files in the repo to your wiki, select the root of the repo (
/) as the folder:
Enter a name for the new wiki repo and select Publish. The wiki repo populates with the Markdown files and folders included in the repo you selected.
The following image shows the published repo for the files contained in the azure-docs-sdk-node repo selected in the previous step:
The code wiki features a table of contents (TOC):
- The TOC title is derived from the Markdown file name.
- The Markdown (.md) files in the repo/branch/folder are listed in alphabetical order.
- A parent page is created for each subfolder defined within the published folder, even if the folder doesn't contain any Markdown files.
The following image shows the TOC content for the azure-docs-sdk-node repo:
Git repo branch mapped to wiki
The head of the Git repo branch is mapped to the published code wiki. Any changes made within the branch and selected folders are automatically reflected in the published code wiki. There are no other workflows involved.
Note
You can publish up to 10 branches per published code wiki.
For the provisioned wiki with the extra Markdown files, you can add or edit pages in the same way that you maintain code in your Git repo.
Edit, rename, or delete pages
In the Azure DevOps web portal, you can edit, rename, or delete a wiki page:
In your project, select Repos > Files or Code > Files.
In the list of files, select the page you want to work on.
Select More options
for the file, and then select the action:
Note
You can manage your wiki repo in the same way you manage other Git repo by defining branch policies on the branch that you selected to publish to the wiki. If you don't define branch policies, you can also make changes and push them directly to the branch from your web portal or from a client.
The following sections describe how to complete the actions in more detail.
Edit a page
As you edit a file, use the links to preview your changes or highlight changes made from the previous version.
To discard your changes, select Cancel. For more information about supported Markdown features, see Syntax guidance for Markdown usage.
When you're done, add a comment about your updates, and then select Commit:
The system automatically presents you with a link to create a pull request. You can ignore this message when you're directly editing the wiki branch.
Tip
If you change the name or case of a file, update the .order file that references the file to reflect the change. For more information, see Change the page sequence, add, or update an .order file.
Rename a page
All pages that you want to display in the wiki TOC must use the Markdown (.md) file type. You can use the Rename action to rename a file, including changing the file extension.
The following example renames the new-home-page.md file to New-Home-Page.md. The corresponding page displays in the wiki TOC with the label, "New Home Page."
Page titles are case-sensitive and must be unique within the folder. The title must be 235 characters or less. For more information, see Page title naming restrictions.
Delete a page
Any Markdown file that you don't want to appear in the wiki, you can delete from the published folder. If you included the file in a .order file, delete the corresponding page entry from the .order file. For more information, see Change the page sequence, add, or update an .order file.
Add a page or multiple pages
There are several ways you can add pages to your published wiki:
- Add a file to the wiki root folder or any subfolder
- Upload files to the wiki root folder or any subfolder
- Add or update any .order file to specify the page sequence in the wiki TOC
For each update, you need to commit your changes to the wiki repo. Then, refresh your wiki for your published repo to review the changes.
Add a page from the web portal
To add a page to your published wiki, follow these steps:
In the Azure DevOps web portal, go to Repos > Files or Code > Files for the published repo.
Select More options
for the repo, then select New > File:
In the dialog, enter a name for the new file that includes the Markdown (.md) file type.
The file name should correspond to the page title that you want to display in the wiki TOC. Replace any spaces in the page title with hyphens (
-) in the file name. Page titles are case-sensitive and must be unique within the folder. The title must be 235 characters or less. For more information, see Page title naming restrictions.The following example adds a file named Page-4.md that displays in the wiki TOC with the page title "Page 4."
Select Create.
When the page appears in the file list, select the page and then select Edit. Enter the contents for the page. For more information, see Syntax guidance for Markdown files, widgets, wikis, and pull request comments.
When you're done, add the new page to your published repo by selecting Commit.
Upload files to a folder
You can also upload files to a folder in the published wiki. This option is useful when you have existing content that you want to add.
In the Azure DevOps web portal, go to Repos > Files or Code > Files for the published repo.
Select More options
for the repo, then select Upload file(s):
In the Commit dialog, select the folder and files you want to upload:
When you're done, upload the files to your published repo by selecting Commit.
Add a page that has subpages
If you want a page in your wiki to have subpages, you need a Markdown file and folder that have the same name. The file and folder must be in the same wiki folder.
Create the new Markdown file by following the steps in Add a page from the web portal.
To create the corresponding folder, select More options
for the repo, then select New > Folder.In the New Folder dialog, enter the folder name, which must be identical to the Markdown file name:
Select Create.
In the wiki file list, select the new folder. Add one or more files as subpages to the folder.
Add or update the .order file
After you add files or folders to the published repo, the last step is to add or update the .order file for any new or updated folders. Update the page sequence to ensure the new files and folders display in the wiki TOC as expected.
For more information, see Change the page sequence, add, or update a .order file. Any file not listed in the .order file is added to the end of the alphabetical list in the page sequence.
Change page sequence with .order file
The .order file at the wiki root specifies the display sequence for pages at the root level. The file is a plain text list of page names that correspond to the Markdown files in the folder, such as Welcome, support, rel-2025, and so on. Each folder within the wiki also has a .order file that defines the page sequence for that folder.
Follow these steps to set up an order sequence file for a folder:
In the Code > Files page, select New file. Name the file .order.
Edit the file contents to define the display sequence for the Markdown files in the folder.
Add an entry corresponds for each page file in the folder that you want to make visible to wiki users.
Page titles are case-sensitive. The entry text should match the page title and case used in the file name, but don't include the Markdown (.md) file type.
The following example shows an .order file for a folder with five files:
readme-version-9
Project-Overview
Get-Started
Submit-a-pull-request
team-contacts
Set the wiki home page
When you select Wiki in the Azure DevOps web portal, the home page for your wiki opens.
By default, the first page you add when you create a wiki is set as the wiki home page. When your wiki has multiple pages, the first file in the alphabetical sequence is set as the home page.
You can specify which page to use as the home page by setting the page sequence in the .order file at the wiki root. Place the home page name on the top line in the root .order file:
Wiki-Welcome
Project-Overview
Get-Started
Submit-a-pull-request
team-contacts
readme-version-9
Promote folder to wiki page
You can display a folder in your repository as a page in your wiki. This process is known as promoting a folder to a page.
For this scenario, you need the following configuration:
A Markdown (.md) file in your wiki that has the same name as the folder.
The Markdown file and folder must be peers at the same location in your wiki file list.
The following example shows a folder and Markdown (.md) file that are both named Test. The presence of the peers with the same name at the same location creates a page with the same name in the wiki sequence:
Select a wiki version
If your wiki has several published versions, the most recent version is shown by default.
You can select a different wiki version by expanding the branch dropdown list and selecting the version to display:
Unpublish a code wiki
If you no longer want a Git repository to be published as a wiki, you can unpublish the wiki.
Warning
Unpublishing a wiki unpublishes the entire code wiki, which includes all published versions of the repository.
In the wiki list, select the wiki you want to unpublish, select More options (...) > Unpublish wiki:
After you select the Unpublish action, a dialog opens for confirmation.
In the confirmation dialog, select Unpublish:
