Announcing the Docs Markdown Extension for Visual Studio Code

This post was written by Adam Kinney, Senior Software Engineer on the docs.microsoft.com team.

Today, we are delighted to announce the release of the Docs Authoring Pack for Visual Studio Code, making it easier than ever to contribute to docs.microsoft.com. This first release of the pack includes three extensions:

  • Docs Markdown - provides Markdown authoring assistance including formatting text, inserting lists and tables, inserting links to other content, and adding images and other assets. Unlike other Markdown editors, Docs Markdown supports custom Markdown extensions for docs.microsoft.com, such as alerts and code snippets.
  • DocFX - provides a limited docs.microsoft.com-specific Markdown preview to help see what your Markdown file will look like when published.
  • markdownlint - a popular Markdown linter by David Anson to help ensure your Markdown follows best practices.

How it Works

First, you will need to install it from the Visual Studio Marketplace. Once you navigate to the extension page, simply click on Install and follow the messages on the screen:

Installation of the Docs Markdown Extension

Once done, you should reload Visual Studio Code, open a Markdown file, and start writing! Use the Alt+M key combination to access the Docs Markdown Extension command palette, allowing you to quickly format the text (e.g. make it bold or italic), insert standard Markdown entities, such as a numbered list or a table, as well as insert docs-specific markup for notes, important information and tips:

Extension command palette

You can also quickly insert code from other files via a DocFX-compatible Markdown extension, and preview the page you are working on directly in the editor:

Preview the currently edited page

Contribute

The extension is open source, and we welcome any contributions to it!

Most contributions require you to agree to a Contributor License Agreement (CLA) affirming that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all Microsoft-owned repos using our CLA.

Feedback

Have thoughts on how we can make the extension better? Simply open a new issue!

And don't forget to follow our Twitter account for the latest updates.

Dreaming of making the world better for developers? Join our team!