Tool installations

Important

If you're making only minor changes to an article, you do not need to complete the steps in this article and can continue directly to the minor/infrequent changes workflow.

Major contributors and Microsoft employees are encouraged to complete these steps, which enable you to use the major/long-running changes workflow. Even if you have write permissions in the main repository, we highly recommend (and this guide assumes) that you fork and clone the repository, where you will have read/write permissions to store your proposed changes.

If you prefer to install the client tools via package manager or command line, see Installing tools using a Package Manager / Commandline.

Install Git client tools

Install the latest version of Software Freedom Conservancy's Git client tools. This installs the Git version control system, including Git Bash, the command-line app that you will use to interact with your local Git repository.

For the purposes of this guide, we'll install Git for Windows. You can accept all default settings, unless you want different behavior.

Page for selecting components

Page for adjusting the PATH environment

Page for configuring line-ending conversions

Page for configuring the terminal editor

Page for configuring extra options

Note

If you prefer a graphical user interface (GUI) over a command-line interface (CLI), see Software Freedom Conservancy's available GUI Clients page, GitHub's GitHub Desktop, or Visual Studio Code for some popular options. In this guide, we'll focus on using the command-line interface.

Update your Git Bash configuration

To make sure that you are listed correctly as a contributor, you must configure your username and email locally in Git.

  1. Open the Git Bash command prompt.

  2. Configure your username to match the username that you set up in your GitHub profile:

    git config --global user.name "johndoe"

  3. Configure your email to match the primary email that you designated in your GitHub profile. Use your Microsoft email address:

    git config --global user.email "alias@microsoft.com"

  4. Enter git config -l (that's the letter "l" and not the number "1"), and review your local settings to ensure the username and email in the configuration are correct.

Additional Git resources

Install a Markdown editor

Markdown is a lightweight markup language that is both easy to read and easy to learn. Because of this, it has rapidly become an industry standard. To write articles in Markdown, we recommend that you first download and install a Markdown editor.

Additional details on how to write with Markdown, including Markdown basics and the features supported by OPS custom Markdown extensions, are covered later in the How to use Markdown article.

Important

For Microsoft contributors, the recommended Markdown editor is Visual Studio Code. Some teams require the use of Visual Studio Code extensions (such as Gauntlet and Acrolinx).

Visual Studio Code

Visual Studio Code, also known as VS Code, is Microsoft's entry in this space. It's updated often and keeps getting better. Visit the Visual Studio Code documentation page to learn more.

For Microsoft employees, the OPS engineering team also provides VS Code authoring and Acrolinx extensions to assist with authoring OPS-compliant articles for Docs.

Atom

Atom is a free Markdown editor that GitHub provides. It does not require a license for business use, and it has a spell checker.

If you use Atom, you'll need to set up a few things:

  1. Atom defaults to using two spaces for tabs, but Markdown expects four spaces. If you leave it at the default of two, your article will look great in local preview but not when it’s imported into Azure. So, configure Atom to use four spaces. You can find this setting under File > Settings > Editor Settings > Tab Length.
  2. Turn on Soft Wrap in this section. It has the same effect as Word Wrap in Notepad.
  3. To turn on the Markdown preview, select Packages > Markdown Preview > Toggle Preview. You can use Ctrl+Shift+M to toggle the preview HTML view.

Installing tools using a Package Manager / Commandline

Package managers are a common way of installing applications on a computer from a unified source. This process makes it much easier to script the installation of required applications in an organization. The instructions below will outline how to install Git and Visual Studio Code from a package installer on both Mac and Windows.

Homebrew (Mac)

Homebrew is a package manager which is available on Mac OSX. It can be installed using the following commandline script:

Warning

Running arbitrary scripts from the internet generally isn't a safe practice, always ensure that the script is safe to run and that it is using a secure protocol (such as https)

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once you have Homebrew on your machine, you are able to install applications on your machine using the brew install command. Run the following command to install Git:

brew install git

After installing Git, ensure to follow the instructions to Update your Git Bash configuration.

To install Visual Studio Code, you need to use the brew cask install command as it is distributed in a different manner than Git. Running the following command will install Visual Studio Code:

brew cask install visual-studio-code

Once you have installed Visual Studio Code, follow the instructions to Install Visual Studio Code Extensions in order to get Gauntlet and Acrolinx tools.

PowerShell Package Management (Windows)

Starting with Windows 10, PowerShell contains a PackageManagement module which provides the ability to manage Package Managers within Windows.

To install Git and Visual Studio Code using PackageManagement, we will use the nuget Provider in order to leverage the Chocolatey repository.

To install Git, run the following command from a PowerShell window with administrative permissions:

Install-Package git.install -ProviderName nuget -Source https://chocolatey.org/api/v2

After installing Git, ensure to follow the instructions to Update your Git Bash configuration.

To install Visual Studio Code, run the following command:

Install-Package VisualStudioCode -ProviderName nuget -Source https://chocolatey.org/api/v2

Once you have installed Visual Studio Code, follow the instructions to Install Visual Studio Code Extensions in order to get Gauntlet and Acrolinx tools.

Next steps

  • For Microsoft employees:
    • If your group requires you to use the VS Code Gauntlet authoring or Acrolinx extensions to assist with authoring OPS-compliant articles for Docs, complete the installations before continuing.
    • If your group uses the VS Code Gauntlet extension and you are a portfolio owner/administrator, please also review the Gauntlet Template Service.
  • Finish the "Setup" section of this guide by continuing to Local repository setup. It shows you how to set up a local copy of the repository to use for your contributions.