About READMes and Wikis
VSTS | TFS 2018 | TFS 2017 | TFS 2015
To support your team or contributors to your project, use Markdown to add rich formatting, tables, and images to your team project. You can use Markdown format within a team project Wiki, content you add to a dashboard, within your team project README file, or other repository README file.
About READMes and markdown
VSTS | TFS 2018 | TFS 2017 | TFS 2015
To support your team or contributors to your project, use Markdown to add rich formatting, tables, and images to your team project. You can use Markdown format within content you add to a dashboard, within your team project README file, or other repository README file.
Markdown makes it easy to format text, include images, and link as needed to additional documentation within your project pages, readme files, dashboards, and pull request comments.
You can provide guidance to your team in these places using Markdown:
For supported syntax, see Syntax guidance for Markdown files, widgets, wikis, and pull request comments.
You can define a README file, or multiple files, for each repo or team project. Write your readme in Markdown instead of plain text.
Use README pages to orient contributors to working within your project. Consider adding guidance about:
- The project focus
- 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
Here are some great readmes that use this format and speak to all three audiences, for reference and inspiration:
Use your team project wiki to share information with other team members. When you provision a wiki from scratch, a Git repository is created to store your markdown files, images, attachments, and the sequence of pages. This wiki supports collaborative editing of its content and structure.
The built-in wiki is available with TFS 2018 and later versions. To download TFS 2018, see Visual Studio Downloads.
The following features are supported for the team project wiki.
Provision or create a wiki
Work with wiki content
- Add and edit wiki pages
- View wiki page history and revert
- Search Wiki content
- Version, select, or unpublish a published wiki
- Clone and update wiki content offline
- Filter or print Wiki content 1
- The print feature may not be available from the Firefox web browser.
Format wiki content
The following features are supported for the team project wiki you create in the indicated TFS version or later versions. To learn more, see Create a wiki for your team project and Add and edit wiki pages.
|Markdown format||TFS 2018|
|HTML tags||TFS 2018|
|Insert and resize images||TFS 2018|
|Link to work items using #||TFS 2018|
|Attach files||TFS 2018|
|Filter Wiki TOC||TFS 2018|
|Mathematical notation and characters||TFS 2018.2|
|Preview a Wiki page while editing||TFS 2018.2|
|Print a Wiki page 1||TFS 2018.2|
|Wiki keyboard shortcuts||TFS 2018.2|
|Wiki search||TFS 2018.2|
- This feature may not be available from the Firefox web browser.
Publish existing Git repositories to a wiki
Many teams document their code using markdown and check in these files along with the code. While Git supports the maintenance and review of such documentation along with standard pull requests, such files present a few challenges to consumers of the content.
- Readers must often sift through multiple files and folders to find the content of interest.
- Content lacks organization and structure. There is no inherent page hierarchy to support readers.
- Content versioning is not supported.
- Searching through content relies on searching the code, rather than a search experience optimized for searching content.
With the publish code as wiki feature, you can publish one or more Git repositories defined in your team project to a wiki. This feature addresses the challenges by providing a way to maintain your content alongside your code base, but selectively publish and update your content to a wiki.
There are several significant differences between how you manage the content for a wiki that you provision for a team project versus wiki pages that you publish from a Git repository. For details, see