Project Welcome Pages

Project Welcome Pages

  • Comments 15

We recently deployed a new feature to Visual Studio Online to help people get new team members started with a project and for people browsing the server to understand what a project is for and how to use it. We call the feature “Project Welcome Pages”. It’s very easy to tell when the feature had been enabled for your account, simply go to your project homepage and you’ll see a new “Welcome” tab has appeared next to the “Overview” page that you are used to.  Don’t worry if you don’t see it quite yet, the way that our deployments work it may take while to roll out to everyone’s account but it is coming to yours very soon. This is what it looks like when you do get the feature enabled.

Project home page showing Welcome tab

Clicking on the Welcome link takes you to the welcome page for that project if it has one.

Welcome pages in TFVC

The page itself is configured using a very simple convention based approach around Markdown files checked into version control for that project meaning that the pages are very easy for the development team to keep up to date alongside their code.

To set a welcome page for a project, simply check in a file called README.md.  For TFVC based projects this file needs to be at the root of your Team Project folder (i.e. $/TeamProject/ReadMe.md).  For Git based project this needs to be at the root of your repository in the default branch.  Once those changes are up on the server you are done – the content will display when someone selects the welcome page.

With TFVC projects, any other Markdown files you have (with a *.md extension) in the root of the project folder will also show up in the left and panel for easy navigation between them so you can provide additional information. For Git based projects the left hand side navigation bar displays the repositories that you have in your project so that you can select the one that you wish to read the documentation for.

Obviously the advantage of using such a simple convention based approach is that many of your open source codebases already have README.md files in them meaning those welcome pages will show up – also, because we also support many elements of GitHub Flavored Markdown (including things like code blocks and tables) the vast majority of them just display correctly out of the box.

image

That said, we can’t really take any credit for the great rendering capabilities. The Markdown rendering itself is in fact made possible by us making use of a superbly written open source library called “marked” from Christopher Jeffrey. It’s written entirely in Javascript but the performance and capability of the library is amazing, if you are looking to render some Markdown in your own projects then you could do a lot worse than take a look at the marked project.  We’ve been using it server side for a couple of different initiatives for a while now but this is the first time we have been making use of the client side rendering support and it has been working extremely well for us in testing – please do let us know how it works out for you.

When editing your Markdown files on the client side, if you are not already using the Web Essentials for Visual Studio then you should be (the clue is in the name - this extension is a must have for the power VS developer). On the Windows side, I personally use MarkdownPad as a great stand-alone editor with live previews – the Pro version is well worth it. Over on the Mac there are a ton of apps to choose from but to be honest I tend to stick with my trusty text editor of choice and that’s Sublime Text.

This is the first place that we are using Markdown with-in the Visual Studio Online experience for developers to create content stored in VSO but, depending on your feedback, we are expecting this to be a continuing trend. Markdown isn’t suitable for business users entering in bugs etc, but for developer friendly creation of documentation there is no doubt that it is here to stay.  Let us know in the comments if you like this approach.

Leave a Comment
  • Please add 8 and 4 and type the answer here:
  • Post
  • Awesome, although i do wonder if it would work very well for those of us who have hundreds of projects in the same Team Project.  Wonder if it could somehow be Team based (fav source control location?)

  • Nice, Will it be available for TFS server version too?

  • @Betty - Would a convention around the team name work for you? (i.e. default to a file that is the same name as the team if it is available?)

  • @Jean - yes the feature will make it into a future TFS version.

  • @Martin - That could work, although i wonder about the scalability.  I was thinking

  • That's awesome! But at the moment we have about 50+ projects in one Team Project. It would be nice to have a hierarchical navigation with a readme.md file in the root folder of every project.

  • @Martin - the more I think about it the more I feel that it needs to be closer to the related source code.  Otherwise branching will not add benefit and migrating code between repositories becomes harder.

    Also thinking about the git solution it really needs to be in individual repos too, instead of one root/default repo.

  • We also face the problem with branches that Betty already mentioned. We use branches for our releases and the readme files are related to a specific branch/release.

  • For Git the plan is to have a link between repo name and team name. Sounds like we need to have a bit of a think about the branch name thing in TFVC - for example for a given project how do we determine which is the branch that we want to use?  We'll keep digging into this some more so thanks for the early feedback, much appreciated.

  • This is a nice new feature. Thanks for your hard work. Can you create links between pages in the site like other Wiki systems or is it limited to only a single page?

  • I love this. Looking forward to seeing it in TFS.

  • Is there a problem with loading images in this? I can't get it to find the image even though it's in the same folder as the md file...

  • I'm also curious how/when linking to other .md files is possible/will be possible?

  • For anyone looking to link multiple .md files, it's covered here. Not the cleanest approach but it works for now.

    roadtoalm.com/.../creating-welcome-pages-on-vso-made-easy-with-markdown-files

  • What a great feature, looking forward to seeing this in TFS Server. Nice to see SharePoint out of the picture, it never really handled the 'Project Guidance' content that well. Now we'll finally be able to provide the metadata and help instructions needed for all our users.

Page 1 of 1 (15 items)