Open Publishing Services (OPS) implements DocFX Flavored Markdown (DFM), which is highly compatible with GitHub Flavored Markdown (GFM). DFM adds some functionality through Markdown extensions. As such, selected articles from the full OPS Authoring Guide are included in this guide for reference. (See "DFM and Markdown extensions" in the table of contents.) Microsoft employees can also refer to the "Authoring" section of the full OPS User Guide for additional details. It's available under the "Open Publishing Services" node in Writing/publishing resources.
All links must be secure (
http) whenever the target supports it (which the vast majority should).
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.
Do not use "click here." It's bad for SEO and doesn't adequately describe the target.
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://msdn.microsoft.com/library/ms173763.aspx) reference.
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
To create an inline link from a Docs technical article to another Docs technical article, use the following link syntax:
An article in a directory links to another article in the same directory:
An article links from a subdirectory to an article in the root directory:
An article in the root directory links to an article in a subdirectory:
An article in a subdirectory links to an article in another subdirectory:
Links to anchors
You do not have to create anchors. They're automatically generated at publishing time for all H2 headings. The only thing you have to do is create links to the H2 sections.
To link to a heading within the same article:
To link to an anchor in another article in the same subdirectory:
[Configure your profile](media-services-create-account.md#configure-your-profile)
To link to an anchor in another service subdirectory:
[Configure your profile](../directory/media-services-create-account.md#configure-your-profile)
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:
Links in selectors
If you have selectors that are embedded in an include--as does the Azure documentation team--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) -->
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:
I get 10 times more traffic from [Google] than from [Yahoo] or [MSN].
Link references at the end of the article:
<!--Reference links in article--> : http://google.com/ : http://search.yahoo.com/ : 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:
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: Have PMs 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.
Links to MSDN or TechNet
When you need to link to MSDN or TechNet, use the full link to the topic, and remove the "en-us" language locale from the link.
Links to Azure PowerShell reference content
The Azure PowerShell reference content has been through several changes since November 2016. Use the following guidelines for linking to this content from other articles on docs.microsoft.com.
Structure of the URL:
- For cmdlets:
- For conceptual topics:
The <moniker-name> portion is optional. If it's omitted, you will be directed to the latest version of the content. The <service-name> portion is one of the examples shown in the following base URLs:
- Azure PowerShell (AzureRM) content: https://docs.microsoft.com/powershell/azure/
- Azure PowerShell (ASM) content: https://docs.microsoft.com/powershell/azure/_servicemanagement_
- Azure Active Directory (AzureAD) PowerShell content: https://docs.microsoft.com/powershell/azure/_active-directory_
- Azure Service Fabric PowerShell: https://docs.microsoft.com/powershell/azure/_service-fabric_
- Azure Information Protection PowerShell: https://docs.microsoft.com/powershell/azure/_aip_
- Azure Elastic DB Jobs PowerShell: https://docs.microsoft.com/powershell/azure/_elasticdbjobs_
When you use these URLs, you will be redirected to the latest version of the content. This way, you don't have to specify a version moniker. And you won't have links to conceptual content that must be updated when the version changes.
To create the correct link, find the page that you want to link to in your browser, and copy the URL. Then, remove "https://docs.microsoft.com" and the locale info.
When you're linking from a TOC, you must use the full URL without the locale information.
[Get-AzureRmResourceGroup](/powershell/module/azurerm.resources/get-azurermresourcegroup) [Get-AzureRmResourceGroup](/powershell/module/azurerm.resources/get-azurermresourcegroup?view=azurermps-4.1.0) [New-AzureVM](/powershell/module/azure/new-azurevm?view=azuresmps-4.0.0) [New-AzureRmVM](/powershell/module/azurerm.compute/new-azurermvm) [Install Azure PowerShell for Service Management](/powershell/azure/servicemanagement/install-azurerm-ps) [Install Azure PowerShell](/powershell/azure/install-azurerm-ps)
FWLinks (Microsoft employees)
Avoid FWLinks in Docs content. Use FWLinks only as a last resort. For example, use one when you link to a page that doesn't yet have a URL, or when you link to a page and you know its URL will change.
If you must use an FWLink on a webpage, include the "p" parameter to make it a permanent redirect, as in the following example:
Make sure that your FWLink does not include "en-us" (or any other language locale) in its URL.
aka.ms links (Microsoft employees)
For now, do not use aka.ms links.