Format comments with markdown

Last Update: 4/19/2017

Team Services | TFS 2017

Use markdown to add rich formatting, tables, and images to your pull request comments.

Headers

Structure your comments using headers. Headers segment longer comments, making them easier to read.

Start a line with a hash character # to set a heading. Organize your remarks with subheadings by starting a line with additional hash characters, for example ####. Up to six levels of headings are supported.

Example:

This is an H1 header

This is a H3 header

This is a H5 header

This is an H1 header

This is a H3 header

This is a H5 header

Emphasis

Emphasize text with italics by surrounding the text with an asterisk * or underscore _.
Strongly emphasize text with boldface by surrounding text with double asterisks **.
Strike through text by surrounding it with double tilde characters ~~.
Combine these elements to apply multiple emphasis to text.

Example:

Use _emphasis_ in comments to express **strong** opinions and point out ~~corrections~~.

Use emphasis in comments to express strong opinions and point out corrections.

Tables

Organize structured data in your comments with tables. Tables are especially useful for describing function parameters, object methods, and other data that has a clear name to description mapping.

Each row of a table is on its own line, and table cells are separated using the pipe character |. The first two lines of a table set the column headers and the alignment of elements in the table. Use the : character on the second line of the table dividing the headers from the cells to set column alignment.

Example:

| Name | Description | 
|------|:-------------|
| parameter | description of parameter |
| option    | description of option |   
Name Description
parameter description of parameter
option description of option

Line breaks

Separate logical breaks in your comments with whitespace to make them easier to read.

A line break will be added to your text every time you hit return in the comment box to create a new line.

Example:

Add lines between your text with the return key.
This spaces your text better and makes it easier to read.

Add lines between your text with the return key
This spaces your text better and makes it easier to read.

A line break whenever a new line is put in a paragraph differs from standard markdown, where a line break is added only if you include extra spaces before your newline.

Horizontal rules

Add a horizontal rule to your comments by adding a new line that's just a series of dashes ---.

Example:

above
----
below

above


below

Lists

Organize related items with lists. You can add ordered lists with numbers , or unordered lists with just bullets.

Ordered lists start with a number followed by a period for each list item. Unordered lists start with a -. Put each list item on its own line.

Examples:

  1. First item.
  2. Second item.
  3. Third item.

  • First item.

  • Second item.
  • Third item.
  • - Item
    - Item
    - Item
    
    • Item
    • Item
    • Item

    Images

    Add images and animated GIFs to your comments to point out issues or just to liven the discussion.

    Use the following syntax to add an image:

    ![Text](URL)
    The text in the brackets describes the image being linked and the URL points to the image location.

    Example:

    ![Let's use this flow for the login experience](http://dev.fabrikam.net/images/uxflow.png)
    

    Sample flowchart with three items

    Attachments

    Attach files to your comments to illustrate your point or to give more detailed reasoning behind your suggestions. To attach a file, drag and drop it into the comment field or select the paperclip icon in the upper-right of the comment box.

    Attach files via drag and drop in pull requests

    If you have an image in your clipboard, you can paste it from the clipboard into the comment box and it will render directly into your comment.

    Attachments support the following file formats:

    • Images: PNG (.png), GIF (.gif), JPEG (both .jpeg and .jpg)
    • Documents: Word (.docx), Excel (.xlsx), and Powerpoint (.pptx), text files (.txt), and PDFs (.pdf)
    • Compressed files: ZIP (.zip) and GZIP (.gz)
    • Video files: MOV (.mov), MP4 (.mp4)

    Attaching non-image files creates a link to the file in your comment. Update the description text between the brackets to change the text displayed in the link. Attached image files render directly into your comment.

    Once you save a new comment or update a comment with an attachment, reviewers see the attached image(s) in the comment and can select links to download attached files.

    Code highlighting

    Highlight suggested code segments in your comments using code highlight blocks. Surround your code block with the ``` sequence on a new line at both the start and end of the block.

    Set an language identifier for the code block to enable syntax highlighting for any of the supported languages.

    ```language
    code
    ```
    

    Examples:

    ```js
    const count = records.length;
    ```
    
    const count = records.length;
    
    ```csharp
    Console.WriteLine("Hello, World!");
    ```
    
    Console.WriteLine("Hello, World!");
    

    HTTP and HTTPS URLs in your comments will automatically be formatted as links. You can set text hyperlinks for your URL using the more detailed link syntax:

    [Text](URL)

    You can link Team Services work items in your comments by typing the # and an identifier for the item in your comment and then choosing the work item from the list.

    Example:

    [C# language reference](https://msdn.microsoft.com/en-us/library/618ayhy6.aspx)
    

    C# language reference

    Emoji

    Use emojis to add character and quickly react to comments. Type in what you're feeling surrounded by : characters to get a matching emoji in your text. A full range of emojis are supported.

    Example:

    :smile:
    :angry:
    

    Emojis in markdown

    Quotes

    Quote previous comments or other text to set context for your comment.

    Quote single lines of text be putting a > before the text. Use multiple > characters to nest quoted text. Quote blocks of lines of text by using the same level of > across multiple lines.

    Example:

    > Single line quote
    >> Nested quote   
    > multiple line
    > quote
    

    quoting in markdown