Markdown guidance

Last Update: 3/6/2017

Team Services | TFS 2017 | TFS 2015

Having the right guidance at the right time is critical to success. To support your team or contributors to your project, use Markdown text to format in-project guidance.

You can provide guidance to your team in these places using Markdown:

Here's an example of a Welcome page:

Sample Welcome Markdown page

Repository welcome pages

Use these pages to orient contributors to working within a Git repository or Team Foundation version (TFVC) control project folder. Consider adding guidance about:

  • The project focus
  • Prerequisites
  • Setting up the environment
  • Tips for getting things done within the project
  • Purpose or use of specific files
  • Project-specific terms and acronyms
  • Workflow guidance about committing or uploading changes and adding branches
  • Project sponsors or contacts

Edit or create additional pages

  1. You can start editing directly from the Welcome page.

    Edit Welcome Markdown page

    To edit a page, you must be a contributor to the repository or branch or have the Contribute permissions set to allow.

  2. To add another page, simply enter a link to a new Markdown file that doesn't yet exist, for example:

    [page-1](./page-1.md)

  3. After you save the file, click the link. Respond to the prompt to edit the file and commit it to your repository.

Add a page to a dashboard

NOTE

Feature availability: Adding a Markdown file to a team dashboard is available from Team Services and the web portal for TFS 2015.3 and later versions.

Click Add to dashboard, and then choose the team dashboard to add the markdown file to. As you update the Markdown file, changes will automatically appear on the dashboard upon refresh. See Dashboards for more info.

Add Markdown page to a dashboard

Location of the Welcome pages

The Welcome page corresponds to the README.md file defined in the Git repository or TFVC project folder (i.e. $/TeamProject/ReadMe.md). Additional pages you create show up in the same location.

Markdown pages in the repository

You can edit and manage these files in the same way you manage all other files under source control.

Git repositories

For Git projects, the README.md file needs to be at the root of each repository in the default branch. For Git based projects the left pane supports navigation to other repositories. A separate Welcome page/README.md file can be created for each repository.

TFVC projects

For TFVC projects the README.md file needs to be at the root of your team project folder (i.e. $/TeamProject/README.md).

Any additional Markdown files you have (ones with a *.md extension) in the root of the project folder will also show up in the left pane for easy navigation between them so you can provide additional information.

Markdown widgets

Use these widgets to support your team and stakeholders by adding information such as:

  • Team goals
  • Provide links to team backlogs or boards, metrics, or other items located in a network share such as a OneNote, SharePoint site or wiki pages
  • Important dates or target deadlines

Here's an example:

Sample Markdown widget

Go here to learn about adding a markdown widget to a team dashboard.

To edit a markdown widget, you must be a team admin or a member of the Project Administrators group. To be added as a team admin, go here.

Markdown conventions and syntax

Here's some basic Markdown syntax guidance. For more, see Daring Fireball.

Format element Syntax Example/notes

Headers

# - same as <h1>...</h1>

##- same as <h2>...</h2>

###- same as <h3>...</h3>

Header formats

Paragraphs

Press RETURN to start a new line.

Enter two spaces at the end of a line to indicate a line break.

For example, enter two spaces

to start a new line

Lists

Enter a - or * to indicate a bullet list.

- List item one
- List item two
- List item three

Enter numbers to indicate an ordered list.

1. Step 1
2. Step 2
3. Step 3
Unordered list:
  • List item one
  • List item two
  • List item three

Ordered list:
  1. Step 1
  2. Step 2
  3. Step 3

Links

[Link text](relative path or URL)

A link is represented in Markdown like this: [text to display](link target). When linking to another Markdown page in the same Git or TFVC repository, the link target can be a relative path or an absolute path in the repository.

Supported links for Welcome pages:

  • Relative path: [text to display](./target.md)
  • Absolute path in Git: [text to display](/folder/target.md)
  • Absolute path in TFVC: [text to display]($/project/folder/target.md)
  • URL: [text to display](http://address.com)

Supported links for Markdown widget:

  • URL: [text to display](http://address.com)
Note: Links to documents on file shares using file:// are not supported on Team Services or TFS 2017.1 and later versions. This restriction has been implemented for security purposes.

For information on how to specify relative links from a Welcome page or Markdown widget, see Source control relative links.

Anchor links

[text to display](#heading id)
[text to display](./target.md#heading id)

Anchor IDs are assigned to all headings when a Markdown files is rendered as HTML. The ID is the heading text with the spaces replaced by dashes (-) and all lower case. For example, the ID of this section is link-to-a-heading-in-the-page.

The syntax for an anchor link to a section--####Link to a heading in the page would translate to this: [this section](#link-to-a-heading-in-the-page).
The ID is all lower case, and the link is case sensitive, so be sure to use lower case, even though the heading itself uses upper case. You can reference headings in another Markdown file, too, like this: [text to display](path to markdown#heading id).

Images

![alt text](path to image file)

The path to the image file can be a relative path or the absolute path in Git or TVFC, just like the path to another Markdown file in a link.
  • Relative path: ![Image alt text](./image.png)
  • Absolute path in Git: ![Image alt text](/_img/image.png)
  • Absolute path in TFVC: ![Image alt text]($/project/folder/_img/image.png)

Bold, italics, etc.

Make text bold using double-asterisks: ** **

Make text italics using single-asterisks: * *

Make text strikethrough using double-tildas: ~~ ~~

The path to the image file can be a relative path or the absolute path in Git or TVFC, just like the path to another Markdown file in a link.
  • Bold text
  • Italicize text
  • Strikethrough text

Code blocks

To indicate a span of code, wrap it with backtick quotes ( ```). For example:

```
$ sudo npm install vsoagent-installer -g
```

$ sudo npm install vsoagent-installer -g

Text with four spaces at the beginning automatically converts to a code block.

Tables

Use | to format a table. For example:

| Heading 1 | Heading 2 | Heading 3 |
|-----------|-----------|-----------|
| Cell A1 | Cell A2 | Cell A3 |
| Cell B1 | Cell B2 | Cell B3 |
Make sure that you end each row with a CR or LF.

Markdown table example

Special characters

To insert one of the following characters, prefix with a backslash:

\ backslash

` backtick

_ underscore

{} curly braces

[] square brackets

() parentheses

# hash mark

+ plus sign

- minus sign (hyphen)

. dot

! exclamation mark

Some examples on inserting special characters

Enter \\ to get \

Enter \_ to get _

Enter \# to get #

Enter \( to get (

Enter \. to get .

Enter \! to get !

You can use both common Markdown conventions and Github-flavored extensions.

You can also use Markdown when entering text for Definition of Done on the Kanban board.

If you set policies on the Git repository, changes to the welcome page must be done as a pull request.

Additional resources:

Links to source control files are interpreted differently depending on whether you specify them in a Welcome page or a Markdown widget. The system interprets relative links as follows:

  • Welcome page: relative to the root of the source control repository in which the welcome page exists
  • Markdown widget: relative to the team project collection URL base.

For example:

Welcome page Markdown widget equivalent
/BuildProcessTemplates/AzureContinuousDeployment.11.xaml /DefaultCollection/Fabrikam Fiber/_versionControl#path=$/Tfvc Welcome/BuildProcessTemplates/AzureContinuousDeployment.11.xaml
./page-2.md /DefaultCollection/Fabrikam Fiber/_versionControl#path=$/Tfvc Welcome/page-2.md