Setting up a welcome page for a Team Project

It is hard to summarize the objective of the Team Project by just its name or description. Software Teams are usually found creating introduction documents or README files to summarize the purpose of the project with references to other useful material. Traditionally, Teams would store these files in SharePoint. This information is all the more useful when seen in context with the Team Project. A new feature called project welcome pages provides the perfect solution here. In this recipe, you'll learn how to set up welcome pages using markdown files.

Getting ready

Project welcome pages are created using a very simple convention-based approach. The welcome page simply renders the markdown files checked into the source control of the project.

Note

For TFVC-based source control, the readme.md file needs to be at the root of the Team Project folder. For Git-based source control, the readme.md file needs to be at the root of the repository in the default branch.

Team project welcome pages require the underlying file to be written in a markdown format. Markdown is intended to be easy to read and easy to write with the main emphasis on readability. TFS offers a markdown editor in Team Portal to help you author the welcome pages. You can alternatively choose to author your markdown files using a desktop editor.

How to do it…

1. Open Team Web Access and navigate to the FabrikamTFVC Team Project http://tfs2015:8080/tfs/DefaultCollection/Recipes.
2. From the home hub, select the welcome view and click on Edit to start editing the readme.md markdown file.
3. Copy the markdown snippet into the editor:

   # Welcome to the FabrikamTFVC
   ----------
   The team project contains the resources for the Fabrikam Software & Services. 
   
   ## Contacts
   ---
   * Project Owner - Tarun Arora [@arora_tarun](https://twitter.com/arora_tarun)
   
   ## Definition of Done
    All product backlog items need to abide to the definition of done before they can be marked done 
    1. All source code is checked in
    2. All code passes CI & no failing unit tests 
    3. Business services code coverage of > 60%
    4. All changes have been tested
    5. Deployment script added & updated
    6. Demo to Product Owner
    7. All associated tasks must be completed 
   ## Definition of Bug
   *Work in progress*
   

4. In the toolbar at the far right corner, you'll see the Show Content Preview icon. Click on the preview icon, the welcome page will now be rendered using the markdown:
   
5. Click on the Save icon to check in the readme.md file into version control.

How it works…

TFS supports common markdown conventions and GitHub-flavored extensions.

Tip

You can learn more about the Markdown syntax at http://bit.ly/1jJjRlI.

You can find out more about the GitHub-Flavored-Markdown at http://bit.ly/1jJl38D.

To simplify creating and editing markdown content, Team Foundation Server lets you link to other markdown files through both absolute and relative paths. When markdown is rendered as HTML, all headings automatically get IDs, so you can link to the headers by using the following convention [text to display](#heading id).

TFS also allows you to refer to a markdown page that does not yet exist; the engine is smart enough to give you the option to create the page when you click on the referred link. You can use the following format in markdown to do so: [new page](./newpage.md).