Install content authoring tools
This article describes the steps to interactively install Git client tools and Visual Studio Code.
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 quick changes workflow.
Major contributors 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
Install the latest version of Software Freedom Conservancy's Git client tools for your platform.
- Git for Windows. This install includes the Git version control system and Git Bash, the command-line app that you use to interact with your local Git repository.
- Git for Mac is provided as part of the Xcode Command Line Tools. Simply run
gitfrom 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
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.
Follow the instructions for your chosen client for installation and configuration.
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 Open Publishing Services (OPS) custom Markdown extensions, are covered in the How to use Markdown for writing Docs and Markdown Reference for OPS articles.
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. The VS Code home page should detect your operating system correctly.
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.
Docs Authoring Pack
Install the Docs Authoring Pack for Visual Studio Code. This set of extensions includes basic authoring assistance for help when writing Markdown, and a preview feature, so that you can see what the Markdown looks like in the style of the docs.microsoft.com site.
Visit this marketplace page and select Install, or search for
docsmsft.docs-authoring-pack in your extensions list in the VS Code window.
The Docs Authoring Pack is accessible by pressing Alt+M inside of VS Code. The toolbar is hidden by default but can be shown. Edit the VS Code settings (Control+comma) and adding user setting
"markdown.showToolbar": true to show the toolbar.
For more information, see the Docs Authoring Pack page.
Now you are ready to Set up a local Git repository.