Add Markdown to a dashboard

Azure DevOps Services | TFS 2018 | TFS 2017 | TFS 2015.1

Use the Markdown widget 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:

Web portal, Sample Markdown widget

Prerequisites

  • You must be a member of a team project. If you don't have a team project yet, create one.
  • If you haven't been added as a team member, get added now.
  • Anyone with access to a project, including stakeholders, can view dashboards.
  • To add, edit, or manage a team dashboard, you must be a team admin, a project admin, or have dashboard permissions. In general, you need to be a team member for the currently selected team to edit dashboards.

Prerequisites

  • You must be a member of a team project. If you don't have a team project yet, create one in an on-premises TFS.
  • If you haven't been added as a team member, get added now.
  • Anyone with access to the team project, including stakeholders, can view dashboards.
  • To add a widget to a team dashboard, you must be a team admin, a project admin, or have dashboard permissions. In general, you need to be a team admin for the currently selected team to edit dashboards. Request your current team or project admin to add you as a team admin.

Prerequisites

Connect to the web portal for your project

To add the markdown widget to a dashboard, you connect to your project using a supported web browser.

Note

Choose Previous navigation when you see a top-level, blue-bar. Choose New navigation if you see a vertical sidebar, if you enabled the New Navigation preview feature, or you are working in Azure DevOps Services. The vertical sidebar along with the new dashboards experience and other features are enabled when the New Navigation preview feature has been enabled for the signed-in user or the Azure DevOps Services organization.

To learn how to use the web portal effectively, see Web portal navigation.

Open a web browser window and choose Overview>Dashboards.

Web portal, open Dashboards

If you need to switch to a different project, choose the  Azure DevOps logo to browse all projects.

New navigation isn't supported on TFS at this time. Choose Previous navigation for guidance.

Add the markdown widget to a dashboard

If you need to add a dashboard, see Add and manage dashboards.

Note

Requires TFS 2015.1 or later version.

To add the markdown widget to the dashboard, click Edit dashboard icon. The widget catalog will automatically open.

  1. Drag the Markdown widget onto the dashboard where you want it located.

    Markdown widget

  2. Choose Done Editing to exit dashboard editing. This will dismiss the widget catalog. You can then configure the markdown widget as needed.

  3. Choose the gear icon gear icon to open the configuration dialog for the widget.

    To edit a markdown widget, you may need to be a team admin, a member of the Project Administrators group, or be granted permissions. To learn more, see Set dashboard permissions.

  4. Adjust the widget size as needed to fit the contents of the markdown you'll enter. The largest size is 10 tiles wide by 10 tiles tall. You can always adjust this later.

    Change markdown widget size

  5. Enter the text and markdown syntax into the configuration the configuration dialog. For supported syntax, see Syntax guidance for Markdown files, widgets, wikis, and pull request comments.

    Here we show some simple text with a bulleted list of four links

    Configure markdown

    Tip

    To link to a wiki page,use the following syntax:
    /ProjectName/_wiki/wikis/WikiRepositoryName?pagePath=/FileName

    To link to a repository file, page, or image within the project, rich-click the file and use the full URL.

    This renders the following widget:

    Web portal, Sample Markdown widget

    Note

    Links to documents on file shares using file:// are not supported. This restriction has been implemented for security purposes.

  6. Optionally, you can choose to point to a file in your repository.

    Configure Markdown widget with a repo file

  1. Choose Edit dashboard icon to modify a dashboard.

  2. Choose add a widget icon to open the widget catalog.

  3. Drag the Markdown widget onto the dashboard where you want it located.

    Markdown widget

  4. Choose the gear icon gear icon to open the configuration dialog for the widget.

    To edit a markdown widget, you may need to be a team admin, a member of the Project Administrators group, or be granted permissions. To learn more, see Set dashboard permissions.

  5. Adjust the widget size as needed to fit the contents of the markdown you'll enter. The largest size is 10 tiles wide by 10 tiles tall. You can always adjust this later.

    Change markdown widget size

  6. Enter the text and markdown syntax into the configuration the configuration dialog. For supported syntax, see Syntax guidance for Markdown files, widgets, wikis, and pull request comments.

    Here we show some simple text with a bulleted list of four links

    Configure markdown

    To link to a wiki page, repository file, or page within the project, use this format:

    /DefaultCollection/Fabrikam%20Fiber/Voice/_wiki?pagePath=%2FHome /DefaultCollection/Fabrikam%20Fiber/Voice/_git/Fabrikam%20Fiber?path=%2FREADME.md /DefaultCollection/Fabrikam%20Fiber/Voice/_backlogs?level=Backlog%20items&showParents=false&_a=backlog

    This renders the following widget:

    Web portal, Sample Markdown widget

    Note

    Links to documents on file shares using file:// are not supported on TFS 2017.1 and later versions. This restriction has been implemented for security purposes.

  7. Optionally, you can choose to point to a file in your repository.

    Configure Markdown widget with a repo file

  8. If you haven't closed the widget catalog yet, do that now.

  9. If you want to reposition the markdown widget or other widgets on the dashboard, do that now while you're still in dashboard edit mode.

  10. When you're finished with your changes, choose Exit edit-dashboard-mode icon to exit dashboard editing.