Install content-authoring tools

This article describes how to install the recommended tools you need to make efficient in-depth or large contributions to Microsoft Learn. Examples of major updates include:

  • Lengthy revisions to multiple articles
  • Creating a new article
  • Work for which you'd want to use the available Visual Studio Code extensions, like Learn Authoring Pack.

Important

If you're making only minor changes, you don't need to complete the steps in this article. See Edit in the browser to learn how to make quick edits without installing any tools.

Contributors who'll be making major changes are encouraged to complete these steps. Even if you have write permissions in the main repository, we highly recommend (and this guide assumes) that you fork and clone the repository and store your proposed changes in your fork.

In this article, you'll:

Install Git client tools for Windows

This installation includes the Git version control system and Git Bash, the command-line app that you use to interact with your local Git repository.

  1. Download Git for Windows.

  2. Run the downloaded executable (.EXE) file and follow the prompts to install. Select Next at each prompt to accept all default settings.

  3. Select a code editor, when prompted. The default code editor is Vim.

  4. Select Finish to complete the installation.

After installing Git for Windows, configure your Git name and your email address.

Install Git client tools for Mac and Linux

  • Git for Mac is provided as part of the Xcode Command Line Tools. Simply run git from the command line. You will be prompted to install the command line tools if needed. You can also download Git for Mac from the Software Freedom Conservancy.
  • Git for Linux and Unix

Follow the instructions for your chosen client for installation and configuration.

Install Visual Studio Code

Visual Studio Code is a lightweight editor that works on Windows, Linux, and Mac. It includes Git integration and support for extensions.

Download and install Visual Studio Code for your operating system:

During installation, accept all default settings.

Tip

To launch VS Code and open the current folder, run the command code . in the command line or Bash shell. If the current folder is part of a local Git repo, the GitHub integration appears in Visual Studio Code automatically.

Install Learn Authoring Pack

The Learn Authoring Pack for Visual Studio Code includes basic Markdown authoring assistance, page previews, support for Markdown templates, markdownlint, and Code Spell Checker. These features ease and streamline the contribution process. As such, we consider the Learn Authoring Pack a required extension for contributors.

To install the Learn Authoring Pack, choose Install from the Learn Authoring Pack page in the VS Code Marketplace.

To use the Learn Authoring Pack functionality, press Alt+M in Visual Studio Code. To configure a toolbar to show the functions available, edit the Visual Studio Code settings (Control+comma), and add user setting "markdown.showToolbar": true.

For more information, see Learn Authoring Pack for Visual Studio Code.

Understand Markdown editors

Markdown is a lightweight markup language used to author the content. Visual Studio Code is the preferred tool for editing Markdown at Microsoft. Other Markdown editing tools are available. The Markdown Reference article covers Markdown basics and the features supported by the learn.microsoft.com website.

Next steps

Now you're ready to Set up a local Git repository.