Contents

Contributor Guide overview and browser-based tasks

Set up and work locally
1. Sign up for GitHub
2. Install Git and Markdown tools
3. Set up a local Git repository
Git and GitHub fundamentals
Full workflow
Writing essentials
Markdown reference
Style and voice quick start
Style guide
Add code to articles
Format text
Links
Docs Authoring pack
Overview
Features
Dev lang completion
Image compression
Metadata updates
Reformat Markdown tables
Smart quote replacement
Sort redirects
Sort selection
Documentation set-specific guidance
.NET docs
How to contribute to .NET docs
Labels and projects roadmap
.NET docs style conventions
 Voice and tone guide
Pull request review process
PowerShell-Docs
Additional resources
 Microsoft Docs contributor guide overview
4/21/2020 • 5 minutes to read • Edit Online

Welcome to the docs.microsoft.com (Docs) Contributor Guide!

Several of the Microsoft documentation sets are open source and hosted on GitHub. Not all document sets are
completely open source but many have public-facing repos where you can make suggested changes via pull
requests. This open source approach streamlines and improves communication between product engineers,
content teams, and customers, and has other advantages:
Open source repos plan in the open to get feedback on what docs are most needed.
Open source repos review in the open to publish the most helpful content on our first release.
Open source repos update in the open to make it easier to continuously improve the content.
The user experience on docs.microsoft.com integrates GitHub workflows directly to make it even easier. Start by
editing the document you are viewing. Or, help by reviewing new topics, or create quality issues.

IMPORTANT
All repositories that publish to docs.microsoft.com have adopted the Microsoft Open Source Code of Conduct or the .NET
Foundation Code of Conduct. For more information, see the Code of Conduct FAQ. Or contact [email protected], or
[email protected] with any questions or comments.
Minor corrections or clarifications to documentation and code examples in public repositories are covered by the
docs.microsoft.com Terms of Use. New or significant changes generate a comment in the pull request, asking you to submit
an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. We need you to complete the
online form before we can review or accept your pull request.

Quick edits to existing documents

Quick edits streamline the process to report and fix small errors and omissions in documents. Despite all efforts,
small grammar and spelling errors do make their way into our published documents. While you can create issues
to report mistakes, it's faster and easier to create a pull request (PR) to fix the issue, when the option is available.
1. Some docs pages allow you to edit content directly in the browser. If so, you'll see an Edit button like the one
shown below. Clicking the Edit (or equivalently localized) button takes you to the source file on GitHub. If the
Edit button (pencil icon without text) is missing, that means the documentation page is not available to be
changed.

2. Next, click the pencil icon, to edit the article as shown. If the pencil icon is grayed out, you need to either log
in to your GitHub account or create a new account.

3. Make your changes in the web editor. Click the Preview changes tab to check the formatting of your
change.
4. Once you have made your changes, scroll to the bottom of the page. Enter a title and description for your
changes and click Propose file change as shown in the following figure:

5. Now that you've proposed your change, you need to ask the owners of the repository to "pull" your changes
into their repository. This is done using something called a "pull request". When you clicked on Propose file
change in the figure above, you should have been taken to a new page that looks like the following figure:

Click Create pull request , enter a title (and optionally a description) for the pull request, and then click
Create pull request again. (If you are new to GitHub, see About Pull Requests for more information.)
6. That's it! Content team members will review and merge your PR. You may get some feedback requesting
changes if you made larger changes.
The GitHub editing UI responds to your permissions on the repository. The preceding images are accurate for
contributors that do not have write permissions to the target repository. GitHub automatically creates a fork of the
target repository in your account. If you have write-access to the target repository, GitHub creates a new branch in
the target repo. The branch name has the form <GitHubId>-patch-n using your GitHub ID, and a numeric
identifier for the patch branch.
We use pull requests for all changes, even for contributors that have write-access. Most repositories have the
master branch protected so that updates must be submitted as pull requests.

The in-browser editing experience is best for minor or infrequent changes. If you make large contributions or use
advanced Git features (such as branch management or advanced merge conflict resolution), you need to fork the
repo and work locally.

NOTE
If enabled, you can edit an article in any language and, based on the type of edit, the following will happen:
1. any linguistic change that is approved, will also help improve our Machine Translation engine
2. any edit that significantly modifies the content of the article will be handled internally to submit a change to the same
article in English so that it will get localized in all languages if approved. Your suggested improvements will not only
positively affect articles in your own language, but in all available languages.

Review open PRs

You can read new topics before they are published by checking the currently open PRs. Reviews follow the GitHub
flow process. You can see proposed updates or new articles in public repositories. Review them and add your
comments. Look at any of our docs repositories, and check the open pull requests (PRs) for areas that interest you.
Community feedback on proposed updates helps the entire community.

Create quality issues

Our docs are a continuous work in progress. Good issues help us focus our efforts on the highest priorities for the
community. The more detail you can provide, the more helpful the issue. Tell us what information you sought. Tell
us the search terms you used. If you can't get started, tell us how you want to start exploring unfamiliar technology.
Many of Microsoft's documentation pages have a Feedback section at the bottom of the page where you can click
to leave Product feedback or Content feedback to track issues that are specific to that article.
Issues start the conversation about what's needed. The content team will respond to these issues with ideas for
what we can add, and ask for your opinions. When we create a draft, we'll ask you to review the PR.

Get more involved

Other topics help you get started productively contributing to Microsoft Docs. They explain working with GitHub
repositories, Markdown tools, and extensions used in the Microsoft Docs platform.
 GitHub account setup
10/11/2019 • 2 minutes to read • Edit Online

Set up your GitHub account

To contribute to Docs technical content, you need to set up your own GitHub account. The good news is, you
usually only have to perform these steps once.
1. Create a GitHub account and set up your profile
If you don't already have a GitHub account, create one. Identify any affiliations in your GitHub profile. Contributions
to docs.microsoft.com count toward MVP award consideration. Identification helps us build a complete profile of all
your activities.

NOTE
Microsoft employees participating in Open Source projects always identify themselves as such in their GitHub profiles.
Community contributors should ensure that their profile does not incorrectly imply an employment relationship.

Next step
Continue to the Tool installations article to install Git Bash, a Markdown editor, and more.
 Install content authoring tools
2/6/2020 • 2 minutes to read • Edit Online

This article describes the steps to interactively install Git client tools and Visual Studio Code.
Install Git
Install Visual Studio Code
Install Docs Authoring Pack

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 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 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
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.
Additional Git resources are available here: Git terminology | Git basics | Learning Git and GitHub

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 Markdown Reference 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. The VS Code home page should detect your operating system correctly.
Windows
Mac
Linux

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.

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.

Next steps
Now you are ready to Set up a local Git repository.
 Set up Git repository locally for documentation
10/11/2019 • 5 minutes to read • Edit Online

This article describes the steps to set up a git repository on your local machine, with the intent to contribute to
Microsoft documentation. Contributors may use a locally cloned repository to add new articles, do major edits on
existing articles, or change artwork.
You run these one-time setup activities to start contributing:
Determine the appropriate repository
Fork the repository to your GitHub account
Choose a local folder for the cloned files
Clone the repository to your local machine
Configure the upstream remote value

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

Overview
To contribute to Microsoft's documentation site, you can make and edit Markdown files locally by cloning the
corresponding documentation repository. Microsoft requires you to fork the appropriate repository into your own
GitHub account so that you have read/write permissions there to store your proposed changes. Then you use pull
requests to merge changes into the read-only central shared repository.

If you're new to GitHub, watch the following video for a conceptual overview of the forking and cloning process:
Determine the repository
Documentation hosted at docs.microsoft.com resides in several different repositories at github.com.
1. If you are unsure of which repository to use, then visit the article on docs.microsoft.com using your web
browser. Select the Edit link (pencil icon) on the upper right of the article.

2. That link takes you to github.com location for the corresponding Markdown file in the appropriate
repository. Note the URL to view the repository name.

For example, these popular repositories are available for public contributions:
Azure documentation https://github.com/MicrosoftDocs/azure-docs
SQL Server documentation https://github.com/MicrosoftDocs/sql-docs
Visual Studio documentation https://github.com/MicrosoftDocs/visualstudio-docs
.NET Documentation https://github.com/dotnet/docs
Azure .Net SDK documentation https://github.com/azure/azure-docs-sdk-dotnet
ConfigMgr documentation https://github.com/MicrosoftDocs/SCCMdocs

Fork the repository

Using the appropriate repository, create a fork of the repository into your own GitHub account by using the GitHub
website.
A personal fork is required since all main documentation repositories provide read-only access. To make changes,
you must submit a pull request from your fork into the main repository. To facilitate this process, you first need
your own copy of the repository, in which you have write access. A GitHub fork serves that purpose.
1. Go to the main repository's GitHub page and click the Fork button on the upper right.

2. If you are prompted, select your GitHub account tile as the destination where the fork should be created.
 This prompt creates a copy of the repository within your GitHub account, known as a fork.

Choose a local folder

Make a local folder to hold a copy of the repository locally. Some of the repositories can be large; up to 5 GB for
azure-docs for example. Choose a location with available disk space.
1. Choose a folder name should be easy for you to remember and type. For example, consider a root folder
C:\docs\ or make a folder in your user profile directory ~/Documents/docs/

IMPORTANT
Avoid choosing a local folder path that is nested inside of another git repository folder location. While it is acceptable
to store the git cloned folders adjacent to each other, nesting git folders inside one another causes errors for the file
tracking.

2. Launch Git Bash

The default location that Git Bash starts in is typically the home directory (~) or
/c/users/<Windows-user-account>/ on Windows OS.

To determine the current directory, type pwd at the $ prompt.

3. Change directory (cd) into the folder that you created for hosting the repository locally. Note that Git Bash
uses the Linux convention of forward-slashes instead of back-slashes for folder paths.
For example, cd /c/docs/ or cd ~/Documents/docs/

Create a local clone

Using Git Bash, prepare to run the clone command to pull a copy of a repository (your fork) down to your device
on the current directory.
Authenticate by using Git Credential Manager
If you installed the latest version of Git for Windows and accepted the default installation, Git Credential Manager
is enabled by default. Git Credential Manager makes authentication much easier because you don't need to recall
your personal access token when re-establishing authenticated connections and remotes with GitHub.
1. Run the clone command, by providing the repository name. Cloning downloads (clone) the forked
repository on your local computer.
 TIP
You can get your fork's GitHub URL for the clone command from the Clone or download button in the GitHub UI:

Be sure to specify the path to your fork during the cloning process, not the main repository from which you
created the fork. Otherwise, you cannot contribute changes. Your fork is referenced through your personal
GitHub user account, such as github.com/<github-username>/<repo> .

git clone https://github.com/<github-username>/<repo>.git

Your clone command should look similar to this example:

git clone https://github.com/smithj/azure-docs.git

2. When you're prompted, enter your GitHub credentials.

3. When you're prompted, enter your two-factor authentication code.

 NOTE
Your credentials will be saved and used to authenticate future GitHub requests. You only need to do this
authentication once per computer.

4. The clone command runs and downloads a copy of the repository files from your fork into a new folder on
the local disk. A new folder is made within the current folder. It may take a few minutes, depending on the
repository size. You can explore the folder to see the structure once it is finished.

Configure remote upstream

After cloning the repository, set up a read-only remote connection to the main repository named upstream . You
use the upstream URL to keep your local repository in sync with the latest changes made by others. The git
remote command is used to set the configuration value. You use the fetch command to refresh the branch info
from the upstream repository.
1. If you're using Git Credential Manager , use the following commands. Replace the <repo> and
<organization> placeholders.

cd <repo>
git remote add upstream https://github.com/<organization>/<repo>.git
git fetch upstream

2. View the configured values and confirm the URLs are correct. Ensure the origin URLs point to your
personal fork. Ensure the upstream URLs point to the main repository, such as MicrosoftDocs or Azure.

git remote -v

Example remote output is shown. A fictitious git account named MyGitAccount is configured with a personal
access token to access the repo azure-docs:
 origin https://github.com/MyGitAccount/azure-docs.git (fetch)
origin https://github.com/MyGitAccount/azure-docs.git(push)
upstream https://github.com/MicrosoftDocs/azure-docs.git (fetch)
upstream https://github.com/MicrosoftDocs/azure-docs.git (push)

3. If you made a mistake, you can remove the remote value. To remove the upstream value, run the command
git remote remove upstream .

Next steps
To learn more about adding and updating content, continue to the GitHub contribution workflow.
 Git and GitHub essentials for Docs
2/6/2020 • 5 minutes to read • Edit Online

Overview
As a contributor to Docs content, you will interact with multiple tools and processes. You'll work in parallel with
other contributors on the same project, potentially the exact same content, even at the same time. This is all
enabled through Git and GitHub software.
Git is an open-source version control system. It facilitates this type of project collaboration through distributed
version control of files that live in repositories. In essence, Git makes it possible to integrate streams of work done
by multiple contributors over time, for a given repository.
GitHub is a web-based hosting service for Git repositories, such as those used to store docs.microsoft.com content.
For any project, GitHub hosts the main repository, from which contributors can make copies for their own work.

Git
If you're familiar with centralized version control systems (such as Team Foundation Server, SharePoint, or Visual
SourceSafe), you will notice that Git has a unique contribution workflow and terminology to support its distributed
model. For instance, there is no file locking that is normally associated with check-out/check-in operations. As a
matter of fact, Git is concerned about changes at an even finer level, comparing files byte by byte.
Git also uses a tiered structure to store and manage content for a project:
Repository: Also known as a repo, this is the highest unit of storage. A repository contains one or more
branches.
Branch: A unit of storage that contains the files and folders that make up a project's content set. Branches
separate streams of work (typically referred to as versions). Contributions are always made and scoped to a
specific branch. All repositories contain a default branch (typically named "master") and one or more branches
that are destined to be merged back into the master branch. The master branch serves as the current version
and "single source of truth" for the project. It's the parent from which all other branches in the repository are
created.
Contributors interact with Git to update and manipulate repositories at both the local and GitHub levels:
Locally through tools such as the Git Bash console, which supports Git commands for managing local
repositories and communicating with GitHub repositories.
Via www.github.com, which integrates Git to manage the reconciliation of contributions that flow back into the
main repository.

