{"id":833,"date":"2014-08-08T08:00:00","date_gmt":"2014-08-08T08:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/visualstudioalm\/2014\/08\/08\/project-welcome-pages\/"},"modified":"2019-02-14T17:48:04","modified_gmt":"2019-02-15T01:48:04","slug":"project-welcome-pages","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/devops\/project-welcome-pages\/","title":{"rendered":"Project Welcome Pages"},"content":{"rendered":"

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 \u201cProject Welcome Pages\u201d. It\u2019s very easy to tell when the feature had been enabled for your account, simply go to your project homepage and you\u2019ll see a new \u201cWelcome\u201d tab has appeared next to the \u201cOverview\u201d page that you are used to.\u00a0 Don\u2019t worry if you don\u2019t see it quite yet, the way that our deployments work it may take while to roll out to everyone\u2019s account but it is coming to yours very soon. This is what it looks like when you do get the feature enabled.<\/p>\n

\"Project<\/p>\n

Clicking on the Welcome link takes you to the welcome page for that project if it has one.<\/p>\n

\"Welcome<\/p>\n

The page itself is configured using a very simple convention based approach around Markdown<\/a> 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.<\/p>\n

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

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.<\/p>\n

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 \u2013 also, because we also support many elements of GitHub Flavored Markdown<\/a> (including things like code blocks and tables) the vast majority of them just display correctly out of the box.<\/p>\n

\"image\"<\/p>\n

That said, we can\u2019t 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 \u201cmarked<\/a>\u201d from Christopher Jeffrey. It\u2019s 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<\/a> project.\u00a0 We\u2019ve 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 \u2013 please do let us know how it works out for you.<\/p>\n

When editing your Markdown files on the client side, if you are not already using the Web Essentials for Visual Studio<\/a> 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<\/a> as a great stand-alone editor with live previews \u2013 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\u2019s Sublime Text<\/a>.<\/p>\n

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\u2019t 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.\u00a0 Let us know in the comments if you like this approach.<\/p>\n","protected":false},"excerpt":{"rendered":"

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 \u201cProject Welcome Pages\u201d. It\u2019s very easy to tell when the feature had […]<\/p>\n","protected":false},"author":652,"featured_media":45953,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1,225],"tags":[],"class_list":["post-833","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","category-git"],"acf":[],"blog_post_summary":"

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 \u201cProject Welcome Pages\u201d. It\u2019s very easy to tell when the feature had […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/posts\/833","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/users\/652"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/comments?post=833"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/posts\/833\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/media\/45953"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/media?parent=833"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/categories?post=833"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/devops\/wp-json\/wp\/v2\/tags?post=833"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}