Announcement: Publish markdown files from your git repository to VSTS Wiki

Sandeep Chadda (MSFT)

March 25th, 20180 0

Now you can publish markdown files from a git repository to the VSTS Wiki. Developers often write SDK documents, product documentation, or README files explaining a product in a git repository. Such pages are often updated alongside code in the code repository. Git provides a friction free experience where code and docs can live on the same branch and are reviewed together in pull requests and are released together using the same build and release process.

There are few issues with hosting such pages in code repositories:

Viewers of this documentation need to sift through tons of code to find and read the content
Documentation inherently needs ordering i.e a structure that can dictate a page hierarchy. Git does not offer ordering of files therefore you end up seeing all pages in the alphabetical order only
Managing documentation versions is cumbersome i.e. it is not easy to find documentation of product release 1.0, 2.0, or other past releases.
There is no ubiquitous search or discovery to find all documentation at one place. Markdown files in git repository are discoverable through code search while the wiki pages are discoverable through wiki search.

You can read about more use cases in this user voice.

Solution

Now, VSTS Wiki allows you to publish markdown files from a folder in a git repository as Wiki pages. So let’s see how it works.

Publishing MD pages from code as Wiki

For the purpose of this blog post, I am creating a sample repository. Let’s say I have a code repository on Azure Node.js SDK that contains all my code and documentation. The conceptual folder has a bunch of markdown files that I need to publish to VSTS Wiki.

Sample git repository containing code and documentation

If you are a first time user of VSTS Wiki and you navigate to the Wiki hub, you see two options.

Publish code as Wiki shows up for first time users of Wiki

Create Wiki – creates your first project wiki (read more)
Publish code as Wiki – publishes markdown files from a git repository as Wiki

In case you are already using Wiki, then you will see Publish code as Wiki in the wiki breadcrumb.

Publish code as Wiki shows up on an existing Wiki

When you click on Publish code as Wiki, you see a dialog to select a repository, branch, and folder that you want to publish as wiki. You can also give your wiki a friendly and memorable name.

Map a wiki to a git repo

If you use the entire repository for documentation purposes, then you can select the root of the repository to publish all markdown files in the repository as wiki.

When you publish a branch in a git repo as wiki, the head of the branch of the git repo is mapped to the wiki. Therefore any changes made in this folder in the published branch will immediately reflect in Wiki. There are no other workflows involved.

And that’s it. All the content from the git repo will show up in the Wiki. Now you have a mirror image of the folder in the git repo in Wiki that will continue to get updated as developers write documentation in their git repo.

Markdown files published from git repository to VSTS Wiki

Once you click publish, we look for all markdown files recursively under the folder and its sub folders. If a sub-folder does not contain a markdown file, it will not show up in Wiki.

Edit pages & add new pages

You can also add new pages or edit existing pages in the git repository and these pages will appear in the wiki immediately. Clicking on the Edit page button in Wiki takes you to the underlying git repository.

Publish another version

As your product grows, you may add various versions to the product. Therefore you may have a need to write documentation regarding the various versions of the product.

Wiki now supports publishing multiple versions of the content. You can click on Publish new version.

Publish another branch from code repository as wiki

Next, select the branch that indicates the new version, and click on Update.

Select another branch from code repository

Now you have two different versions of documentation residing in the same wiki.

VSTS Wiki showing documentation from multiple branches

Reordering pages

Another issue with content hosted in version control is that you have no control over the ordering of the files and all files show up in alphabetical order. However, ordering the content is a basic need for content published in any wiki.

In VSTS Wiki, once you publish the content, you can add a .ORDER file at a folder level in your git repository to create your own page order.

.ORDER file to manage order of pages in Wiki

In the above example, I added a .ORDER file and added titles of few pages in a particular order. Once, I commit this change, the ordering of pages in wiki changes to mimic what I mentioned in the .ORDER file.

Changed order in Wiki hierarchy

Promoting folders to Wiki pages

Once the markdown files are published as Wiki, the sub-folders in the git repository will appear as follows.

Folders in git mapped to VSTS Wiki

In a wiki, there is an inherent need to have a hierarchy of pages, therefore you need a better treatment for folders. Now, you have the ability to promote a git repo folder to a page in wiki by following these simple steps:

If you want to promote the folder called ‘includes’ as a wiki page then create a page called ‘includes.MD’ at the same hierarchy as the folder

Promote a folder to a wiki page – includes.md is at the same hierarchy as includes folder

Commit the changes to the branch and view the page in Wiki. Now you see that ‘includes’ does not appear as a folder but rather is appears as a wiki page.

VSTS Wiki shows a git folder as a Wiki page

Searching published wiki pages from code

All the markdown files published as wiki are searchable in the Wiki hub. Currently, files from the first published branch are indexed.

Un-publish a wiki

We understand that there could be moments when you could have published a code repository by mistake or the code repository content may turn stale therefore you may have a need to un-publish a wiki.

You can simply click on “Unpublish wiki” to remove the mapping between the git repository and wiki.

Unpublish wiki

Unpublishing a wiki will have no impact on the markdown pages in the code repository. i.e. all the pages in the git repository are still intact and you can always publish the pages from the code repository again at a later time.

Unpublishing a wiki has no impact on the markdown pages in the code repository

When you unpublish a wiki, the pages are also removed from the search index therefore you will not be able to search pages in wiki once the wiki is unpublished.

What features are coming next?

Fix broken links on page move or page rename (70 votes)

Report Issues or Feature request

If you have a feature request or want to report a bug:

Update: 4/18/2018 – This feature is available for all accounts.