Provisioned wikis vs. published code as a wiki
TFS 2018
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.
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:
- Markdown format
- HTML tags
- Insert and resize images
- Mathematical notation and characters
- Link to work items using #
- Attach files
- Filter Wiki contents
- Print a Wiki page
- Update content offline
- Add or edit pages from the Wiki
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.
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.
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.1returns all the wikis in the project, so you can choose which one to delete.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.