GitHub
NOTE
Although Docs guidance is based on using GitHub, some teams use Visual Studio Team Services to host Git repositories. The
Visual Studio Team Explorer client provides a GUI for interacting with Team Services repositories, as an alternative to using Git
commands through a command line.
Also, many of the following guidelines were developed as best practices from years of experience in hosting Azure service
content in GitHub. They might be required in some Docs repositories.
All workflows begin and end at the GitHub level, where the main repository for any Docs project is stored. The
copies that contributors create for their own use are distributed across multiple computers. These copies are
eventually reconciled back into the project's main GitHub repository.
Directory organization
As mentioned earlier, a project's default/master branch serves as the current version of content for the project. The
content in the master branch--and branches created from it--is loosely aligned with the organization of the articles
on the corresponding Docs pages. Subdirectories are used for separation of like content (such as services), media
content (such as image files), and "include" files (which enable reuse of content).
You can typically find a main articles directory off the root of the repository. The articles directory contains a set
of subdirectories. Articles in the subdirectories are formatted as Markdown files that use an .md extension. Some
repositories that support multiple services use a generic /articles subdirectory, such as the Azure-Docs
repository. Others might use a service-specific name, such as the IntuneDocs repository, which uses /IntuneDocs .
Within the root of this directory, you can find general articles that relate to the overall service or product. And
typically, you can then find another series of subdirectories that match the features/services or common scenarios.
For instance, Azure "virtual machine" articles are in the /virtual-machines subdirectory, and Intune "understand
and explore" articles are in the /understand-explore subdirectory.
Media subdirectory
Each article directory contains a /media subdirectory for corresponding media files. Media files contain images
used by articles that have image references.
Includes subdirectory
Whenever we have reusable content that is shared across two or more articles, it is placed in an /includes
subdirectory off the main articles directory. In a Markdown file that uses the include file, a corresponding
"include" Markdown extension is placed in the location where the include file needs to be referenced.
See Markdown reference: Includes for additional guidance.
Markdown file template
For convenience, the root directory of each repository typically contains a Markdown template file named
template.md . You can use this template file as a "starter file" if you need to create a new article for submission to
the repository. The file contains:
A metadata header at the top of the file, delineated by two, 3-hyphen lines. It contains the various tags used
for tracking information related to the article. Article metadata enables certain functionality, such as author
attribution, contributor attribution, breadcrumbs, and article descriptions. It also includes SEO optimizations and
reporting processes that Microsoft uses to evaluate the performance of the content. So the metadata is
important!
A metadata section that describes the various metadata tags and values. If you're unsure of the values to use
for the metadata section, you can leave them blank or comment them with a leading hashtag (#), and they will
be reviewed/completed by the pull request reviewer for the repository.
Various examples of using Markdown to format the elements of an article.
General instructions on the use of Markdown extensions , which you can use for various types of alerts.
Examples of embedding video by using an iframe.
General instructions on the use of docs.microsoft.com extensions , which you can use for special controls
such as buttons and selectors.

Pull requests
A pull request provides a convenient way for a contributor to propose a set of changes that will be applied to the
default branch. The changes (also known as commits) are stored in a contributor's branch, so GitHub can first
model the impact of merging them into the default branch. A pull request also serves as a mechanism to provide
the contributor with feedback from a build/validation process, the pull request reviewer, to resolve potential issues
or questions before the changes are merged into the default branch.
There are two ways to contribute by pull request, depending on the size of changes that you want to propose. We
will cover this in detail later, in the GitHub workflow section of this guide.
 GitHub contribution workflow for major or long-
running changes
2/6/2020 • 11 minutes to read • Edit Online

IMPORTANT
All repositories that publish to docs.microsoft.com have adopted either the Microsoft Open Source Code of Conduct or the
.NET Foundation Code of Conduct. For more information, see the Code of Conduct FAQ. Or contact
[email protected], or [email protected] with any questions or comments.
Minor corrections or clarifications to documentation and code examples in public repositories are covered by the
docs.microsoft.com Terms of Use. New or significant changes will generate a comment in the pull request, asking you to
submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. You will need to complete
the online form before your pull request can be merged.

Overview
This workflow is suitable for a contributor who needs to make a major change or will be a frequent contributor to
a repository. Frequent contributors typically have ongoing (long-running) changes, which go through multiple
build/validation/staging cycles or span multiple days before pull request sign-off and merge.
Examples of these types of contributions include:
Making a large contribution . For instance, you might make contributions (additions, changes, or deletions)
that span multiple articles and need to be committed and tested as one unit of work in a single pull request.
Creating and publishing a new ar ticle , which typically requires a more robust local editor.
Adding new images or updating images , which typically requires simultaneous creation of a new media
subdirectory, image files, updates to image links in articles, and previewing markdown files in a local editor to
test image rendering.
Updating an ar ticle over a period of days before you publish . In these cases, you typically need to do
regular integration of other changes that occur in the master branch. This integration is easier via Git Bash and
local editing. You also run the risk of losing your edits if you do this via the GitHub UI and wait before you
commit the changes.
Making continual updates to the same ar ticle after a pull request has been opened (unless you are
comfortable doing this via the GitHub UI). Using the GitHub UI has the potential to create multiple outstanding
pull requests for the same file, which may conflict with one another.
Terminology
Before you start, let's review some of the Git/GitHub terms and monikers used in this workflow. Don't worry about
understanding them now. Just know that you will be learning about them, and you can refer back to this section
when you need to verify a definition.

NAME DESC RIP T IO N

 NAME DESC RIP T IO N

fork Normally used as a noun, when referring to a copy of a main

GitHub repository. In practice, a fork is just another
repository. But it's special in the sense that GitHub maintains
a connection back to the main/parent repository. It's
sometimes used as a verb, as in "You must fork the repository
first."

remote A named connection to a remote repository, such as the

"origin" or "upstream" remote. Git refers to this as remote
because it is used to reference a repository that's hosted on
another computer. In this workflow, a remote is always a
GitHub repository.

origin The name assigned to the connection between your local

repository and the repository from which it was cloned. In
this workflow, origin represents the connection to your fork.
It's sometimes used as a moniker for the origin repository
itself, as in "Remember to push your changes to origin."

upstream Like the origin remote, upstream is a named connection to

another repository. In this workflow, upstream represents the
connection between your local repository and the main
repository, from which your fork was created. It's sometimes
used as a moniker for the upstream repository itself, as in
"Remember to pull the changes from upstream."

Workflow
IMPORTANT
If you haven't already, you must complete the steps in the Setup section. This section walks you through setting up your
GitHub account, installing Git Bash and a Markdown editor, creating a fork, and setting up your local repository. If you are
unfamiliar with Git and GitHub concepts such as a repository or branch, please first review Git and GitHub fundamentals.

In this workflow, changes flow in a repetitive cycle. Starting from your device's local repository, they flow back up
to your GitHub fork, into the main GitHub repository, and back down locally again as you incorporate changes
from other contributors.
Use GitHub flow
Recall from Git and GitHub fundamentals that a Git repository contains a master branch, plus any additional work-
in-progress branches that have not been integrated into master. Whenever you introduce a set of logically related
changes, it’s a best practice to create a working branch to manage your changes through the workflow. We refer to
it here as a working branch because it's a workspace to iterate/refine changes, until they can be integrated back
into the master branch.
Isolating related changes to a specific branch allows you to control and introduce those changes independently,
targeting them to a specific release time in the publishing cycle. In reality, depending on the type of work you do,
you can easily end up with several working branches in your repository. It's not uncommon to be working on
multiple branches at the same time, each representing a different project.
 TIP
Making your changes in the master branch is not a good practice. Imagine that you use the master branch to introduce a
set of changes for a timed feature release. You finish the changes and are waiting to release them. Then in the interim, you
have an urgent request to fix something, so you make the change to a file in the master branch and then publish the
change. In this example, you inadvertently publish both the fix and the changes that you were holding for release on a
specific date.

Now let's create a new working branch in your local repository, to capture your proposed changes. If you've setup
Git Bash (see Install content authoring tools), you can create a new branch and "checkout" that branch with one
command from within your cloned repository:

git checkout -b "branchname"

Each git client is different, so consult the help for your preferred client. You can see an overview of the process in
the GitHub Guide on GitHub flow.

Making your changes

Now that you have a copy ("clone") of the Microsoft repository and you've created a branch, you're now free to
make whatever changes you think would benefit the community using any text or Markdown editor, as outlined on
the Install content authoring tools page. You can save your changes locally without needing to submit them to
Microsoft until you're ready.

Saving changes to your repository

Before sending your changes to the author, you must first save them to your Github repository. Again, while all
tools are different, if you're using the Git Bash command line, this can be done in just a few easy steps.
First, from within the repository, you need to stage all of your changes to be commmited. This can be done by
executing:

git add --all

Next, you need to commit your saved changes to your local repository. This can be done in Git Bash by running:

git commit -m "Short Description of Changes Made"

Finally, since you created this branch on your local computer, you need to let the fork in your GitHub.com account
know about it. If you're using Git Bash, this can be done by running:

git push --set-upstream origin <branchname>

You've done it! Your code is now up in your GitHub repository and ready for you to create a pull request.

TIP
Even though your changes become visible in your personal GitHub account when you push them, there is no rule that you
need to submit a pull request immediately. If you want to come stop and return at a later time to make additional tweaks,
that's OK!
Need to fix something you submitted? No problem! Just make your changes in the same branch and then commit
and push again (no need to set the upstream server on subsequent pushes of the same branch).
Got more changes you need to make unrelated to this one? Switch back to the master branch and checkout
another fresh branch, Using Git Bash, this is as easy as:

git checkout master

git checkout -b "branchname"

You're now back in a new branch and you're well on your way to being a master contributer.

Pull request processing

The previous section walked you through the process of submitting proposed changes, by bundling them in a new
pull request (PR) that is added to the destination repository's PR queue. A pull request enables GitHub's
collaboration model, by asking for the changes from your working branch to be pulled and merged into another
branch. In most cases, that other branch is the default/master branch in the main repository.
Validation
Before your pull request can be merged into its destination branch, it might be required to pass through one or
more PR validation processes. Validation processes can vary depending on the scope of proposed changes and the
rules of the destination repository. After your pull request is submitted, you can expect one or more of the
following to happen:
Mergeability : A baseline GitHub mergeability test occurs first, to verify whether the proposed changes in your
branch are not in conflict with the destination branch. If the pull request indicates that this test failed, you must
reconcile the content that is causing the merge conflict before processing can continue.
CL A : If you are contributing to a public repository and are not a Microsoft employee, depending on the
magnitude of the proposed changes, you might be asked to complete a short Contribution License Agreement
(CLA) the first time you submit a pull request to that repository. After the CLA step is cleared, your pull request
is processed.
Labeling : Labels are automatically applied to your pull request, to indicate the state of your pull request as it
passes through the validation workflow. For instance, new pull requests might automatically receive the "do-
not-merge" label, indicating that the pull request has not yet completed the validation, review, and sign-off
steps.
Validation and build : Automated checks verify whether your changes pass validation tests. The validation
tests might yield warnings or errors, requiring you to make changes to one or more files in your pull request
before it can be merged. The validation test results are added as a comment in your pull request for your
review, and they might be sent to you in e-mail.
Staging : The article pages affected by your changes are automatically deployed to a staging environment for
review upon successful validation and build. Preview URLs appear in a PR comment.
Auto-merge : The pull request might be automatically merged, if it passes validation testing and certain
criteria. In this case, you don't need to take any further action.
Review and sign-off
After all PR processing is completed, you should review the results (PR comments, preview URLs, etc.) to
determine if additional changes to its files are required before you sign off for merging. If a PR reviewer has
reviewed your pull request, they can also provide feedback via comments if there are outstanding
issues/questions to be resolved prior to merge.
Comment automation enables read-level users (users who don't have write permissions in a repo) to perform a
write-level action, by assigning the appropriate label to a pull request. If you are working in a repository where
comment automation has been implemented, use the hashtag comments listed in the following table to assign
labels, change labels, or close a pull request. Microsoft employees will also be notified via e-mail for review and
sign-off of public repository PRs, whenever changes are proposed to articles for which you are the author.

H A SH TA G C O M M EN T W H AT IT DO ES REP O AVA IL A B IL IT Y

#sign-off When the author of an article types the Public and private
#sign-off comment in the comment
stream, the ready-to-merge label is
assigned. This label lets the reviewers in
the repo know when a pull request is
ready for review/merge.

If a contributor who is not the listed

author tries to sign off on a public repo
pull request by using the #sign-off
comment, a message is written to the
pull request indicating that only the
author can assign the label.

#hold-off Authors can type #hold-off in a PR Public and private

comment to remove the ready-to-
merge label--in case they change their
mind or make a mistake. In the private
repo, this assigns the do-not-merge
label.

#please-close Authors can type #please-close in Public

the comment stream to close the pull
request if they decide not to have the
changes merged.

When the pull request is issue-free and signed off, your changes are merged back into the parent branch and the
pull request is closed.
Publishing
Remember, your pull request has to be merged by a PR reviewer before the changes can be included in the next
scheduled publishing run. Pull requests are normally reviewed/merged in the order of submission. If your pull
request requires merging for a specific publishing run, you will need to work with your PR reviewer ahead of time
to ensure that merging happens prior to publishing.
After your contributions are approved and merged, the docs.microsoft.com publishing process picks them up.
Depending on the team that manages the repository you are contributing to, publishing times can vary. Articles
published under the following paths are normally deployed at approximately 10:30 AM and 3:30 PM Pacific Time,
Monday-Friday:
https://docs.microsoft.com/azure/
https://docs.microsoft.com/aspnet/
https://docs.microsoft.com/dotnet/
https://docs.microsoft.com/enterprise-mobility-security
It can take up to 45 minutes for articles to appear online after publishing. After your article is published, you can
verify your changes at the appropriate URL:
https://docs.microsoft.com/<path-to-your-article-without-the-md-extension> .

Next steps
That's it! You've made a contribution to docs.microsoft.com content!
To learn more about topics such as Markdown and Markdown extensions syntax, continue to the Markdown
reference article.
 Docs Markdown reference
4/3/2020 • 15 minutes to read • Edit Online

This article provides an alphabetical reference for writing Markdown for docs.microsoft.com (Docs).
Markdown is a lightweight markup language with plain text formatting syntax. Docs supports CommonMark
compliant Markdown parsed through the Markdig parsing engine. Docs also supports custom Markdown
extensions that provide richer content on the Docs site.
You can use any text editor to write Markdown, but we recommend Visual Studio Code with the Docs Authoring
Pack. The Docs Authoring Pack provides editing tools and preview functionality that lets you see what your articles
will look like when rendered on Docs.

Alerts (Note, Tip, Important, Caution, Warning)

Alerts are a Markdown extension to create block quotes that render on docs.microsoft.com with colors and icons
that indicate the significance of the content. The following alert types are supported:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

These alerts look like this on docs.microsoft.com:

NOTE
Information the user should notice even if skimming.

TIP
Optional information to help a user be more successful.

IMPORTANT
Essential information required for user success.

Cau t i on

Negative potential consequences of an action.

 WARNING
Dangerous certain consequences of an action.

Angle brackets
If you use angle brackets in text in your file--for example, to denote a placeholder--you need to manually encode
the angle brackets. Otherwise, Markdown thinks that they're intended to be an HTML tag.
For example, encode <script name> as &lt;script name&gt; or \<script name> .
Angle brackets don't have to be escaped in text formatted as inline code or in code blocks.

Apostrophes and quotation marks

If you copy from Word into a Markdown editor, the text might contain "smart" (curly) apostrophes or quotation
marks. These need to be encoded or changed to basic apostrophes or quotation marks. Otherwise, you end up
with things like this when the file is published: It’s
Here are the encodings for the "smart" versions of these punctuation marks:
Left (opening) quotation mark: &#8220;
Right (closing) quotation mark: &#8221;
Right (closing) single quotation mark or apostrophe: &#8217;
Left (opening) single quotation mark (rarely used): &#8216;

Blockquotes
Blockquotes are created using the > character:

> This is a blockquote. It is usually rendered indented and with a different background color.

The preceding example renders as follows:

This is a blockquote. It is usually rendered indented and with a different background color.

Bold and italic text

To format text as bold , enclose it in two asterisks:

This text is **bold**.

To format text as italic, enclose it in a single asterisk:

This text is *italic*.

To format text as both bold and italic , enclose it in three asterisks:

This text is both ***bold and italic***.

Code snippets
Docs Markdown supports the placement of code snippets both inline in a sentence and as a separate "fenced"
block between sentences. For more information, see How to add code to docs.

Columns
The columns Markdown extension gives Docs authors the ability to add column-based content layouts that are
more flexible and powerful than basic Markdown tables, which are only suited for true tabular data. You can add
up to four columns, and use the optional span attribute to merge two or more columns.
The syntax for columns is as follows:

:::row:::
:::column span="":::
Content...
:::column-end:::
:::column span="":::
More content...
:::column-end:::
:::row-end:::

Columns should only contain basic Markdown, including images. Headings, tables, tabs, and other complex
structures shouldn't be included. A row can't have any content outside of column.
For example, the following Markdown creates one column that spans two column widths, and one standard (no
span ) column:

:::row:::
:::column span="2":::
**This is a 2-span column with lots of text.**

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc
ornare commodo. Nullam ac metus imperdiet, rutrum justo vel, vulputate leo. Donec
rutrum non eros eget consectetur.
:::column-end:::
:::column span="":::
**This is a single-span column with an image in it.**

:::column-end:::
:::row-end:::

This renders as follows:

This is a 2-span column with lots of text.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec vestibulum mollis nunc ornare commodo. Nullam
ac metus imperdiet, rutrum justo vel, vulputate leo. Donec rutrum non eros eget consectetur.
This is a single-span column with an image in it.
Headings
Docs supports six levels of Markdown headings:

# This is a first level heading (H1)

## This is a second level heading (H2)

...

###### This is a sixth level heading (H6)

There must be a space between the last # and heading text.

Each Markdown file must have one and only one H1 heading.
The H1 heading must be the first content in the file after the YML metadata block.
H2 headings automatically appear in the right-hand navigating menu of the published file. Lower-level
headings don't appear, so use H2s strategically to help readers navigate your content.
HTML headings, such as <h1> , aren't recommended, and in some cases will cause build warnings.
You can link to individual headings in a file via bookmark links.

HTML
Although Markdown supports inline HTML, HTML isn't recommended for publishing to Docs, and except for a
limited list of values will cause build errors or warnings.

Images
The following file types are supported by default for images:
.jpg
.png
Standard conceptual images (default Markdown)
The basic Markdown syntax to embed an image is:


Example:

Where <alt text> is a brief description of the image and <folder path> is a relative path to the image. Alternate
text is required for screen readers for the visually impaired. It's also useful if there's a site bug where the image
can't render.
Underscores in alt text aren't rendered properly unless you escape them by prefixing them with a backslash ( \_ ).
However, don't copy file names for use as alt text. For example, instead of this:


Write this:

![Active Directory extension for two-factor authentication, step 4: Configure]

(./media/bogusfilename/ADextension_2FA_Configure_Step4.PNG)
Standard conceptual images (Docs Markdown)
The Docs custom :::image::: extension supports standard images, complex images, and icons.
For standard images, the older Markdown syntax will still work, but the new extension is recommended because it
supports more powerful functionality, such as specifying a localization scope that's different from the parent topic.
Other advanced functionality, such as selecting from the shared image gallery instead of specifying a local image,
will be available in the future. The new syntax is as follows:

:::image type="content" source="<folderPath>" alt-text="<alt text>":::

If type="content" (the default), both source and alt-text are required.

Complex images with long descriptions
You can also use this extension to add an image with a long description that is read by screen readers but not
rendered visually on the published page. Long descriptions are an accessibility requirement for complex images,
such as graphs. The syntax is the following:

:::image type="complex" source="<folderPath>" alt-text="<alt text>":::

<long description here>
:::image-end:::

If type="complex" , source , alt-text , a long description, and the :::image-end::: tag are all required.
Specifying loc-scope
Sometimes the localization scope for an image is different from that of the article or module that contains it. This
can cause a bad global experience: for example, if a screenshot of a product is accidentally localized into a
language the product isn't available in. To prevent this, you can specify the optional loc-scope attribute in images
of types content and complex .
Icons
The image extension supports icons, which are decorative images and should not have alt text. The syntax for icons
is:

:::image type="icon" source="<folderPath>":::

If type="icon" , only source should be specified.

Included Markdown files

Where markdown files need to be repeated in multiple articles, you can use an include file. The includes feature
instructs Docs to replace the reference with the contents of the include file at build time. You can use includes in
the following ways:
Inline: Reuse a common text snippet inline with within a sentence.
Block: Reuse an entire Markdown file as a block, nested within a section of an article.
An inline or block include file is a Markdown (.md) file. It can contain any valid Markdown. Include files are typically
located in a common includes subdirectory, in the root of the repository. When the article is published, the
included file is seamlessly integrated into it.
Includes syntax
Block include is on its own line:
 [!INCLUDE [<title>](<filepath>)]

Inline include is within a line:

Text before [!INCLUDE [<title>](<filepath>)] and after.

Where <title> is the name of the file and <filepath> is the relative path to the file. INCLUDE must be capitalized
and there must be a space before the <title> .
Here are requirements and considerations for include files:
Use block includes for significant amounts of content--a paragraph or two, a shared procedure, or a shared
section. Do not use them for anything smaller than a sentence.
Includes won't be rendered in the GitHub rendered view of your article, because they rely on Docs extensions.
They'll be rendered only after publication.
Ensure that all the text in an include file is written in complete sentences or phrases that do not depend on
preceding text or following text in the article that references the include. Ignoring this guidance creates an
untranslatable string in the article.
Don't embed include files within other include files.
Place media files in a media folder that's specific to the include subdirectory--for instance, the <repo>
/includes/media folder. The media directory should not contain any images in its root. If the include does not
have images, a corresponding media directory is not required.
As with regular articles, don't share media between include files. Use a separate file with a unique name for
each include and article. Store the media file in the media folder that's associated with the include.
Don't use an include as the only content of an article. Includes are meant to be supplemental to the content in
the rest of the article.

Links
For information on syntax for links, see Use links in documentation.

Lists (Numbered, Bulleted, Checklist)

Numbered list
To create a numbered list, you can use all 1s. The numbers are rendered in ascending order as a sequential list
when published. For increased source readability, you can increment your lists manually.
Don't use letters in lists, including nested lists. They don't render correctly when published to Docs. Nested lists
using numbers will render as lowercase letters when published. For example:

1. This is
1. a parent numbered list
1. and this is
1. a nested numbered list
1. (fin)

This renders as follows:

1. This is
2. a parent numbered list
a. and this is
b. a nested numbered list
3. (fin)
Bulleted list
To create a bulleted list, use - or * followed by a space at the beginning of each line:

- This is
- a parent bulleted list
- and this is
- a nested bulleted list
- All done!

This renders as follows:

This is
a parent bulleted list
and this is
a nested bulleted list
All done!
Whichever syntax you use, - or * , use it consistently within an article.
Checklist
Checklists are available for use on Docs via a custom Markdown extension:

> [!div class="checklist"]

> * List item 1
> * List item 2
> * List item 3

This example renders on Docs like this:

List item 1
List item 2
List item 3
Use checklists at the beginning or end of an article to summarize "What will you learn" or "What have you learned"
content. Do not add random checklists throughout your articles.

Next step action

You can use a custom extension to add a next step action button to Docs pages.
The syntax is as follows:

> [!div class="nextstepaction"]

> [button text](link to topic)

For example:

> [!div class="nextstepaction"]

> [Learn about adding code to articles](code-in-docs.md)

This renders as follows:

Learn about adding code to articles
You can use any supported link in a next step action, including a Markdown link to another web page. In most
cases, the next action link will be a relative link to another file in the same docset.

Non-localized strings
You can use the custom no-loc Markdown extension to identify strings of content that you would like the
localization process to ignore.
All strings called out will be case-sensitive; that is, the string must match exactly to be ignored for localization.
To mark an individual string as non-localizable, use this syntax:

:::no-loc text="String":::

For example, in the following, only the single instance of Document will be ignored during the localization process:

# Heading 1 of the Document

Markdown content within the :::no-loc text="Document":::. The are multiple instances of Document, document,
and documents.

NOTE
Use \ to escape special characters:

Lorem :::no-loc text="Find a \"Quotation\""::: Ipsum.

You can also use metadata in the YAML header to mark all instances of a string within the current Markdown file as
non-localizable:

author: cillroy
no-loc: [Global, Strings, to be, Ignored]

NOTE
The no-loc metadata is not supported as global metadata in docfx.json file. The localization pipeline doesn't read the
docfx.json file, so the no-loc metadata must be added into each individual source file.

In the following example, both in the metadata title and the Markdown header the word Document will be
ignored during the localization process.
In the metadata description and the Markdown main content the word document is localized, because it does not
start with a capital D .
 ---
title: Title of the Document
author: author-name
description: Description for the document
no-loc: [Title, Document]
---
# Heading 1 of the Document

Markdown content within the document.

Selectors
Selectors are UI elements that let the user switch between multiple flavors of the same article. They are used in
some doc sets to address differences in implementation across technologies or platforms. Selectors are typically
most applicable to our mobile platform content for developers.
Because the same selector Markdown goes in each article file that uses the selector, we recommend placing the
selector for your article in an include file. Then you can reference that include file in all your article files that use
the same selector.
There are two types of selectors: a single selector and a multi-selector.
Single selector

> [!div class="op_single_selector"]

> - [Universal Windows](../articles/notification-hubs-windows-store-dotnet-get-started/)
> - [Windows Phone](../articles/notification-hubs-windows-phone-get-started/)
> - [iOS](../articles/notification-hubs-ios-get-started/)
> - [Android](../articles/notification-hubs-android-get-started/)
> - [Kindle](../articles/notification-hubs-kindle-get-started/)
> - [Baidu](../articles/notification-hubs-baidu-get-started/)
> - [Xamarin.iOS](../articles/partner-xamarin-notification-hubs-ios-get-started/)
> - [Xamarin.Android](../articles/partner-xamarin-notification-hubs-android-get-started/)

... will be rendered like this:

Multi-selector

> [!div class="op_multi_selector" title1="Platform" title2="Backend"]

> - [(iOS | .NET)](./mobile-services-dotnet-backend-ios-get-started-push.md)
> - [(iOS | JavaScript)](./mobile-services-javascript-backend-ios-get-started-push.md)
> - [(Windows universal C# | .NET)](./mobile-services-dotnet-backend-windows-universal-dotnet-get-started-
push.md)
> - [(Windows universal C# | Javascript)](./mobile-services-javascript-backend-windows-universal-dotnet-get-
started-push.md)
> - [(Windows Phone | .NET)](./mobile-services-dotnet-backend-windows-phone-get-started-push.md)
> - [(Windows Phone | Javascript)](./mobile-services-javascript-backend-windows-phone-get-started-push.md)
> - [(Android | .NET)](./mobile-services-dotnet-backend-android-get-started-push.md)
> - [(Android | Javascript)](./mobile-services-javascript-backend-android-get-started-push.md)
> - [(Xamarin iOS | Javascript)](./partner-xamarin-mobile-services-ios-get-started-push.md)
> - [(Xamarin Android | Javascript)](./partner-xamarin-mobile-services-android-get-started-push.md)

... will be rendered like this:

Subscript and superscript

You should only use subscript or superscript when necessary for technical accuracy, such as when writing about
mathematical formulas. Don't use them for non-standard styles, such as footnotes.
For both subscript and superscript, use HTML:

Hello _{This is subscript!}

This renders as follows:

Hello This is subscript!

Goodbye ^{This is superscript!}

This renders as follows:

Goodbye This is superscript!

Tables
The simplest way to create a table in Markdown is to use pipes and lines. To create a standard table with a header,
follow the first line with dashed line:

|This is |a simple |table header|

|----------|-----------|------------|
|table |data |here |
|it doesn't|actually |have to line up nicely!|

This renders as follows:

T H IS IS A SIM P L E TA B L E H EA DER

table data here

it doesn't actually have to line up nicely!

You can align the columns by using colons:

| Fun | With | Tables |

| :------------------- | -------------------: |:---------------:|
| left-aligned column | right-aligned column | centered column |
| $100 | $100 | $100 |
| $10 | $10 | $10 |
| $1 | $1 | $1 |

Renders as follows:

F UN W IT H TA B L ES

left-aligned column right-aligned column centered column

$100 $100 $100

$10 $10 $10

$1 $1 $1
 TIP
The Docs Authoring Extension for VS Code makes it easy to add basic Markdown tables!
You can also use an online table generator.

Line breaks within words in any table cell

Long words in a Markdown table might make the table expand to the right navigation and become unreadable.
You can solve that by allowing Docs rendering to automatically insert line breaks within words when needed. Just
wrap up the table with the custom class [!div class="mx-tdBreakAll"] .
Here is a Markdown sample of a table with three rows that will be wrapped by a div with the class name
mx-tdBreakAll .

> [!div class="mx-tdBreakAll"]

> |Name|Syntax|Mandatory for silent installation?|Description|
> |-------------|----------|---------|---------|
> |Quiet|/quiet|Yes|Runs the installer, displaying no UI and no prompts.|
> |NoRestart|/norestart|No|Suppresses any attempts to restart. By default, the UI will prompt before restart.|
> |Help|/help|No|Provides help and quick reference. Displays the correct use of the setup command, including a
list of all options and behaviors.|

It will be rendered like this:

M A N DATO RY F O R SIL EN T
NAME SY N TA X IN STA L L AT IO N ? DESC RIP T IO N

Quiet /quiet Yes Runs the installer, displaying

no UI and no prompts.

NoRestart /norestart No Suppresses any attempts to

restart. By default, the UI will
prompt before restart.

Help /help No Provides help and quick

reference. Displays the
correct use of the setup
command, including a list of
all options and behaviors.

Line breaks within words in second column table cells

You might want line breaks to be automatically inserted within words only in the second column of a table. To limit
the breaks to the second column, apply the class mx-tdCol2BreakAll by using the div wrapper syntax as shown
earlier.
Data matrix tables
A data matrix table has both a header and a weighted first column, creating a matrix with an empty cell in the top
left. Docs has custom Markdown for data matrix tables:

| |Header 1 |Header 2|
|------------------|---------|--------|
|**First column A**|Cell 1A |Cell 2A |
|**First column B**|Cell 1B |Cell 2B |

Every entry in the first column must be styled as bold ( **bold** ); otherwise the tables won't be accessible for
screen readers or valid for Docs.
HTML Tables
HTML tables aren't recommended for docs.microsoft.com. They aren't human readable in the source - which is a
key principle of Markdown.
 Docs style and voice quick start
10/11/2019 • 3 minutes to read • Edit Online

This quick start is a brief guide to writing technical content for publication on docs.microsoft.com. These guidelines
apply whether you are creating new documentation or updating existing documentation.
Best practices:
Check the spelling and grammar in your articles, even if you have to copy and paste into Microsoft Word to
check.
Use a casual and friendly voice—like you're talking to another person one-on-one.
Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.

Use the Microsoft voice principles

We aspire to follow these principles when we write technical content for docs.microsoft.com. We might not always
get there, but we need to keep trying!
Focus on the intent : Customers have a specific purpose in mind when they consult our documentation. Before
you begin writing, clearly determine who the customer is and what task he or she is trying to do. Then, write
your article to help that specific customer do that specific task.
Use ever yday words : Try to use natural language, the words your customers use. Be less formal but not less
technical. Provide examples that explain new concepts.
Write concisely : Don't waste words. Be affirmative and don't use extra words or lots of qualifiers. Keep
sentences short and concise. Keep your article focused. If a task has a qualifier, put it at the beginning of the
sentence or paragraph. Also, keep the number of notes to a minimum. Use a screenshot when it can save words.
Make your ar ticle easy to scan : Put the most important things first. Use sections to chunk long procedures
into more manageable groups of steps. (Procedures with more than 12 steps are probably too long.) Use a
screenshot when it adds clarity.
Show empathy : Use a supportive tone in the article, and keep disclaimers to a minimum. Honestly call out
areas that will be frustrating to customers. Make sure the article focuses on what matters to customers; don't
just give a technical lecture.

Consider localization and machine translation

Our technical articles are translated into several languages, and some are modified for particular markets or
geographies. People might also use machine translation on the web to read the technical articles. So, keep the
following guidelines in mind when you're writing:
Make sure the ar ticle contains no grammar, spelling, or punctuation errors : This is something we
should do in general. Some Markdown editors (such as MarkdownPad 2.0) have a basic spell checker, but it's a
good practice to paste the rendered HTML content from the article into Word, which has a more robust spell
and grammar checker.
Make your sentences as shor t as possible : Compound sentences or chains of clauses make translation
difficult. Split up sentences if you can do it without being too redundant or sounding weird. We don't want
articles written in unnatural language either.
Use simple and consistent sentence construction : Consistency is better for translation. Avoid
parentheticals and asides, and have the subject as near the beginning of the sentence as possible. Check out a
few published articles. If an article has a friendly, easy-to-read style, use it as a model.
 Use consistent wording and capitalization : Again, consistency is key. Do not capitalize a word if it isn't at
the start of a sentence or it isn't a proper noun.
Include the "small words" : Words that we consider small and unimportant in English because they are
understood for context (such as "a," "the," "that," and "is") are crucial for machine translation. Be sure to include
them.

Other style and voice issues to watch for

Don't break up steps with commentary or asides.
For steps that include code snippets, put additional information about the step into the code as comments. This
reduces the amount of text that people have to read through. The key information gets copied into the code
project to remind people of what the code is doing when they refer to it later.
Use sentence case for all titles and headings.
Use "sign in" and not "log in."
For more guidelines, see the Microsoft Writing Style Guide.

Localized documentation
If you are contributing to localized documentation, refer to the Microsoft Language Portal.
For localization guidelines, information on language style and usage in technical publications, and information
on market-specific data formats, download the style guide in your language.
For Microsoft localized terminology, search for product-specific approved terminology or download the
Microsoft Terminology Collection in your language.
To learn more about localization, see "Global communications" in the Microsoft Writing Style Guide.
 How to include code in docs
3/5/2020 • 15 minutes to read • Edit Online

There are several ways to include code in an article published on docs.microsoft.com:

Individual elements (words) within a line.
Here's an example of code style.
Use code format when referring to named parameters and variables in a nearby code block in your text.
Code format may also be used for properties, methods, classes, and language keywords. For more
information, see Code elements later in this article..
Code blocks in the article Markdown file.

```csharp
public static void Log(string message)
{
_logger.LogInformation(message);
}
```

Use inline code blocks when it's impractical to display code by reference to a code file. For more
information, see Code blocks later in this article.
Code blocks by reference to a code file in the local repository.

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-

24,26":::

For more information, see In-repo snippet references later in this article.
Code blocks by reference to a code file in another repository.

:::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx"

highlight="2,5":::

For more information, see Out-of-repo snippet references later in this article.
Code blocks that let the user execute code in the browser.

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

For more information, see Interactive code snippets later in this article.
Besides explaining the Markdown for each of these ways to include code, the article provides some general
guidance for all code blocks.

Code elements
A "code element" is a programming language keyword, class name, property name, and so forth. It's not always
obvious what qualifies as code. For example, NuGet package names should be treated as code. When in doubt, see
Text formatting guidelines.
Inline code style
To include a code element in article text, surround it with backticks (`) to indicate code style. Inline code style
shouldn't use the triple-backtick format.

M A RK DO W N REN DERED

By default, the Entity Framework interprets a property that's By default, the Entity Framework interprets a property that's
named `Id` or `ClassnameID` as the primary key. named Id or ClassnameID as the primary key.

When an article is localized (translated into other languages), text styled as code is left untranslated. If you want to
prevent localization without using code style, see Non-localized strings.
Bold style
Some older style guides specify bold for inline code. Bold is an option when code style is so obtrusive as to
compromise readability. For example, a Markdown table with mostly code elements might look too busy with code
styling everywhere. If you choose to use bold style, use non-localized strings syntax to make sure that code is not
localized.
Links
A link to reference documentation may be more helpful than code format in some contexts. If you use a link, don't
apply code format to the link text. Styling a link as code can obscure the fact that the text is a link.
If you use a link and refer to the same element later in the same context, make the subsequent instances code
format rather than links.
Placeholders
If you want the user to replace a section of displayed code with their own values, use placeholder text marked off
by angle brackets or curly braces. For example: az group delete -n <ResourceGroupName> . Explain that the brackets
or braces must be removed when substituting real values.

Code blocks
The syntax for including code in a doc depends on where the code is located:
In the article Markdown file
In a code file in the same repository
In a code file in a different repository
Following are guidelines that apply to all three types of code blocks:
Automate code validation.
Highlight key lines of code.
Avoid horizontal scroll bars.
Screenshots
All of the methods listed in the preceding section result in usable code blocks:
You can copy and paste from them.
They're indexed by search engines.
They're accessible to screen readers.
These are just a few of the reasons why IDE screenshots aren't recommended as a method of including code in an
article. Use IDE screenshots for code only if you're showing something about the IDE itself, like IntelliSense. Don't
use screenshots just to show colorization and highlighting.
Code validation
Some repositories have implemented processes that automatically compile all sample code to check for errors.
The .NET repository does this. For more information, see Contributing in the .NET repository.
If you are including code blocks from another repository, work with the owners on a maintenance strategy for the
code so that your included code does not break or go out of date as new versions of the libraries the code uses are
shipped.
Highlighting
Snippets typically include more code than necessary in order to provide context. It helps readability when you
highlight the key lines that you're focusing on in the snippet, as in this example:

You can't highlight code when you include it in the article Markdown file. It works only for code snippets included
by reference to a code file.
Horizontal scroll bars
Break up long lines to avoid horizontal scroll bars. Scroll bars on code blocks make code hard to read. They're
especially problematic on longer code blocks, where it may be impossible to see the scroll bar and the line you
want to read at the same time.
A good practice for minimizing horizontal scroll bars on code blocks is to break up code lines longer than 85
characters. But keep in mind that the presence or absence of a scroll bar isn't the only criterion of readability. If
breaking a line before 85 hurts readability or copy-paste convenience, feel free to go over 85.

Inline code blocks

Use inline code blocks only when it's impractical to display code by reference to a code file. Inline code is generally
more difficult to test and keep up to date compared to a code file that is part of a complete project. And inline code
may omit context that could help the developer to understand and use the code. These considerations apply
mainly to programming languages. Inline code blocks can also be used for outputs and inputs (such as JSON),
query languages (such as SQL), and scripting languages (such as PowerShell).
There are two ways to indicate a section of text in an article file is a code block: by fencing it in triple-backticks (```)
or by indenting it. Fencing is preferred because it lets you specify the language. Avoid using indentation because
it's too easy to get wrong and it may be hard for another writer to understand your intent when they need to edit
your article.
Language indicators are placed immediately after the opening triple-backticks, as in the following example:
Markdown:

```json
{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}
```

Rendered:

{
"aggregator": {
"batchSize": 1000,
"flushTimeout": "00:00:30"
}
}

For information about the values you can use as language indicators, see Language names and aliases.
If you use a language or environment word after the triple-backticks (```) that isn't supported, that word appears in
the code section title bar on the rendered page. Whenever possible, use a language or environment indicator in
your inline code blocks.

NOTE
If you copy and paste code from a Word document, make sure it has no "curly quotes," which aren't valid in code (for
example, “ and ’ ). If it does, change them back to normal quotes ( ' and " ). Alternatively, rely on the Docs Authoring
Pack, smart quotes replacement feature.

In-repo snippet references

The preferred way to include code snippets for programming languages in docs is by reference to a code file. This
method gives you the ability to highlight lines of code and makes the wider context of the snippet available on
GitHub for developers to use. You can include code by using the triple colon format (:::) either manually or in Visual
Studio Code with the help of the docs.microsoft.com Authoring Pack.
1. In Visual Studio Code, click Alt + M or Option + M and select Snippet.
2. Once Snippet is selected, you will be prompted for Full Search, Scoped Search or Cross-Repository Reference.
To search locally, select Full Search.
3. Enter a search term to find the file. Once you've found the file, select the file.
4. Next, select an option to determine which line(s) of code should be included in the snippet. The options are: ID ,
Range and None .
5. Based on your selection from Step 4, provide a value if necessary.
Display entire code file:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs":::

Display part of a code file by specifying line numbers:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

Display part of a code file by specifying a snippet name:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

The following sections explain these examples:

Use a relative path to the code file
Include only selected line numbers
Refer to a named snippet
Highlight selected lines
For more information, see Snippet syntax reference later in this article.
Path to code file
Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

The example is from the ASP.NET docs repo, aspnetcore/data/ef-mvc/crud.md article file. The code file is
referenced by a relative path to aspnetcore/data/ef-mvc/intro/samples/cu/Controllers/StudentsController.cs in the
same repository.
Selected line numbers
Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26":::

This example displays only lines 2-24 and 26 of the StudentController.cs code file.
Prefer named snippets over hard-coded line numbers, as explained in the next section.
Named snippet
Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" id="snippet_Create":::

Use only letters and underscores for the name.

The example displays the snippet_Create section of the code file. The code file for this example has snippet tags in
comments in the C# code:
 // code excluded from the snippet
// <snippet_Create>
// code included in the snippet
// </snippet_Create>
// code excluded from the snippet

Whenever you can, refer to a named section rather than specifying line numbers. Line number references are
brittle because code files inevitably change in ways that make line numbers change. You don't necessarily get
notified of such changes. Your article eventually starts showing the wrong lines and you have no clue anything has
changed.
Highlighting selected lines
Example:

:::code language="csharp" source="intro/samples/cu/Controllers/StudentsController.cs" range="2-24,26"

highlight="2,5":::

The example highlights lines 2 and 5, counting from the start of the displayed snippet. Line numbers to highlight
don't count from the start of the code file. In other words, lines 3 and 6 of the code file are highlighted.

Out-of-repo snippet references

If the code file you want to reference is in a different repository, set up the code repository as a dependent
repository. When you do that, you specify a name for it. That name then acts like a folder name for purposes of
code references.
For example, the docs repository is Azure/azure-docs, and the code repository is Azure/azure-functions-durable-
extension.
In the root folder of azure-docs, add the following section in .openpublishing.publish.config.json:

{
"path_to_root": "samples-durable-functions",
"url": "https://github.com/Azure/azure-functions-durable-extension",
"branch": "master",
"branch_mapping": {}
},

Now when you refer to samples-durable-functions as if it were a folder in azure-docs, you're actually referring to
the root folder in the azure-functions-durable-extension repository.
You can include code by using the triple colon format (:::) either manually or in Visual Studio Code with the help of
the docs.microsoft.com Authoring Pack.
1. In Visual Studio Code, click Alt + M or Option + M and select Snippet.
2. Once Snippet is selected, you will be prompted for Full Search, Scoped Search or Cross-Repository Reference.
To search across repositories, select Cross-Repository Reference.
3. You will be given a selection of repositories that are in .openpublishing.publish.config.json. Select a repository.
4. Enter a search term to find the file. Once you've found the file, select the file.
5. Next, select an option to determine which line(s) of code should be included in the snippet. The options are: ID ,
Range and None .
6. Based on your selection from Step 5, provide a value.
Your snippet reference will look like this:
 :::code language="csharp" source="~/samples-durable-functions/samples/csx/shared/Location.csx"
highlight="2,5":::

In the azure-functions-durable-extension repository, that code file is in the samples/csx/shared folder. As noted
earlier, line numbers for highlighting are relative to the start of the snippet rather than the start of the file.

NOTE
The name you assign to the dependent repository is relative to the root of the main repository, but the tilde (~) refers to
the root of the doc set. The doc set root is determined by build_source_folder in .openpublishing.publish.config.json. The
path to the snippet in the preceding example works in the azure-docs repo because build_source_folder refers to the
repo root ( . ). If build_source_folder were articles , the path would start with ~/../samples-durable-functions
instead of ~/samples-durable-functions .

Interactive code snippets

Inline interactive code blocks
For the following languages, code snippets can be made executable in the browser window:
Azure Cloud Shell
Azure PowerShell Cloud Shell
C# REPL
When interactive mode is enabled, the rendered code boxes have a Tr y It or Run button. For example:

```azurepowershell-interactive
New-AzResourceGroup -Name myResourceGroup -Location westeurope
```

renders as follows:

New-AzResourceGroup -Name myResourceGroup -Location westeurope

To turn on this feature for a particular code block, use a special language identifier. The available options are:
azurepowershell-interactive - Enables the Azure PowerShell Cloud Shell, as in the preceding example
azurecli-interactive - Enables the Azure Cloud Shell
csharp-interactive - Enables the C# REPL

For the Azure Cloud Shell and PowerShell Cloud Shell, users can run commands against only their own Azure
account.
Code snippets included by reference
You can enable interactive mode for code snippets included by reference. Here are examples:

:::code source="PowerShell.ps1" interactive="cloudshell-powershell":::

:::code source="Bash.sh" interactive="cloudshell-bash":::

To turn on this feature for a particular code block, use the interactive attribute. The available attribute values are:
 cloudshell-powershell - Enables the Azure PowerShell Cloud Shell, as in the preceding example
cloudshell-bash - Enables the Azure Cloud Shell
try-dotnet - Enables Try .NET
try-dotnet-class - Enables Try .NET with class scaffolding
try-dotnet-method - Enables Try .NET with method scaffolding

For the Azure Cloud Shell and PowerShell Cloud Shell, users can only run commands against their own Azure
account.

Snippet syntax reference

Syntax:

:::code language="<language>" source="<path>" <attribute>="<attribute-value>":::

IMPORTANT
This syntax is a block Markdown extension. It must be used on its own line.

<language> (optional)
Language of the code snippet. For more information, see the Supported languages section later in this
article.
<path> (mandatory)

Relative path in the file system that indicates the code snippet file to reference.
<attribute> and <attribute-value> (optional)

Used together to specify how the code should be retrieved from the file and how it should be displayed:
range : 1,3-5 A range of lines. This example includes lines 1, 3, 4, and 5.
id : snippet_Create The ID of the snippet that needs to be inserted from the code file. This value
cannot co-exist with range.
highlight : 2-4,6 Range and/or numbers of lines that need to be highlighted in the generated
code snippet. The numbering is relative to the lines displayed (as specified by range or id), not the
file.
interactive : cloudshell-powershell , cloudshell-bash , try-dotnet , try-dotnet-class ,
try-dotnet-method String value determines what kinds of interactivity are enabled.
For details about tag name representation in code snippet source files by language, see the DocFX
guidelines.

Supported languages
The Docs Authoring Pack includes a feature to provide statement completion and validation of the available
language identifiers for code fence blocks.
Fenced code blocks
NAME VA L ID A L IA SES

.NET Core CLI dotnetcli

NAME VA L ID A L IA SES

1C 1c

ABNF abnf

Access logs accesslog

Ada ada

ARM assembler armasm , arm

AVR assembler avrasm

ActionScript actionscript , as

Alan alan , i

AngelScript angelscript , asc

ANTLR antlr

Apache apache , apacheconf

AppleScript applescript , osascript

Arcade arcade

AsciiDoc asciidoc , adoc

AspectJ aspectj

ASPX aspx

ASP.NET (C#) aspx-csharp

ASP.NET (VB) aspx-vb

AutoHotkey autohotkey

AutoIt autoit

Awk awk , mawk , nawk , gawk

Axapta axapta

AzCopy azcopy

Azure CLI azurecli

NAME VA L ID A L IA SES

Azure CLI (Interactive) azurecli-interactive

Azure Powershell azurepowershell

Azure Powershell (Interactive) azurepowershell-interactive

Bash bash , sh , zsh

Basic basic

BNF bnf

C c

C# csharp , cs

C# (Interactive) csharp-interactive

C++ cpp , c , cc , h , c++ , h++ , hpp

C++/CX cppcx

C++/WinRT cppwinrt

C/AL cal

Cache Object Script cos , cls

CMake cmake , cmake.in

Coq coq

CSP csp

CSS css

Cap'n Proto capnproto , capnp

Clojure clojure , clj

CoffeeScript coffeescript , coffee , cson , iced

Crmsh crmsh , crm , pcmk

Crystal crystal , cr

Cypher (Neo4j) cypher

NAME VA L ID A L IA SES

D d

DAX Power BI dax

DNS Zone file dns , zone , bind

DOS dos , bat , cmd

Dart dart

Delphi delphi , dpr , dfm , pas , pascal , freepascal ,

lazarus , lpr , lfm

Diff diff , patch

Django django , jinja

Dockerfile dockerfile , docker

dsconfig dsconfig

DTS (Device Tree) dts

Dust dust , dst

Dylan dylan

EBNF ebnf

Elixir elixir

Elm elm

Erlang erlang , erl

Excel excel , xls , xlsx

Extempore extempore , xtlang , xtm

F# fsharp , fs

FIX fix

Fortran fortran , f90 , f95

G-Code gcode , nc

Gams gams , gms

NAME VA L ID A L IA SES

GAUSS gauss , gss

GDScript godot , gdscript

Gherkin gherkin

GN for Ninja gn , gni

Go go , golang

Golo golo , gololang

Gradle gradle

Groovy groovy

HTML html , xhtml

HTTP http , https

Haml haml

Handlebars handlebars , hbs , html.hbs , html.handlebars

Haskell haskell , hs

Haxe haxe , hx

Hy hy , hylang

Ini ini

Inform7 inform7 , i7

IRPF90 irpf90

JSON json

Java java , jsp

JavaScript javascript , js , jsx

Kotlin kotlin , kt

Kusto kusto

Leaf leaf
NAME VA L ID A L IA SES

Lasso lasso , ls , lassoscript

Less less

LDIF ldif

Lisp lisp

LiveCode Server livecodeserver

LiveScript livescript , ls

Lua lua

Makefile makefile , mk , mak

Markdown markdown , md , mkdown , mkd

Mathematica mathematica , mma , wl

Matlab matlab

Maxima maxima

Maya Embedded Language mel

Mercury mercury

mIRC Scripting Language mirc , mrc

Mizar mizar

Managed Object Format mof

Mojolicious mojolicious

Monkey monkey

Moonscript moonscript , moon

MS Graph (Interactive) msgraph-interactive

N1QL n1ql

NSIS nsis

Nginx nginx , nginxconf

NAME VA L ID A L IA SES

Nimrod nimrod , nim

Nix nix

OCaml ocaml , ml

Objective C objectivec , mm , objc , obj-c

OpenGL Shading Language glsl

OpenSCAD openscad , scad

Oracle Rules Language ruleslanguage

Oxygene oxygene

PF pf , pf.conf

PHP php , php3 , php4 , php5 , php6

Parser3 parser3

Perl perl , pl , pm

Plaintext no highlight plaintext

Pony pony

PostgreSQL & PL/pgSQL pgsql , postgres , postgresql

PowerShell powershell , ps

PowerShell (Interactive) powershell-interactive

Processing processing

Prolog prolog

Properties properties

Protocol Buffers protobuf

Puppet puppet , pp

Python python , py , gyp

Python profiler results profile

NAME VA L ID A L IA SES

Q# qsharp

Q k , kdb

QML qml

R r

Razor CSHTML cshtml , razor , razor-cshtml

ReasonML reasonml , re

RenderMan RIB rib

RenderMan RSL rsl

Roboconf graph , instances

Robot Framework robot , rf

RPM spec files rpm-specfile , rpm , spec , rpm-spec , specfile

Ruby ruby , rb , gemspec , podspec , thor , irb

Rust rust , rs

SAS SAS , sas

SCSS scss

SQL sql

STEP Part 21 p21 , step , stp

Scala scala

Scheme scheme

Scilab scilab , sci

Shape Expressions shexc

Shell shell , console

Smali smali

Smalltalk smalltalk , st
NAME VA L ID A L IA SES

Solidity solidity , sol

Stan stan

Stata stata

Structured Text iecst , scl , stl , structured-text

Stylus stylus , styl

SubUnit subunit

Supercollider supercollider , sc

Swift swift

Tcl tcl , tk

Terraform (HCL) terraform , tf , hcl

Test Anything Protocol tap

TeX tex

Thrift thrift

TOML toml

TP tp

Twig twig , craftcms

TypeScript typescript , ts

VB.NET vbnet , vb

VBScript vbscript , vbs

VHDL vhdl

Vala vala

Verilog verilog , v

Vim Script vim

X++ xpp
 NAME VA L ID A L IA SES

x86 Assembly x86asm

XL xl , tao

XQuery xquery , xpath , xq

XAML xaml

XML xml , xhtml , rss , atom , xjb , xsd , xsl , plist

YAML yml , yaml

Zephir zephir , zep

TIP
The Docs Authoring Pack, Dev Lang Completion feature uses the first valid alias when multiple aliases are available.

Next steps
For information on text formatting for content types other than code, see Text formatting guidelines.
 Text formatting guidelines
3/5/2020 • 3 minutes to read • Edit Online

Consistent and appropriate use of bold, italic, and code style for text elements improves readability and helps avoid
misunderstandings.

Bold
Use bold for UI elements, such as menu selections, dialog box names, and input field names.
Examples
This : In Solution Explorer , right-click the project node, and then select Add > New Item .
Not this : In Solution Explorer, right-click the project node, and then select Add > New Item.
Not this : In Solution Explorer, right-click the project node, and then select Add > New Item.

Italics
Use italics for:
Introducing new terms along with a definition or explanation.
File names, folder names, paths.
User input.
Examples
This : In App Service, an app runs in an App Service plan. An App Service plan defines a set of compute
resources for a web app to run on.
Not this : In App Service, an app runs in an "App Service plan." An App Service plan defines a set of compute
resources for a web app to run on.
This : Replace the code in HttpTriggerCSharp.cs with the following code.
Not this : Replace the code in HttpTriggerCSharp.cs with the following code.
This : Enter ContosoUniversity for the Name , and then select Add .
Not this : Enter "ContosoUniversity" for the Name , and then select Add .

Code style
Use code style for:
Code elements, such as method names, property names, and language keywords.
SQL commands
NuGet package names
Command-line commands
Database table and column names
Resource names that should not be localized (such as virtual machine names)
URLs that you don't want to be clickable
Why? Older style guides specify bold for many of these text elements. However, most articles are localized, and
code style tells the translator to leave that part of the text untranslated.
Code style can be inline (surrounded by `) or fenced code blocks (surrounded by ```) that span multiple lines. Put
longer code snippets and paths in fenced code blocks.
Examples using inline styles
This : By default, the Entity Framework interprets a property that's named Id or ClassnameID as the primary
key.
Not this : By default, the Entity Framework interprets a property that's named Id or ClassnameID as the primary
key.
This : The Microsoft.EntityFrameworkCore package provides runtime support for EF Core.
Not this : The Microsoft.EntityFrameworkCore package provides runtime support for EF Core.
Examples of fenced code blocks
This : No commands are sent to the database by statements that just change an IQueryable , such as the
following code:

```csharp
var students = context.Students.Where(s => s.LastName == "Davolio")
```

Not this : No commands are sent to the database by statements that just change an IQuer yable , such as
var students = context.Students.Where(s => s.LastName == "Davolio") .
This : For example, to run the Get-ServiceLog.ps1 script in the C:\Scripts directory, type:

```powershell
C:\Scripts\Get-ServiceLog.ps1
```

Not this : For example, to run the Get-Ser viceLog.ps1 script in the C:\Scripts directory, type:
"C:\Scripts\Get-ServiceLog.ps1."
All fenced code blocks must have an approved language tag. For a list of support language tags, see How to
include code in docs.

Headings and link text

Don't apply an inline style such as italics, bold, or code to headings or hyperlink text.
Why?
People rely on standard hyperlink text to identify text elements as clickable links. Styling a link as code, for example,
can obscure the fact that the text is a link. Headings have their own styles and mixing other styles in them looks
bad.
Examples
This : The function.json file is generated by the NuGet package Microsoft.NET.Sdk.Functions.
Not this : The function.json file is generated by the NuGet package Microsoft.NET.Sdk.Functions .
This :

### The Microsoft.NET.Sdk.Functions package

Not this :
 ### The `Microsoft.NET.Sdk.Functions` package

Keys and keyboard shortcuts

When referring to keys or key combinations, follow these conventions:
Capitalize the first letter of key names.
Don't apply an inline style such as italics, bold, or code.
Use "+" to join keys that are pressed at the same time.
Examples
This : Select Alt+Ctrl+S.
Not this : Press ALT+CTRL+S .
Not this : Hit ALT+CTRL+S .
For more information, see Describing interactions with UI.

Exceptions
Style guidelines aren't rigid rules. In contexts where they harm readability, do something different. For example, an
HTML table with mostly code elements might look too busy with code styling everywhere. You might choose bold
styling in that context.
If you choose an alternate text style where code is normally called for, make sure it's okay for the text to be
translated in localized versions of the article. Code is the only style that automatically prevents translation. For
scenarios where you want to prevent localization without using code style, see Non-localized strings.
 Use links in documentation
4/3/2020 • 10 minutes to read • Edit Online

This article describes how to use hyperlinks from pages hosted at docs.microsoft.com. Links are easy to add
into markdown with a few varying conventions. Links point users to content in the same page, in other
neighboring pages, or on external sites and URLs.
The docs.microsoft.com site backend uses Open Publishing Services (OPS), which supports CommonMark-
compliant markdown parsed through the Markdig parsing engine. This markdown flavor is mostly compatible
with GitHub Flavored Markdown (GFM), as most docs are stored in GitHub and can be edited there. Additional
functionality is added through Markdown extensions.

IMPORTANT
All links must be secure ( https vs http ) whenever the target supports it (which the vast majority should).

Link text
The words that you include in link text should be friendly. In other words, they should be normal English
words or the title of the page that you're linking to.

IMPORTANT
Do not use "click here." It's bad for search engine optimization and doesn't adequately describe the target.

Correct:
For more information, see the [contributor guide index](https://github.com/Azure/azure-
content/blob/master/contributor-guide/contributor-guide-index.md).

For more details, see the [SET TRANSACTION ISOLATION LEVEL](https://docs.microsoft.com/sql/t-

sql/statements/set-transaction-isolation-level-transact-sql) reference.

Incorrect:
For more details, see [https://msdn.microsoft.com/library/ms173763.aspx]
(https://msdn.microsoft.com/library/ms173763.aspx).

For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-

guide/contributor-guide-index.md).

Links from one article to another

There are two types of hyperlinks supported by the publishing system: URLs and file links .
A URL link can be a URL path that is relative to the root of docs.microsoft.com, or an absolute URL that
includes the full URL syntax (for example, https://github.com/MicrosoftDocs/PowerShell-Docs ).
Use URL links when linking to content outside of the current docset or between autogenerated reference
and conceptual articles within the docset.
The simplest way to create a relative link is to copy the URL from your browser, then remove
https://docs.microsoft.com/en-us from the value you paste into markdown.
Do not include locales in URLs for Microsoft properties (for example, remove "/en-us" from the
 URL).
A file link is used to link from one article to another within the docset.
All file paths use forward-slash ( / ) characters instead of back-slash characters.
An article links to another article in the same directory:
[link text](article-name.md)

An article links to an article in the parent directory of the current directory:

[link text](../article-name.md)

An article links to an article in a subdirectory of the current directory:

[link text](directory/article-name.md)

An article links to an article in a subdirectory of the parent directory of the current directory:
[link text](../directory/article-name.md)

NOTE
None of the previous examples use the ~/ as part of the link. To link to an absolute path that begins at the root of
the repository, start the link with / . Including the ~/ produces invalid links when navigating the source repositories
on GitHub. Starting the path with / resolves correctly.

Structure of links on docs.microsoft.com

Content published on docs.microsoft.com has the following URL structure:

https://docs.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=
<view-name>]

Examples:

https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview
https://docs.microsoft.com/en-us/powershell/azure/overview?view=azurermps-5.1.1

<locale> - identifies the language of the article (example: en-us or de-de)

<product-service> - the name of the product or service (example: powershell, dotnet, or azure)
[<feature-service>] - (optional) the name of the product's feature or subservice (example: csharp or load-
balancer)
[<subfolder>] - (optional) the name of a subfolder within a feature
<topic> - the name of the article file for the topic (example: load-balancer-overview or overview)
[?view=\<view-name>] - (optional) the view name used by the version selector for content that has multiple
versions available (example: azps-3.5.0)
 TIP
In most cases, articles in the same docset have the same <product-service> URL fragment. For example:
Same docset
https://docs.microsoft.com/dotnet/core/get-started
https://docs.microsoft.com/dotnet/framework/install
Different docset
https://docs.microsoft.com/dotnet/core/get-started
https://docs.microsoft.com/visualstudio/whats-new

Bookmark links
For a bookmark link to a heading in the current file, use a hash symbol followed by the lowercase words of the
heading. Remove punctuation from the heading and replace spaces with dashes:

[Managed Disks](#managed-disks)

To link to a bookmark heading in another article, use the file-relative or site-relative link plus a hash symbol,
followed by the words of the heading. Remove punctuation from the heading and replace spaces with dashes:

[Managed Disks](../../linux/overview.md#managed-disks)

You can also copy the bookmark link from the URL. To find the URL, hover your mouse over the heading line
on docs.microsoft.com. You should see a link icon appear:

Click the link icon and then copy the bookmark anchor text from the URL (that is, the part after the hash).

NOTE
The Docs Extension also has tools to help create links.

Explicit anchor links

Adding explicit anchor links using the <a> HTML tag isn't required or recommended, except in hub and
landing pages. Instead, use the auto-generated bookmarks as described in bookmark links. For hub and
landing pages, declare anchors as follows:

## <a id="anchortext" />Header text

or

## <a name="anchortext" />Header text

And the following to link to the anchor:

To go to a section on the same page:

[text](#anchortext)

To go to a section on another page.

[text](filename.md#anchortext)

NOTE
Anchor text must always be lowercase and not contain spaces.

XRef (cross reference) links

XRef links are the recommended way to link to APIs, because they're validated at build time. To link to auto-
generated API reference pages in the current docset or other docsets, use XRef links with the unique ID (UID)
of the type or member.

TIP
You can use the Docs Markdown extension for VS Code (part of the Docs Authoring Pack) to insert .NET XRref links that
are surfaced in the .NET API Browser.

Check if the API you want to link to is on docs.microsoft.com by typing all or some of its full name in the .NET
API browser or Windows UWP search box. If you don't see any results displayed, the type isn't yet on
docs.microsoft.com.
You can use one of the following syntaxes:
Auto-links:

<xref:UID>
<xref:UID?displayProperty=nameWithType>

By default, link text shows only the member or type name. The optional displayProperty=nameWithType
query parameter produces fully qualified link text, that is, namespace.type for types, and
type.member for type members, including enumeration type members.
Markdown-style links:

[link text](xref:UID)

Use Markdown-style links for XRef when you want to customize the link text that's displayed.
Examples:
<xref :System.String> displays as String
<xref :System.String?displayProper ty=nameWithType> displays as System.String
 [String class](xref :System.String) displays as String class.
The displayProperty=fullName query parameter works the same way as displayProperty=nameWithType for
classes. That is, the link text becomes namespace.classname . However, for members, the link text displays as
namespace.classname.membername , which may be undesirable.

NOTE
UIDs are case sensitive. For example, <xref:System.Object> resolves correctly but <xref:system.object> does not.

XRef build warnings and incremental builds

An incremental build only builds files that have changed or been affected by a change. If you see a build
warning about an invalid XREF link, but the link is actually valid, this could be because the build was
incremental. The file causing the warning didn't change, so it wasn't built and past warnings were replayed.
The warning will disappear when the file changes or if you trigger a full build (you can start a full build on
ops.microsoft.com). This is a drawback to incremental builds, because DocFX can't detect a data update inside
the XREF service.
Determine the UID
The UID is usually the fully qualified class or member name. There are at least two ways to determine the UID:
Right-click on the Docs page for a type or member, select View source , and then copy the content
value for ms.assetid :

Use the autocomplete site by appending some or all of the name of the type to the URL. For example,
entering https://xref.docs.microsoft.com/autocomplete?text=Writeline in the address bar of your
browser displays all the types and methods that contain Writeline in their name, along with their UID.
Verify the UID
To test if you have the correct UID, replace System.String in the following URL with your UID, and then paste
it into the address bar of a browser:
https://xref.docs.microsoft.com/query?uid=System.String

TIP
The UID in the URL is case-sensitive, and if you're checking a method overload UID, don't include spaces between the
parameter types.

If you see something like the following, you have the correct UID:

[{"uid":"System.String","name":"String","fullName":"System.String","href":"https://docs.microsoft.com/dotn
et/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-
4.5,...xamarinmac-
3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"},
{"uid":"System.String","name":"String","fullName":"System.String","href":"https://docs.microsoft.com/dotne
t/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,netframework-
4.6,netframework-4.6.1,...,xamarinmac-
3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"}]
If you just see [] displayed on the page, you have the wrong UID.
Percent-encoding of URLs
Special characters in the UID need to be HTML encoded as follows:

C H A RA C T ER H T M L EN C O DIN G

` %60

# %23

* %2A

See a full list of percent-codes.

Encoding examples:
System.Threading.Tasks.Task``1 encodes as System.Threading.Tasks.Task%601 (see the section on
generic types)
System.Exception.#ctor encodes as System.Exception.%23ctor

System.Object.Equals* encodes as System.Object.Equals%2A

Generic types
Generic types are those types such as System.Collections.Generic.List<T> . If you browse to this type in the
.NET API browser and look at its URL, you see that <T> is written as -1 in the URL, which actually represents
`1 :
https://docs.microsoft.com/dotnet/api/system.collections.generic.list-1

To link to a generic type such as List<T> , encode the ` backtick character as %60 , as shown in the following
example:

<xref:System.Collections.Generic.List%601>

Methods
To link to a method, you can either link to the general method page by adding an asterisk ( * ) after the
method name, or to a specific overload. For example, use the general page when you want to link to the
<xref:System.Object.Equals%2A?displayProperty=nameWithType> method without specific parameter types. The
asterisk character is encoded as %2A . For example:
<xref:System.Object.Equals%2a?displayProperty=nameWithType> links to Object.Equals
To link to a specific overload, add parenthesis after the method name and include the full type name of each
parameter. Do not put a space character between the type names or the link won't work. For example:
<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> links to
Object.Equals(Object, Object)

Links from includes

Because include files are located in another directory, you must use longer relative paths. To link to an article
from an include file, use this format:
 [link text](../articles/folder/article-name.md)

TIP
The Docs Authoring Pack extension for Visual Studio Code helps you insert relative links and bookmarks correctly
without the tedium of figuring out paths.

Links in selectors
A selector is a navigation component that appears in a docs article as a drop-down list. When a reader selects
a value in the drop-down, the browser opens the selected article. Typically the selector list contains links to
closely related articles, for example the same subject matter in multiple programming languages or a closely
related series of articles.
If you have selectors that are embedded in an include, use the following link structure:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]

- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Reference-style links
You can use reference-style links to make your source content easier to read. Reference-style links replace
inline link syntax with simplified syntax that allows you to move the long URLs to the end of the article. Here's
Daring Fireball 's example:
Inline text:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Link references at the end of the article:

<!--Reference links in article-->

[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Make sure that you include the space after the colon, before the link. When you link to other technical articles,
if you forget to include the space, the link will be broken in the published article.

Links to pages that are not part of the technical documentation set
To link to a page on another Microsoft property (such as a pricing page, SLA page, or anything else that is not
a documentation article), use an absolute URL, but omit the locale. The goal here is that links work in GitHub
and on the rendered site:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)
Links to third-party sites
The best user experience minimizes sending users to another site. So base any links to third-party sites, which
we do sometimes need, on this info:
Accountability : Link to third-party content when it's the third-party's information to share. For example,
it's not Microsoft's place to tell people how to use Android developer tools--that is Google's story to tell. If
we need to, we can explain how to use Android developer tools with Azure, but Google should tell the story
of how to use their tools.
PM signoff : Request that Microsoft sign off on third-party content. By linking to it, we are saying
something about our trust in it and our obligation if people follow the instructions.
Freshness reviews : Make sure that the third-party info is still current, correct, and relevant, and that the
link hasn't changed.
Offsite : Make users aware that they are going to another site. If the context does not make that clear, add a
qualifying phrase. For example: "Prerequisites include the Android Developer Tools, which you can
download on the Android Studio site."
Next steps : It's fine to add a link to, say, an MVP blog in a "Next steps" section. Again, just make sure that
users understand they'll be leaving the site.
Legal : We are covered legally under Links to Third Par ty Sites in the Terms of Use footer on every
microsoft.com page.
 Docs Authoring Pack for VS Code
3/5/2020 • 7 minutes to read • Edit Online

The Docs Authoring Pack is a collection of VS Code extensions to aid with Markdown authoring for
docs.microsoft.com. The pack is available in the VS Code Marketplace and contains the following extensions:
Docs Markdown: Provides Markdown authoring assistance for docs.microsoft.com (Docs) content, including
basic Markdown support and support for custom Markdown syntax in Docs, such as alerts, code snippets, and
non-localizable text. Now also includes some basic YAML authoring assistance, such as inserting TOC entries.
markdownlint: A popular Markdown linter by David Anson to help make sure your Markdown is valid.
Code Spell Checker: A fully offline spell checker by Street Side Software.
Docs Preview: Uses the docs.microsoft.com CSS for more accurate Markdown preview, including custom
Markdown.
Docs Article Templates: Allows users to scaffold Learn modules and apply Markdown skeleton content to new
files.
Docs YAML: Provides Docs YAML schema validation and auto-complete.
Docs Images: Provides image compression and resizing for folders and individual files to help authors of
docs.microsoft.com.

Prerequisites and assumptions

To insert relative links, images, and other embedded content with the Docs Markdown extension, you must have
your VS Code workspace scoped to the root of your cloned Open Publishing System (OPS) repo. For example, if
you have cloned the docs repository to C:\git\SomeDocsRepo\ , then open that folder or a subfolder in VS Code:
File > Open Folder menu, or code C:\git\SomeDocsRepo\ from the command line.
Some syntax supported by the extension, such as alerts and snippets, are custom Markdown for OPS. Custom
Markdown will not render correctly unless published via OPS.

How to use the Docs Markdown extension

To access the Docs Markdown menu, type ALT+M. You can click or use the up and down arrows to select the
command you want. Or you can type to start filtering, then hit ENTER when the function you want is highlighted in
the menu.
See the Docs Markdown readme for an up-to-date list of commands.

How to generate a master redirect file

The Docs Markdown extension includes a script to generate or update a master redirection file for a repo, based on
the redirect_url metadata in individual files. This script checks every Markdown file in the repo for redirect_url ,
adds the redirection metadata to the master redirection file (.openpublishing.redirection.json) for the repo, and
moves the redirected files to a folder outside the repo. To run the script:
1. Select F1 to open the VS Code command palette.
2. Start typing "Docs: Generate..."
3. Select the command Docs: Generate master redirection file .
4. When the script finishes running, the redirection results will show in the VS Code output pane, and the removed
Markdown files will be added to the Docs Authoring\redirects folder under your default path.
5. Review the results. If they are as expected, submit a pull request to update the repo.

How to assign keyboard shortcuts

1. Type CTRL+K then Ctrl+S to open the Keyboard Shor tcuts list.
2. Search for the command, such as formatBold , for which you want to create a custom key binding.
3. Click the plus that appears near the command name when you mouse over the line.
4. After a new input box is visible, type the keyboard shortcut you want to bind to that particular command.
For example, to use the common shortcut for bold, type Ctrl+B.
5. It's a good idea to insert a when clause into your key binding, so it won't be available in files other than
Markdown. To do this, open keybindings.json and insert the following line below the command name (be
sure to add a comma between lines):
"when": "editorTextFocus && editorLangId == 'markdown'"

Your completed custom key binding should look like this in keybindings.json:

[
{
"key": "ctrl+b",
"command": "formatBold",
"when": "editorTextFocus && editorLangId == 'markdown'"
}
]

TIP
Place your key bindings in this file to overwrite the defaults

6. Save keybindings.json.
For more information on key bindings, see the VS Code docs.

How to show the legacy "Gauntlet" toolbar

Former users of the extension code-named "Gauntlet" will notice that the authoring toolbar no longer appears at
the bottom of the VS Code window when the Docs Markdown Extension is installed. This is because the toolbar
took up a large space on the VS Code status bar and did not follow best practices for extension UX, so it is
deprecated in the new extension. However, you can optionally show the toolbar by updating your VS Code
settings.json file as follows:
1. In VS Code, go to File > Preferences > Settings or select Ctrl+,.
2. Select User Settings to change the settings for all VS Code workspaces or Workspace Settings to
change them for just the current workspace.
3. Select Extensions > Docs Markdown Extension Configuration , and then select Show the legacy
toolbar in the bottom status bar .
Once you've made your selection, VS Code updates the settings.json file. You will then be prompted to reload the
window for the changes to take effect.
Newer commands added to the extension will not be available from the toolbar.

How to use Docs templates

The Docs Article Templates extension lets writers in VS Code pull a Markdown template from a centralized store
and apply it to a file. Templates can help ensure that required metadata is included in articles, that content
standards are followed, and so on. Templates are managed as Markdown files in a public GitHub repository.
To apply a template in VS Code
1. Ensure the Docs Article Templates extension is installed and enabled.
2. If you don't have the Docs Markdown extension installed, click F1 to open the command palette, start typing
"template" to filter, then click Docs: Template . If you do have Docs Markdown installed, you can use either the
command palette or click Alt+M to bring up the Docs Markdown QuickPick menu, then select Template from
the list.
3. Select the desired template from the list that appears.
To add your GitHub ID and/or Microsoft alias to your VS Code settings
The Templates extension supports three dynamic metadata fields: author, ms.author, and ms.date. That means that
if a template creator uses these fields in the metadata header of a Markdown template, they will be auto-populated
in your file when you apply the template, as follows:

M ETA DATA F IEL D VA L UE

author Your GitHub alias, if specified in your VS Code settings file.

ms.author Your Microsoft alias, if specified in your VS Code settings file. If

you are not a Microsoft employee, leave unspecified.

ms.date The current date in the Docs-supported format, MM/DD/YYYY .

The date is not automatically updated if you subsequently
update the file - you must update it manually. This field is
used to indicate the "article freshness".

To set author and/or ms.author

1. In VS Code, go to File > Preferences > Settings or select Ctrl+,.
2. Select User settings to change the settings for all VS Code workspaces, or Workspace settings to change them
for just the current workspace.
3. In the Default Settings pane on the left, find Docs Ar ticle Templates Extension Configuration , click the
pencil icon next to the desired setting, then click Replace in Settings.
4. The User settings pane will open side by side, with a new entry at the bottom.
5. Add your GitHub ID or Microsoft email alias, as appropriate, and save the file.
6. You might need to close and restart VS Code for the changes to take effect.
7. Now, when you apply a template that uses dynamic fields, your GitHub ID and/or Microsoft alias will be auto-
populated in the metadata header.
To make a new template available in VS Code
1. Draft your template as a Markdown file.
2. Submit a pull request to the templates folder of the MicrosoftDocs/content-templates repo.
The docs.microsoft.com team will review your template and merge the PR if it meets docs.microsoft.com style
guidelines. Once merged, the template will be available to all users of the Docs Article Templates extension.

Demo several features

Here's a short video that demonstrates the following features of the Docs Authoring Pack:
YAML files
Support for "Docs: Link to file in repo"
Markdown files
Update "ms.date" Metadata Value context menu option
Code auto-completion support for code-fence language identifiers
Unrecognized code-fence language identifier warnings / auto correction support
Sort selection ascending (A to Z)
Sort selection descending (Z to A)

Contribution expectations
The Docs Authoring Pack extension is open source and available for contributions to anyone with a GitHub
account. There is a dedicated internal Microsoft team that actively works on this project. This team monitors issues
and pull requests. The service level agreement (SLA) and expectation of getting a pull request reviewed is currently
one week. The team is undergoing automation efforts to improve this turn around time.

Next steps
Explore the various features available in the Docs Authoring Pack, Visual Studio Code extension.
Dev lang completion
Image compression
Metadata updates
Reformat table
Smart quote replacement
Sort redirects
Sort selection
 Dev lang completion
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Markdown extension. The Docs Markdown extension is part of the Docs Authoring Pack,
there is no need to install it separately.

Summary
Contributors need assistance determining the valid language identifiers (dev langs) that can follow triple-backticks
(code fence openings) in a Markdown file. Unfortunately, build-time validation of dev langs doesn't exist. The result
is disparate representations of a single language within the same conceptual docset.
Consider C# as an example. Contributors have used c# , C# , cs , csharp , and others as dev lang representations
of the language. Which of the preceding representations is correct?
The Dev lang completion feature dispels the confusion by displaying a list of known dev langs. Upon selecting a
dev lang name from IntelliSense:
The code fence is closed.
The caret is positioned in the code fence.

Preferences
It's not possible to disable this feature. The following settings are available:
Display commonly used dev langs
Display all known dev langs
Display commonly used dev langs
Only a subset of the valid dev langs will be used in a single docset. To enhance the user experience:
1. In Visual Studio Code, open the docset to the root directory.
2. Select File > Preferences > Settings and filter by Docs Markdown Extension.
3. Click the Edit in settings.json link in the Markdown: Docset Languages section.
4. Add the following markdown.docsetLanguages property to the settings.json file:

{
"markdown.docsetLanguages": [

]
}

5. Position your caret in the property's empty array, and activate IntelliSense (via Ctrl + Space). A list of
known dev lang names appears.
6. Add dev lang names to the array until you're satisfied with the list. For example, the following list will display
four dev lang names to the user after typing triple-ticks:
 {
"markdown.docsetLanguages": [
".NET Core CLI",
"C#",
"Markdown",
"YAML"
]
}

7. Save your changes to the settings.json file.

WARNING
An empty markdown.docsetLanguages array causes all known dev langs to display.

Display all known dev langs

By default, all known dev lang names are displayed in IntelliSense. This setting overrides the
markdown.docsetLanguages property described in Display commonly used dev langs.

To change this setting:

1. Select File > Preferences > Settings and filter by Docs Markdown Extension.
2. Toggle the setting in the Markdown: All Available Languages section.

In action
Below is a brief demonstration of this feature:
 Image compression
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Images extension. The Docs Markdown extension is part of the Docs Authoring Pack, there
is no need to install it separately.

Summary
All documentation is provided via the web, with the exception of PDF versions of docs. When serving static content,
it is best to minimize the number of bytes sent over the wire. One way to do that is to compress images at rest.
The Docs Authoring Pack extension includes image compression context menu items. The following image types /
extensions are supported:
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.webp
The lossless image compression algorithms are used, where applicable.

Compress image
From the Explorer navigation pane, right-click on an image file - then select the Compress image option. The
image is then compressed.

Compress images in folder

From the Explorer navigation pane, right-click on a folder containing images - then select the Compress images
in folder option. All images in the folder are compressed.

Considerations
Large resolution images are implicitly resized. The maximum dimensions are based on the platform suggested max
width of 1,200px . The max is only used when images are larger than they are recommended to be, and they will
maintain the aspect ratio when automatically resized.

Preferences
The maximum dimensions are configurable, but a default max width of 1200 pixels exists. To configure the max
dimensions, select File -> Preferences -> Settings and filter by "Docs Image Extension" .
 NOTE
A value of 0 in either the Max Width or Max Height will simply ignore resolution variances.

In action
Below is a brief demonstration of this feature.
 Update metadata
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Markdown extension. The Docs Markdown extension is part of the Docs Authoring Pack,
there is no need to install it separately.

Summary
In a Markdown (*.md) file, there are two contextual menu items specific to metadata. When you right-click
anywhere in the text editor, you will see something similar to the following menu items:

Update ms.date metadata value

Selecting the Update ms.date Metadata Value option will set the current Markdown files ms.date value to
today's date. If the document does not have an ms.date metadata field, no action is taken.

Update implicit metadata values

Selecting the Update implicit metadata values option will find and replace all possible metadata values that
could be implicitly specified. Metadata values are implicitly specified in the docfx.json file, under the
build/fileMetadata node. Each key value pair in the fileMetadata node represents metadata defaults. For
example, a Markdown file in the top-level/sub-folder directory that omits the ms.author metadata value could
implicitly specify a default value to use in the fileMetadata node.
 {
"build": {
"fileMetadata": {
"ms.author": {
"top-level/sub-folder/**/**.md": "dapine"
}
}
}
}

In this case, all Markdown files would implicitly take on the ms.author: dapine metadata value. The feature acts on
these implicit settings found in the docfx.json file. If a Markdown file contains metadata with values that are
explicitly set to something other than the implicit values, they are overridden.
Consider the following Markdown file metadata, where this Markdown file resides in top-level/sub-
folder/includes/example.md :

---
ms.author: someone-else
---

# Content

If the Update implicit metadata values option was executed on this file, with the assumed docfx.json content
from above the metadata value would be updated to ms.author: dapine .

---
ms.author: dapine
---

# Content

In action
Below is a brief demonstration of this feature.
 Reformat Markdown tables
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Markdown extension. The Docs Markdown extension is part of the Docs Authoring Pack,
there is no need to install it separately.

Summary
In a Markdown (*.md) file, when you select a complete table - two table formatting context menu items are now
available. Right-click on the selected Markdown table to open the context menu. You will see something similar to
the following menu items:

TIP
This feature does not work with multiple table selections, but rather is intended for a single Markdown table. You must
select the entire table, including headings for desired results.

Consolidate selected table

Selecting the Consolidate selected table option will collapse the table headings and contents with only a single
space on either side of each value.

Evenly distribute selected table

Selecting the Evenly distribute selected table option will calculate the longest value in each column and evenly
distribute all the other values accordingly with space.
Considerations
The feature will not impact the rendering of the table, but it will help to improve the readability of the table - thus
making more maintainable. The reformatting table feature will keep column alignment intact.
Consider the following table:

| Column1 | This is a long column name | Column3 | |

|--:|---------|:--:|:----|
|| | | |
| | | | a value |
|| | | |
| | | This is a long value | but why? |
| | | | |
| | | | Here is something |
| | | | |

After being "evenly distributed":

| Column1 | This is a long column name | Column3 | |

|--------:|----------------------------|:--------------------:|:------------------|
| | | | |
| | | | a value |
| | | | |
| | | This is a long value | but why? |
| | | | |
| | | | Here is something |
| | | | |

After being "consolidated":

| Column1 | This is a long column name | Column3 | |

|-:|--|:-:|:-|
| | | | |
| | | | a value |
| | | | |
| | | This is a long value | but why? |
| | | | |
| | | | Here is something |
| | | | |

In action
Below is a brief demonstration of this feature.
 Smart quote replacement
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Markdown extension. The Docs Markdown extension is part of the Docs Authoring Pack,
there is no need to install it separately.

Summary
Content developers are responsible for authoring some of the most advanced features of modern technology and
intelligence, yet our tooling today prefers the usage of "dumb quotes" in Markdown. The antonym of course being
"smart quotes". Smart quotes are common with ideal typographies, but not preferred with Markdown and
rendered HTML.
When working on a Microsoft Word document for example, you may have noticed that when you hold the Shift
and type a " Microsoft Word quickly replaces the " character with a smart quote equivalent “ character.

DESC RIP T IO N UN IC O DE SM A RT Q UOT E REP L A C EM EN T

Double left quote \u201c “ "

Double right quote \u201d ” "

Single left quote \u2018 ‘ '

Single right quote \u2019 ’ '

In a Markdown (*.md) file, when you paste in text or as you update content - this feature will actively evaluate the
content and automatically replace values accordingly.

NOTE
The smart quote replacement feature also replaces other characters, such as but not limited to; ( ©, ™, ®, • , subscript and
superscript characters). This is useful when pasting text from Word documents.

Preferences
This feature is optional, but defaults to true . To toggle this feature on or off:
1. Select File > Preferences > Settings and filter by Docs Markdown Extension.
2. Toggle the setting in the Markdown: Replace Smar t Quotes section.

In action
Below is a brief demonstration of this feature.
 Sort redirects
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Markdown extension. The Docs Markdown extension is part of the Docs Authoring Pack,
there is no need to install it separately.

Summary
With the evolution of a docs.microsoft.com docset, some Markdown files eventually will be deleted. When a
Markdown file is deleted, we're required to provide a redirect so that any reference to the deleted article is properly
resolved via the redirect. Redirections are specified in the .openpublishing.redirection.json file.
1. Open the Command Palette, press F1 (or ⇧⌘P on macOS)
2. Type: Docs: Sor t master redirection file
3. Select the command to execute it
4. Observe changes to .openpublishing.redirection.json file

Considerations
The concept of "daisy chaining" exists with how the .openpublishing.redirection.json file was originally designed.
Over time, files added as a redirect will eventually become stale. This happens when file A is deleted and needs a
redirect to file B, then later file B is deleted and then redirects to file C. Ideally, both entries would point to C - so
that A redirects to C, and B remains the same. This is a minor performance gain, and the feature is actively being
worked on.

In action
Below is a brief demonstration of this feature.
 Sort selection
3/5/2020 • 2 minutes to read • Edit Online

Extension name
The Docs Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature
is included in the Docs Markdown extension. The Docs Markdown extension is part of the Docs Authoring Pack,
there is no need to install it separately.

Summary
In a Markdown (*.md) file, when you've made a selection - two sorting context menu items are now available.
Right-click on the selected text to open the context menu. You will see something similar to the following menu
items:

TIP
The sorting context menu items are hidden until there is a valid selection in the Visual Studio Code text editor.

Sort selection ascending (A to Z)

Selecting the Sor t selection ascending (A to Z) option will sort the entire selection ascending, alphabetically
from A to Z.

Sort selection descending (Z to A)

Selecting the Sor t selection descending (Z to A) option will sort the entire selection ascending, alphabetically
from Z to A.
Considerations
The underlying sorting mechanism uses natural language sorting. This makes it more powerful and
comprehensive than standard sorting. Consider the following table:

| Column1 | Column2 |
|---------|----------------------------------------|
| 1 | Number 1 |
| Aa | The first letter in the alphabet |
| Ab | The first letter in the alphabet |
| C | The a letter after A in the alphabet |
| M | Somewhere in the middle? |
| 2 | Number 2 |
| X | The alphabet letter is towards the end |
| Z | The last letter in the alphabet |
| 11 | Number 11 |

Without natural language sorting, the order for Column1 would have been 1, 11, 2, etc. but instead it understands
that 11 is greater than 2 - resulting in the following ascending order:

| Column1 | Column2 |
|---------|----------------------------------------|
| 1 | Number 1 |
| 2 | Number 2 |
| 11 | Number 11 |
| Aa | The first letter in the alphabet |
| Ab | The first letter in the alphabet |
| C | The a letter after A in the alphabet |
| M | Somewhere in the middle? |
| X | The alphabet letter is towards the end |
| Z | The last letter in the alphabet |

In action
Below is a brief demonstration of this feature.
 Learn how to contribute to the .NET docs repositories
4/21/2020 • 12 minutes to read • Edit Online

Thank you for your interest in contributing to the .NET documentation!

This document covers the process for contributing to the articles and code samples that are hosted on the .NET
documentation site. Contributions may be as simple as typo corrections or as complex as new articles.
The .NET documentation site is built from multiple repositories:
.NET conceptual articles
Code samples and snippets
.NET Standard, .NET Core, .NET Framework API reference
.NET Compiler Platform SDK reference
ML.NET API reference
Issues for all these repositories are tracked at the dotnet/docs repository.

Guidelines for contributions

We appreciate community contributions to docs. The following list shows some guiding rules that you should keep
in mind when you're contributing to the .NET documentation:
DON'T surprise us with large pull requests. Instead, file an issue and start a discussion so we can agree on a
direction before you invest a large amount of time.
DO follow these instructions and voice and tone guidelines.
DO use the template file as the starting point of your work.
DO create a separate branch on your fork before working on the articles.
DO follow the GitHub Flow workflow.
DO blog and tweet (or whatever) about your contributions, frequently!
Following these guidelines will ensure a better experience for you and for us.

Make a contribution to .NET docs

Step 1: Skip this step for small changes. If you're interested in writing new content or in thoroughly revising
existing content, open an issue describing what you want to do.
The content inside the docs folder is organized into sections that are reflected in the Table of Contents (TOC).
Define where the topic will be located in the TOC. Get feedback on your proposal.
-or-
You can also choose from existing issues for which community contributions are welcome. Projects for .NET
Community contributors lists many of the issues that are available for community contributors. Depending on your
interests and level of commitment, you can choose from issues in the following categories:
Maintenance . This category includes fairly simple contributions, such as fixing broken or incorrect links,
adding missing code examples, or addressing limited content issues. In some cases, these issues may
concern large numbers of files. In that case, you should let us know what you'd like to work on before you
begin. Add a comment on the issue to tell us that you are working on it.
 Content updates . Given the enormity of the doc set, content easily becomes outdated and requires
revision. In addition, for a variety of reason, some content has been duplicated or even triplicated. Updating
content involves making sure that individual topics are current or revising content in a feature area to
eliminate duplication and ensure that all unique content is preserved in the smaller documentation set.
New content authoring . If you're interested in authoring your own topic, these issues list topics that we
know we'd like to add to our doc set. Let us know before you begin working on a topic, though. If you're
interested in writing a topic that isn't listed here, open an issue.
You can also look at our open issues list and volunteer to work on the ones you're interested in. We use the up-for-
grabs label to tag issues identified for community contribution. These usually require minimal context and are well-
suited for first issues. We encourage experienced contributors in our community to look at any issues of interest.
When you find one, add a comment to ask if it's open.
Once you've picked a task to work on, follow the get started guide to create a GitHub account and setup your
environment.
Step 2: Fork the /dotnet/docs , dotnet/samples , dotnet/dotnet-api-docs , dotnet/roslyn-api-docs , or
dotnet/ml-api-docs repos as needed and create a branch for your changes.
For small changes, see the instructions on editing in GitHub on the home page of the contributor guide.
Step 3: Make the changes on this new branch.
If it's a new topic, you can use this template file as your starting point. It contains the writing guidelines and also
explains the metadata required for each article, such as author information.
Navigate to the folder that corresponds to the TOC location determined for your article in step 1. That folder
contains the Markdown files for all articles in that section. If necessary, create a new folder to place the files for
your content. The main article for that section is called index.md. For images and other static resources, create a
subfolder called media inside the folder that contains your article, if it doesn't already exist. Inside the media
folder, create a subfolder with the article name (except for the index file). Sample code should be in the
dotnet/samples repo, as described in the section on samples.

Be sure to follow the proper Markdown syntax. For examples of common , see the template and markdown
cheatsheet.

Example structure
docs
/about
/core
/porting
porting-overview.md
/media
/porting-overview
portability_report.png

Step 4: Submit a Pull Request (PR) from your branch to the master branch.

IMPORTANT
The comment automation functionality is not available on any of the .NET docs repositories at this time. Members of the .NET
docs team will review and merge your PR.

Each PR should usually address one issue at a time. The PR can modify one or multiple files. If you're addressing
multiple fixes on different files, separate PRs are preferred. If you are creating samples as well as updating
markdown, you'll need to create a separate PR for samples.
If your PR fixes an existing issue, add the Fixes #Issue_Number keyword to the commit message or PR description.
That way, the issue is automatically closed when the PR is merged. For more information, see Closing issues via
commit messages.
The .NET team will review your PR and let you know if there are any other updates/changes necessary in order to
approve it.
Step 5: Make any necessary updates to your branch as discussed with the team.
The maintainers will merge your PR into the master branch once feedback has been applied and your change is
approved.
We regularly push all commits from master branch into the live branch and then you'll be able to see your
contribution live at https://docs.microsoft.com/dotnet/. We typically publish daily during the work week.
Maintenance activities may delay publishing for a few days.

Contributing to samples
The dotnet/samples repo contains all the sample code that is part of any topic under the .NET documentation.
There are several different projects that are organized in sub-folders. These sub-folders are organized similarly to
the organization of the docs for .NET.
We make the following distinction for code that exists in our repository:
Samples: readers can download and run the samples. All samples should be complete applications or libraries.
Where the sample creates a library, it should include unit tests or an application that lets readers run the code.
They often use more than one technology, feature, or toolkit. The readme.md file for each sample will refer to
the article so that you can read more about the concepts covered in each sample.
Snippets: illustrate a smaller concept or task. They compile but they are not intended to be complete
applications. They should run correctly, but aren't an example application for a typical scenario. Instead, they are
designed to be as small as possible to illustrate a single concept or feature. These should be no more than a
single screen of code.
Code all lives in the dotnet/samples repository. We are working toward a model where our samples folder
structure matches our docs folder structure. Standards that we follow are:
The top level snippets folder contains snippets for small, focused samples.
API reference samples are placed in a folder following this pattern:
snippets/<language>/api/<namespace>/<apiname>.
Other top-level folders match the top level folders in the docs repository. For example, the docs repository has a
machine-learning/tutorials folder, and the samples for machine learning tutorials are in the samples/machine-
learning/tutorials folder.
In addition, all samples under the core and standard folders should build and run on all platforms supported by
.NET Core. Our CI build system will enforce that. The top level framework folder contains samples that are only built
and validated on Windows.
Sample projects should build and run on the widest set of platforms possible for the given sample. In practice, that
means building .NET Core-based console applications where possible. Samples that are specific to the web or a UI
framework should add those tools as needed. Examples include web applications, mobile apps, WPF or WinForms
apps, and so on.
We are working toward having a CI system in place for all code. When you make any updates to samples, make
sure each update is part of a buildable project. Ideally, add tests for correctness on samples as well.
Each complete sample that you create should contain a readme.md file. This file should contain a short description
of the sample (one or two paragraphs). Your readme.md should tell readers what they will learn by exploring this
sample. The readme.md file should also contain a link to the live document on the .NET documentation site. To
determine where a given file in the repository maps to that site, replace /docs in the repository path with
https://docs.microsoft.com/dotnet .

Your topic will also contain links to the sample. Link directly to the sample's folder on GitHub.
Writing a new snippet or sample
1. Your sample must be par t of a buildable project . Where possible, the projects should build on all
platforms supported by .NET Core. Exceptions to this are samples that demonstrate a platform specific
feature or platform specific tool.
2. Your sample should conform to the corefx coding style to maintain consistency.
Additionally, we prefer the use of static methods rather than instance methods when demonstrating
something that doesn't require instantiating a new object.
3. Your sample should include appropriate exception handling . It should handle all exceptions that are
likely to be thrown in the context of the sample. For example, a sample that calls the Console.ReadLine
method to retrieve user input should use appropriate exception handling when the input string is passed as
an argument to a method. Similarly, if your sample expects a method call to fail, the resulting exception must
be handled. Always handle the specific exceptions thrown by the method, rather than base class exceptions
such as Exception or SystemException.
4. If your sample builds a standalone package, you must include the runtimes used by our CI build system, in
addition to any runtimes used by your sample:
win7-x64
win8-x64
win81-x64
ubuntu.16.04-x64

We will have a CI system in place to build these projects shortly.

To create a sample:
1. File an issue or add a comment to an existing one that you are working on it.
2. Write the topic that explains the concepts demonstrated in your sample (example:
docs/standard/linq/where-clause.md ).

3. Write your sample (example: WhereClause-Sample1.cs ).

4. Create a Program.cs with a Main entry point that calls your samples. If there is already one there, add the call
to your sample:

public class Program

{
public void Main(string[] args)
{
WhereClause1.QuerySyntaxExample();

// Add the method syntax as an example.

WhereClause1.MethodSyntaxExample();
}
}

You build any .NET Core snippet or sample using the .NET Core CLI, which can be installed with the .NET Core SDK.
To build and run your sample:
1. Go to the sample folder and build to check for errors:

dotnet build

2. Run your sample:

dotnet run

3. Add a readme.md to the root directory of your sample.

This should include a brief description of the code, and refer people to the article that references the sample.
Except where noted, all samples build from the command line on any platform supported by .NET Core. There are a
few samples that are specific to Visual Studio and require Visual Studio 2017 or later. In addition, some samples
show platform specific features and will require a specific platform. Other samples and snippets require the .NET
Framework and will run on Windows platforms, and will need the Developer Pack for the target Framework
version.

The C# interactive experience

All samples included in an article use a language tag to indicate the source language. Short code samples in C# can
use the csharp-interactive language tag to specify a C# sample that runs in the browser. (Inline code samples use
the csharp-interactive tag, for snippets included from source, use the code-csharp-interactive tag.) These code
samples display a code window and an output window in the article. The output window displays any output from
executing the interactive code once the user has run the sample.
The C# interactive experience changes how we work with samples. Visitors can run the sample to see the results. A
number of factors help determine if the sample or corresponding text should include information about the output.
When to display the expected output without running the sample
Articles intended for beginners should provide output so that readers can compare the output of their work
with the expected answer.
Samples where the output is integral to the topic should display that output. For example, articles on formatted
text should show the text format without running the sample.
When both the sample and the expected output is short, consider showing the output. It saves a bit of time.
Articles explaining how current culture or invariant culture affect output should explain the expected output. The
interactive REPL (Read Evaluate Print Loop) runs on a Linux-based host. The default culture, and the invariant
culture produce different output on different operating systems and machines. The article should explain the
output in Windows, Linux, and Mac systems.
When to exclude expected output from the sample
Articles where the sample generates a larger output should not include that in comments. It obscures the code
once the sample has been run.
Articles where the sample demonstrates a topic, but the output isn't integral to understanding it. For example,
code that runs a LINQ query to explain query syntax and then display every item in the output collection.

NOTE
You might notice that some of the topics are not currently following all the guidelines specified here. We're working towards
achieving consistency throughout the site. Check the list of open issues we're currently tracking for that specific goal.
Contributing to International content
Contributions for Machine Translated (MT) content are currently not accepted. In an effort to improve the quality of
MT content, we've transitioned to a Neural MT engine. We accept and encourage contributions for Human
Translated (HT) content, which is used to train the Neural MT engine. So over time, contributions to HT content will
improve the quality of both HT and MT. MT topics will have a disclaimer stating that part of the topic may be MT,
and the Edit button won't be displayed, as editing is disabled.

Contributor license agreement

You must sign the .NET Foundation Contribution License Agreement (CLA) before your PR is merged. This is a one-
time requirement for projects in the .NET Foundation. You can read more about Contribution License Agreements
(CLA) on Wikipedia.
The agreement: net-foundation-contribution-license-agreement.pdf
You don't have to sign the agreement up-front. You can clone, fork, and submit your PR as usual. When your PR is
created, it is classified by a CLA bot. If the change is small (for example, you fixed a typo), then the PR is labeled
with cla-not-required . Otherwise, it's classified as cla-required . Once you signed the CLA, the current and all
future pull requests are labeled as cla-signed .
 Labels and projects roadmap
4/7/2020 • 2 minutes to read • Edit Online

The .NET docs team makes extensive use of GitHub labels to organize our work. By filtering on combinations of
labels, we can quickly focus on sections of interest on the .NET docs website.
We also use GitHub projects to organize sprints and other goal-oriented epics.
This roadmap explains how we use these organizational tools and has links to handy filters we use to find areas of
interest.

Labels
If this is your first experience contributing to dotnet/docs, start with the up-for-grabs issues. These are issues that
have a more focused scope. They are a great way to make your first contribution. From the up-for-grabs view, you
can further filter issues based on areas and priority. We've identified good issues for beginners with the good-first-
issue if you want to try a smaller first contribution.
We use labels to classify issues in many different ways:
.NET Guides and sections of a guide.
Target release
Priority
You can combine a label from each set (guide, release, priority) to create a narrow focus to find issues you want to
work on.
Find a single .NET guide
We use labels for each of the architecture e-books and for each .NET Guide.

Architecture e-books are noted with the :book: guide prefix and have a light green background. These are the
long-form areas that cover recommended architecture. Here are current issues filtered for each of the .NET
architecture guides.
ASP.NET Core web apps
Blazor
Cloud Native
Docker lifecycle
gRPC
Modernizing w/ Windows containers
.NET Microservices
Serverless apps
This label style is also applied to the Framework design guidelines. This area has the same label design, but
community PRs are discouraged. This is material reprinted with permission and should not be edited.
Each .NET Guide is noted with the :books: Area prefix and has a dark blue background. Here are current issues
filtered for each of the .NET guides.
API Reference
Azure .NET SDK
C# Guide
Desktop Guide
F# Guide
ML.NET Guide
.NET Architecture Guide - Could be removed
.NET Core Guide
.NET for Apache Spark Guide
.NET Framework Guide
.NET Guide
Roslyn API Reference - could be removed.
Visual Basic Guide
Search one section of a guide

The .NET guides are large, so these labels further limit the scope by a section of a guide. Each .NET Guide subarea is
noted with the :card_file_box: Technology prefix and has a medium blue background. Many of these labels apply
to multiple guides, while others are in only one guide. After filtering on an area, add one of these labels to further
limit the scope of issues.
AppCompat
Async Task
C# Advanced concepts
C# compiler
C# Fundamentals
C# Get Started
C# Language Reference
C# Null safety
C# What's new
CLI
Data Access
Docker
Installers
LINQ
NCL
.NET Standard
Roslyn APIs
Security
WCF
WF
WIF
WinForms
WPF
Releases

Issues tagged for a specific release are noted with the :checkered_flag: Release: prefix and have a dark yellow
background.
.NET Core 2.2
.NET Core 3.0
.NET Framework 4.8
.NET 5
Priority
Priority labels are all P followed by a single digit. Lower numbers are higher priority:
P0
P1
P2
P3
What about the other labels?
There are many other labels used by the content teams to manage different classifications of issues. If you're not on
the content team, you can ignore these other labels.

Projects
We use projects in two ways:
Month YYYY project types: These are scrum boards for each month's working plan.
Long-running epics: These are used to organize tasks toward a goal when the work will occur over several
months.
 Metadata and Markdown template for .NET docs
4/7/2020 • 8 minutes to read • Edit Online

This dotnet/docs template contains examples of Markdown syntax, as well as guidance on setting the metadata.
When creating a Markdown file, you should copy the included template to a new file, fill out the metadata as
specified below, and set the H1 heading above to the title of the article.

Metadata

The required metadata block is in the following sample metadata block:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help
drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

You must have a space between the colon (:) and the value for a metadata element.
Colons in a value (for example, a title) break the metadata parser. In this case, surround the title with double
quotes (for example, title: "Writing .NET Core console apps: An advanced step-by-step guide" ).
title : Appears in search engine results. The title shouldn't be identical to the title in your H1 heading, and it
should contain 60 characters or less.
description : Summarizes the content of the article. It's usually shown in the search results page, but it isn't
used for search ranking. Its length should be 115-145 characters including spaces.
author : The author field should contain the GitHub username of the author.
ms.date : The date of the last significant update. Update this on existing articles if you reviewed and updated
the entire article. Small fixes, such as typos or similar do not warrant an update.
Other metadata is attached to each article, but we typically apply most metadata values at the folder level,
specified in docfx.json .

Basic Markdown, GFM, and special characters

You can learn the basics of Markdown, GitHub Flavored Markdown (GFM), and OPS specific extensions in the
Markdown reference article.
Markdown uses special characters such as *, `, and # for formatting. If you wish to include one of these characters
in your content, you must do one of two things:
Put a backslash before the special character to "escape" it (for example, \* for a *)
Use the HTML entity code for the character (for example, &#42; for a *).

File names
File names use the following rules:
 Contain only lowercase letters, numbers, and hyphens.
No spaces or punctuation characters. Use the hyphens to separate words and numbers in the file name.
Use action verbs that are specific, such as develop, buy, build, troubleshoot. No -ing words.
No small words - don't include a, and, the, in, or, etc.
Must be in Markdown and use the .md file extension.
Keep file names reasonably short. They are part of the URL for your articles.

Headings
Use sentence-style capitalization. Always capitalize the first word of a heading.

Text styling
Italics Use for files, folders, paths (for long items, split onto their own line), new terms.
Bold Use for UI elements.
Code Use for inline code, language keywords, NuGet package names, command-line commands, database table
and column names, and URLs that you don't want to be clickable.

Links
See the general article on Links for information about anchors, internal links, links to other documents, code
includes, and external links.
The .NET docs team uses the following conventions:
In most cases, we use the relative links and discourage the use of ~/ in links because relative links resolve in
the source on GitHub. However, whenever we link to a file in a dependent repo, we'll use the ~/ character to
provide the path. Because the files in the dependent repo are in a different location in GitHub the links won't
resolve correctly with relative links regardless of how they were written.
The C# language specification and the Visual Basic language specification are included in the .NET docs by
including the source from the language repositories. The markdown sources are managed in the csharplang
and vblang repositories.
Links to the spec must point to the source directories where those specs are included. For C#, it's
~/_csharplang/spec and for VB, it's ~/_vblang/spec , as in the following example:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Links to APIs
The build system has some extensions that allow us to link to .NET APIs without having to use external links. You
use one of the following syntax:
1. Auto-link: <xref:UID> or <xref:UID?displayProperty=nameWithType>

The displayProperty query parameter produces a fully qualified link text. By default, link text shows only
the member or type name.
2. Markdown link: [link text](xref:UID)

Use when you want to customize the link text displayed.

Examples:
 <xref:System.String> renders as String
<xref:System.String?displayProperty=nameWithType> renders as System.String
[String class](xref:System.String) renders as String class
For more information about using this notation, see Using cross reference.
Some UIDs contain the special characters `, # or *, the UID value needs to be HTML encoded as %60 , %23 and
%2A respectively. You'll sometimes see parentheses encoded but it's not a requirement.

Examples:
System.Threading.Tasks.Task`1 becomes System.Threading.Tasks.Task%601
System.Exception.#ctor becomes System.Exception.%23ctor
System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) becomes
System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

You can find the UIDs of types, a member overload list, or a particular overloaded member from
https://xref.docs.microsoft.com/autocomplete . The query string ?text=*\<type-member-name>* identifies the type
or member whose UIDs you'd like to see. For example,
https://xref.docs.microsoft.com/autocomplete?text=string.format retrieves the String.Format overloads. The tool
searches for the provided text query parameter in any part of the UID. For example, you can search for member
name (ToString), partial member name (ToStri), type and member name (Double.ToString), etc.
If you add a * (or %2A ) after the UID, the link then represents the overload page and not a specific API. For
example, you can use that when you want to link to the List<T>.BinarySearch Method page in a generic way
instead of a specific overload such as List<T>.BinarySearch(T, IComparer<T>). You can also use * to link to a
member page when the member is not overloaded; this saves you from having to include the parameter list in the
UID.
To link to a specific method overload, you must include the fully qualified type name of each of the method's
parameters. For example, <xref:System.DateTime.ToString> links to the parameterless DateTime.ToString method,
while <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> links to the
DateTime.ToString(String,IFormatProvider) method.
To link to a generic type, such as System.Collections.Generic.List<T>, you use the ` ( %60 ) character followed by the
number of generic type parameters. For example, <xref:System.Nullable%601> links to the System.Nullable<T>
type, while <xref:System.Func%602> links to the System.Func<T,TResult> delegate.

Code
The best way to include code is to include snippets from a working sample. Create your sample following the
instructions in the contributing to .NET article. The basic rules for including code are located in the general
guidance on code.
You can include the code using the following syntax:

[!code-<language>[<name>](<pathToFile><queryoption><queryoptionvalue>)]

-<language> (optional but recommended)

Language of the code snippet being referenced.
<name> (optional)

Name for the code snippet. It doesn't have any impact on the output HTML, but you can use it to
improve the readability of your Markdown source.
 <pathToFile> (mandatory)
Relative path in the file system that indicates the code snippet file to reference. This can be complicated
by the different repos that make up the .NET doc set. The .NET samples are in the dotnet/samples repo.
All snippet paths would start with ~/samples , the rest of the path being the path to the source from the
root of that repo.
<queryoption> (optional)

Used to specify how the code should be retrieved from the file:
# : #{tagname} (tag name) or #L{startlinenumber}-L{endlinenumber} (line range). We discourage
the use of line numbers because they are very brittle. Tag name is the preferred way of
referencing code snippets. Use meaningful tag names. (Many snippets were migrated from a
previous platform and the tags have names such as Snippet1 , Snippet2 etc. That practice is
much harder to maintain.)
range : ?range=1,3-5 A range of lines. This example includes lines 1, 3, 4, and 5.

We recommend using the tag name option whenever possible. The tag name is the name of a region or of a code
comment in the format of Snippettagname present in the source code. The following example shows how to refer
to the tag name BasicThrow :

[!code-csharp[csrefKeyword#1](~/samples/snippets/snippets/csharp/language-
reference/operators/ConditionalExamples.csConditionalRef)]

The relative path to the source in the dotnet/samples repo follows the ~/samples path.
And you can see how the snippet tags are structured in this source file. For details about tag name representation
in code snippet source files by language, see the DocFX guidelines.
The following example shows code included in all three .NET languages:

[!code-fsharp[ToPigLatin](../../../samples/snippets/fsharp/getting-started/pig-latin.fs#L1-L14)]
[!code-csharp[ADCreateDomain#2]
(../../../samples/snippets/csharp/VS_Snippets_CLR/ADCreateDomain/CS/source2.cs#2)]
[!code-vb[ADCreateDomain#2]
(../../../samples/snippets/visualbasic/VS_Snippets_CLR/ADCreateDomain/VB/source2.vb#2)]

Including snippets from full programs ensures that all code runs through our Continuous Integration (CI) system.
However, if you need to show something that causes compile time or runtime errors, you can use inline code
blocks.

Images
Static image or animated GIF


Linked image

[](https://dot.net)

Videos
Currently, you can embed both Channel 9 and YouTube videos with the following syntax:
Channel 9

> [!VIDEO <channel9_video_link>]

To get the video's correct URL, select the Embed tab below the video frame, and copy the URL from the <iframe>
element. For example:

> [!VIDEO https://channel9.msdn.com/Blogs/dotnet/NET-Core-20-Released/player]

YouTube
To get the video's correct URL, right-click on the video, select Copy Embed Code , and copy the URL from the
<iframe> element.

> [!VIDEO <youtube_video_link>]

For example:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

docs.microsoft extensions
docs.microsoft provides a few additional extensions to GitHub Flavored Markdown.
Checked lists
A custom style is available for lists. You can render lists with green check marks.

> [!div class="checklist"]

> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

This renders as:

How to create a .NET Core app
How to add a reference to the Microsoft.XmlSerializer.Generator package
How to edit your MyApp.csproj to add dependencies
How to add a class and an XmlSerializer
How to build and run the application
You can see an example of checked lists in action in the .NET Core docs.
Buttons
Button links:

> [!div class="button"]

> [button links](dotnet-contribute.md)

This renders as:

 B U T TO N
LINKS

You can see an example of buttons in action in the Visual Studio docs.
Step-by-steps

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

You can see an example of step-by-steps in action at the C# Guide.

 Voice and tone guidelines
4/3/2020 • 3 minutes to read • Edit Online

A wide variety of people including IT Pros and developers read your documents both to learn .NET and to use it in
their regular work. Your goal is to create great documentation that helps the reader on their journey. Our
guidelines help with that. Our style guide contains the following recommendations:
You can see examples of each of these as you read this style guide. We've written this guide following our
guidelines to provide examples for you to follow as you build documentation for .NET. We also provide contrasting
samples so you can see what articles look like when you don't follow our guidelines.

Use a conversational tone

Appropriate style
We want our documentation to have a conversational tone. You should feel as though you are having a
conversation with the author as you read any of our tutorials or explanations. For you, the experience should be
informal, conversational, and informative. Readers should feel as though they are listening to the author explain
the concepts to them.
Inappropriate style
One might see the contrast between a conversational style and the style one finds with more academic treatments
of technical topics. Those resources are very useful, but the authors have written those articles in a very different
style than our documentation. When one reads an academic journal, one finds a very different tone and a very
different style of writing. One feels that they are reading a dry account of a very dry topic.
The first paragraph above follows our recommendation conversational style. The second is a more academic style.
You see the difference immediately.

Write in second person

Appropriate style
You should write your articles as though you are speaking directly to the reader. You should use second person
often (as I just have in these two sentences). 2nd person doesn't always mean using the word 'you'. Write directly
to the reader. Write imperative sentences. Tell your reader what you want them to learn.
Inappropriate style
An author could also choose to write in third person. In that model, an author must find some pronoun or noun to
use when referring to the reader. A reader might often find this third person style less engaging and less enjoyable
to read.
The first paragraph follows our recommended style. The second uses third person. Please write in second person.
You probably found that much easier to read.

Use active voice

Write your articles in active voice. Active voice means that the subject of the sentence performs the action (verb) of
that sentence. It contrasts with passive voice, where the sentence is arranged such that the subject of the sentence
is acted upon. Contrast these two examples:

The compiler transformed source code into an executable.

 The source code was transformed into an executable by the compiler.

The first sentence uses active voice. The second sentence was written in passive voice. (Those two sentences
provide another example of each style).
We recommend active voice because it is more readable. Passive voice can be more difficult to read.

Target a fifth grade reading level

We provide this final guideline because many of our readers are not native English speakers. You are reaching an
international audience with your articles. Please take into account that they may not have the English vocabulary
you have.
However, you are still writing for technical professionals. You can assume that your readers have programming
knowledge and the specific vocabulary for programming terms. Object Oriented Programming, Class, and Object,
Function and Method are familiar terms. However, not everyone reading your articles has a formal computer
science degree. Terms like 'idempotent' probably need to be defined if you use it:

The Close() method is idempotent, meaning that you can call it multiple times and the effect is the same as if
you called it once.

Avoid future tense

In some non-English languages the concept of future tense is not the same as English. Using future tense can make
your documents harder to read. Additionally, when using the future tense, the obvious question is when. So if you
say 'Learning PowerShell will be good for you" - the obvious question for the reader is when will it be good?
Instead, just say "Learning PowerShell is good for you".

What is it - so what?
Whenever you introduce a new concept to the reader, define the concept and only then explain why it's useful. It's
important for reader to understand what something is before they can understand the benefits (or otherwise).
 Pull request review process for the .NET docs
repositories
4/3/2020 • 3 minutes to read • Edit Online

Many repositories don't have PR Merger webhooks enabled, which automatically merges minor PRs. This article
describes the PR review process for those repositories. The PR review process was designed with these goals:
1. Publish high-quality content from our team, product team members, and community members.
2. Provide timely, actionable feedback to authors in a consistent manner.
3. Facilitate discussion between authors and reviewers.
The processes continue to evolve as teams innovate, and as the platform matures.

Reviewers
One of the content team members reviews every PR. Content team members may request a review from the
specific product team members to verify technical accuracy. The content team uses GitHub's Code Ownership
feature to automatically request reviews from content team members. As part of this process, a reviewer may tag
other team members to review internal PRs. Team members see requested reviews from team members and
community members in the same queue.
Community members can review PRs and provide feedback as well. However, at least one member of the core
content team must approve any PR before it is merged.

Review process
Reviews follow one of the three paths based on the PR:
Small PRs - Small PRs are single bug fix: typos, broken links, small code changes, or similar changes.
Major contributions - Major contributions are significant edits to an existing article, new articles, or edits to a
number of articles.
Work in progress - Authors can request an in-progress review by opening a PR with the "[WIP]" tag in the
title. The "WIP" tag stands for "Work in Progress."
The processing used by the Contributor License Agreement (CLA) bot is a good guideline for the distinction
between "small" and "large" contributions. PRs that do not require the CLA to be signed are likely "small." PRs that
do require the CLA are likely "large."
Small PRs
The changes in small PRs are reviewed for accuracy, and checked using the build on the review site. Because they
are small, these PRs do not trigger a review of the entire article.
Reviewers may notice other small changes that would improve an article. If those changes are also small, suggest
them as review comments. If the suggested changes would trigger a larger review, open an issue and address those
later.
Larger changes
Larger PRs undergo a more thorough review. The following are all checked:
Sample code must be included in the PR, in source and as a downloadable zip file.
Sample code compiles and runs correctly.
 The article clearly describes the goals for the reader, and those goals are met.
The article meets style and grammar guidelines and follows our voice and tone principles.
All links should resolve correctly.
Content team members will review the PR, and submit the review with comments. If only minor changes are
requested, team members may "approve" the PR with the feedback. The author can then address the feedback and
merge the PR. Most reviews will request changes and when those changes are made, the reviewer will review
again.
If the edits require a technical review, the content team reviewer will request a review from the appropriate product
team member.
Review "WIP" pull requests
New authors may want feedback earlier in the process. They can open a PR adding the "[WIP]" label to the title. In a
comment, they can request an early review.
These early reviews are not as thorough as a full PR review. The content team will comment, but will not "approve"
or "request changes" using GitHub's review feature. These early reviews focus on the structure of the article: the
outline, the overall content, and the samples. These reviews do not include a thorough check for grammar and
correct links.

Respond to reviews
The author updates the PR to respond to comments marking each addressed comment with the "+1" reaction to
indicate it was addressed. If the author disagrees with the comment, or addresses the comment in a different, the
author adds a comment explaining their change.
The author @-mentions the original reviewer in a comment to request a new review.

Response time expectations

Content team members will typically review new PRs in under two business days. If it takes longer to review, one of
the team members will add a comment to acknowledge the PR and set expectations.
Once a review has been submitted, authors should try to respond to comments in a week or less. Volunteers may
not be able to meet these expectations because of other commitments. In those cases, team members ask if the
community author will update the PR. If not, the team member updates and merges the PR for them.
 Contributing to PowerShell documentation
4/3/2020 • 2 minutes to read • Edit Online

The Contributor's Guide is a collection of articles that explain the tools and processes we use to create
documentation at Microsoft. Some of these guides cover information that is common to any documentation set
published to docs.microsoft.com. Some of the guides are specific to how we write documentation for PowerShell.
The common articles are available in this centralized Contributor's Guide. The PowerShell Contributor Guide is
available Community section of the PowerShell documentation.
 Additional Git and GitHub resources
12/18/2019 • 2 minutes to read • Edit Online

If you are unfamiliar with Git or GitHub, these resources can help you learn, be productive, or answer questions.

Git source control resources

Git basics: This has a basic overview of how git works.
Pro Git e-book (web): This is a thorough git reference, in HTML format.
Pro Git e-book (PDF): Same as the preceding link, in PDF form.
Learn Git course from Codecademy: Git tutorial from Codeacademy.
Try Git course from Code School on Pluralsight: Git tutorial from Code School on Pluralsight.
Git and Github course from Udacity: Git and Github tutorial from Udacity.

GitHub resources
15-minute interactive primer: This is an online git tutorial. It exposes you to the basics of git.
Cheat sheets: A quick reference to common GitHub commands and workflows.
GitHub Guides: The home of GitHub documentation.
GitHub learning resources: Other useful GitHub resources.
GitHub training services: A listing of tutorials and training offerings from GitHub.
Glossary: A handy glossary of git and GitHub terms.
GitHub Student developer pack : Give students free access to the best developer tools.