Mathias Olausson [MVP]

Use Visual Studio Online + Markdown as your Wiki

with 3 comments

With the latest deployment of VSO a bunch of great improvements for content editing was released. Take a look at for the complete list of additions.

The feature I’m most excited about in this update is the “Quick code editing” tools. With these changes we now have decent in-place editing capabilities in the VSO Web UI. It’s easy to add (new or upload) and edit files.

One thing I’ve been waiting for is the ability to use VSO for my team documentation in a Wiki-style way. Now the enchanced editing tools and the fact that VSO supports Markdown files I can finally do this in a good way. All my content is conveniently stored in version control, which makes authoring (using any tool) very easy. And I’ve got complete tracability as well, something that can be very useful when managing this kind of dynamic content.

Here is a quick walk-through just to show how easy it is to get started.

Add a welcome page

First we need to create a start page. Switch to the Welcome page on the VSO home page. Initially you will get a default page with an instruction on how to get started.


Click the Edit button and you will switch to the Markdown editor for the file. In the example below I’ve added some initial content, including a link to the backlog for the team.


Use the preview tool to check out the layout before saving.


When you are happy with the page, save it and the file will be added at the top-level in your repository.


Add content

Now with the start page in place it’s easy to add more content. If you add links to sub-pages you will get the option to automatically create them just like the welcome page.

Note: it’s a good idea to create a structure for your documents, in this case we’ll add the in the docs folder in source control.


Saving the file now gives you a link to a page that doesn’t yet exist.


Click the link and you can add the page the same way as we did for the welcome page. When you have saved the file it also creates the folder structure for you:


Add images

Another nice feature in this VSO deployment is the ability to add files to version control directly from the web UI. This allows us to quickly add additional content, like for instance images, to the page. Select the node to add content to, right-click and select Add Files…


Next you can add new or existing items to that folder, in my case I’ll be adding a logo to our wiki.


I want the image on the welcome page so next I’ll edit the file again and add a Markdown link to the image I’ve just uploaded to the repository.


Save the file and look at how nice the wiki looks with the image inplace.


Using external tools

If you want a richer editing experience then you can use any Markdown tool to author the content. The only big difference is that you need to sync the files in the repository yourself. But if you are a developer then using a TFVC or Git client is nothing new so that shouldn’t be a challenge. In the example below you can see what it looks like editing using MarkdownPad.


Happy editing!

Written by Mathias Olausson

December 28th, 2014 at 11:38 am

Posted in Markdown,VSO

3 Responses to 'Use Visual Studio Online + Markdown as your Wiki'

Subscribe to comments with RSS or TrackBack to 'Use Visual Studio Online + Markdown as your Wiki'.

  1. Great Post Mathias. Thanks. Happy New Year and we keep in touch next week again 😉



    Hassan Fadili

    2 Jan 15 at 10:50 am

  2. D you know when will this be supported for on-premise installations?


    10 Apr 15 at 2:59 pm

  3. Hi, this will be included in TFS 2015. The RC is out if you want it now.

    Mathias Olausson

    12 May 15 at 2:30 pm

Leave a Reply