Install content authoring tools
This article describes the steps to interactively install Git client tools and Visual Studio Code.
If you prefer to install the client tools for Mac using Homebrew, or Windows PowerShell, see additional tool installation options.
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, so that you have read/write permissions to store your proposed changes in your fork.
Install Git client tools on Windows
Install the latest version of Software Freedom Conservancy's Git client tools. The install includes the Git version control system and Git Bash, the command-line app that you use to interact with your local Git repository.
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.
Download Git for Windows.
You can accept all default settings, unless you want different behavior.
If Git Bash is not already running, in the Windows start menu, locate Git Bash, and launch the application.
Configure your user.name and user.email in Git Bash
This step is a one-time setup, only needed once per machine, even if you use multiple repositories. This step is to make sure that you are listed correctly as a contributor.
Configure the two properties user.name and user.email. The user.name value needs to match the username handle that you set up in your GitHub profile. The user.email value needs to match your email address.
git config --global user.name "johndoe" git config --global user.email "firstname.lastname@example.org"
List and review your local settings to ensure the user.name and user.email values are correct.
git config --list
In the next article, you will Set up a local Git repository.
Understand Markdown editors
Markdown is a lightweight markup language that is both easy to read and easy to learn. Therefore, it has rapidly become an industry standard. To write articles in Markdown, we recommend that you first download and install a Markdown editor. Visual Studio Code is the preferred tool for editing Markdown at Microsoft. Atom is another popular tool for editing Markdown.
Markdown text is saved into files with .md extension.
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.
Visual Studio Code
Visual Studio Code, also known as VS Code, is a lightweight editor that works on Windows, Linux, and Mac. It includes git integration, and support for extensions.
Download and install VS Code.
Launch Visual Studio Code
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.
Now you are ready to Set up a local Git repository.
For Mac Homebrew and PowerShell command-line options for these tools, see additional tool installation options.