Open Publishing Services (OPS) implements "DocFX Flavored Markdown" (DFM), which is highly compatible with GitHub Flavored Markdown (GFM). DFM adds some additional functionality through Markup extensions. As such, selected topics from the full OPS Authoring Guide are included in this guide for reference (see "DFM & 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, which is available under the "Open Publishing Services" node in Writing/Publishing Resources.
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 are 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—you would 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. The reference style links replace the 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 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.
Link 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:
Linking to 3rd party sites
The best user experience minimizes sending users to another site. So base any links to 3rd party sites, which we do sometimes need, on this info:
- Accountability: Link to third-party content when the information you want to share is the third-party's information to share. For example, it's not Microsoft's job or 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 3rd 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 the 3rd party info is still current, correct, and relevant and that the link hasn’t changed
- Offsite: Make sure users are aware they are going to another site. If the context does not make that clear, add a qualifying phrase: Ex. “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 users understand they’ll be leaving the site
Link 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.
Use friendly link text for all links
The words you include in link text should be friendly - in other words, they should be normal English words or the title of the page you are 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).
Link 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 is omitted you will be directed to the latest version of the content. The <service-name> 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. This avoids the issue of having links to conceptual content that must be updated when the version changes.
To create the correct link, find the page you want to link to in your browser and copy the URL. Then, remove 'https://docs.microsoft.com' and the locale info.
When 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. FWLinks should be used only as a last resort, i.e. when you link to a page that doesn't yet have a URL, or you link to a page and you know its URL will change.
If you must use an FWLink on a web page, 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 them.