Edit

Provisioned wikis vs. published code as a wiki

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

In Azure DevOps, you can maintain your wiki content in a team project wiki or a published as code wiki. With a published as code wiki, you can maintain several versioned wikis to support your content needs, although it's available only if Azure Repos is enabled.

While both options maintain the wiki content in Git repositories, the way you add, update, and manage the wiki content differs.

Note

The publish code as wiki feature is currently available on Azure DevOps Server 2018 and later versions. For older versions, you can only provision a wiki for your team project.

Wiki page menu options

With a provisioned wiki, you can add and edit pages directly within the wiki. All content updates to a provisioned wiki occur within the wiki.

With a publish code as wiki, you can add, edit, and update content from Repos or Code.

The following image shows options for a provisioned wiki. Several of these options aren't supported for the publish as code wiki pages.

Screenshot of Provisioned wiki page menu options.

For example, the Edit in Repos option for the publish code as wiki takes you to the Repo page to edit that specific page. Updates that you make to a page in the branch you selected for the wiki get automatically published to the wiki.

Supported features and operational differences

Both types of wiki support the following features:

The following table summarizes those operations or features that might differ, depending on the wiki type.

Operation Provisioned wiki Publish code as wiki
Support multiple wikis, name wiki ✔️
Add or edit pages from Repos > Files or Code > Files ✔️
Revert to an earlier revision from the Wiki ✔️
Revert to an earlier revision from Repos or Code ✔️ ✔️
Maintain versioned wikis ✔️
Select a wiki version ✔️
Unpublish a code wiki ✔️

Add pages

For both types of wiki, select New page or Add subpage. For more information, see Add and edit wiki pages.

Page sequence and page list in navigation pane

The provisioned wiki manages the page sequence and page list automatically as you add or move pages within the navigation pane.

To structure the list of pages in the navigation pane for a publish code as wiki, define the .order file at the root, and for each subfolder or parent page that contains subpages.

Both types of wikis follow the same file structure, it's just that the publish code as wiki requires you to maintain the page sequence manually.

For more information about working with .order files, see Wiki Git repository files and file structure.

Page revisions and reverting to a previous version

From the wiki, you can view the revisions of any wiki page. Select Revisions or the View revisions menu option.

But, the revert process differs depending on the wiki page type.

  • For a provisioned wiki page, select Revert, as described in Revert a commit to a provisioned wiki page
  • For a publish as code wiki page, work from a local branch and submit a pull request to update the branch you're working from.

Versioning and unpublishing a wiki

With versioning, you can publish different content versions to distinct wikis, based on a versioned branch of a Git repo. Versioning and unpublishing a wiki, is supported only for wikis that you created by publishing code to a wiki. For more information, see Publish a code wiki/Unpublish a code wiki.

Delete a project wiki

Note

Wiki REST APIs don't support deleting a project wiki. So, you have to delete the wiki repository instead.

  1. Clone the wiki repository to take backup of all its content. The More options has the clone wiki URL, which can be used to clone the wiki.

  2. Get the git repository ID that backs your wiki. You can use the REST API to get all the wikis in the project.

    For example, GET https://fabrikam.visualstudio.com/sampleProject/_apis/wiki/wikis?api-version=4.1 returns all the wikis in the project, so you can choose which one to delete.

  3. Use the REST API to delete the backing Git repo. Use the repository ID of the project wiki you found in the previous step and double check the repository ID, so you don't remove the wrong one.

    For example, DELETE https://fabrikam.visualstudio.com/sampleProject /_apis/git/repositories/{repositoryId}?api-version=4.1

Update a wiki offline

You can work offline or in a local branch to update content for a provisioned wiki and publish as code wiki. For more information, see Clone and update wiki pages offline.