Docs Markdown Extension
Welcome to the Docs Markdown authoring extension! This extension provides Markdown authoring assistance for docs.microsoft.com (Docs) content, including basic Markdown support and support for custom Markdown syntax on Docs. We also now support some YAML authoring commands. Here's a quick demo - the rest of the readme provides details about using the extension:
Prerequisites and assumptions
To accurately insert relative links, images, and other embedded content, you must have your VS Code workspace scoped to the root of your cloned Docs repo.
Some syntax supported by the extension, such as alerts and snippets, are custom Markdown for Docs, and will not render correctly unless published to Docs.
How to use the extension
To access the Docs Markdown menu, type
ALT+M. You can click or use up/down arrows to select the function you want, or type to start filtering, then hit
ENTER when the function you want is highlighted in the menu.
You can also now access the Docs commands from the VS Code command palette. Hit F1 to open the command palette and start typing to filter. All the Docs commands begin with "Docs":
The following commands are available in Markdown files:
|Preview the active topic in a side-by-side window using the Docs Preview extension, if it is installed.
|Format text bold.
|Format text italic.
||If one line or less is selected, formats text as
If multiple lines are selected, formats them as a fenced code block, and prompts you to select a programming language supported by Docs.
||Insert a Note, Important, Warning, or Tip.
Select Alert from the menu, then select the alert type. If you have previously selected text, it will be surrounded with the selected alert syntax. If no text is selected, a new alert will be added with placeholder text.
||Insert a new numbered list.
If multiple lines are selected, each will be a list item. To create a nested numbered list, tab from within the parent list.
||Insert a new bulleted list.
||Insert a Markdown table structure.
After you select the table command, specify the number of columns and rows in the format columns:rows, such as 3:4. Note that the maximum number of columns you can specify via this extension is 5, which is the recommended maximum for readability on docs.microsoft.com.
||Insert a column-based layout structure, or add a column to an existing structure. Optionally add the
span attribute to merge two to four columns together.
|Link to file in repo
||Insert a Markdown link to a file within the current repo.
|Link to web page
||Insert a Markdown link to a URI.
|Link to heading
||Open a sub-menu to link to a heading (bookmark) in the current file or in another file in the current repo.
|Link to XREF
||Search the Docs XREF Service to find and insert a link to a .NET API reference article, such as System.String.Length. Choose a display property: none (just the API name will be displayed as link text, such as "Length");
nameWithType (the API name and its immediate parent will be displayed, such as "String.Length");
fullName (the full API name will be displayed, such as "System.String.Length"). To provide custom link text, select the text first, then use this function to insert the XREF link.
||Within the Markdown body of a file, format text as non-localizable (
:::no-loc text="string":::). Within the YAML header of a Markdown file, add a metadata array to be populated with strings that should be non-localizable throughout the file (
||Insert a standard image, complex image, or icon. For standard and complex images, alternate text is required for accessibility. Either select the alt text before calling the Image command, or add it before you select the image source file. For complex images, type a detailed description between the
:::image-end::: tags. You can optionally add the
loc-scope attribute to standard and complex images to indicate that the scope of localization is different for the image than for the article or module that contains it. Icons should not have alt text and are not localized, so only the image source file should be specified.
||Find a file in the repo to embed in the current file.
||Find a code snippet in the repo to embed in the current file.
||Run one of the Docs Cleanup scripts (see Cleanup scripts below).
||Add an embedded video.
||Insert a Markdown authoring template, if the Docs Article Templates extension is installed.
The following commands are available in YAML files:
||Insert a basic TOC entry with the
href attributes, and select the file link to. By default, the H1 of the selected file is used as the
|TOC entry with optional attributes
||Insert a TOC entry with the following optional attributes as well as
displayName: Add alternative search terms for TOC filtering.
uid: Add an identifier for a Docs reference article, such as
expanded: Indicate that the node should be expanded by default.
||Insert a content-less parent node with a stub child (
no-loc YAML node. If you insert this node within a
metadata node, every matching string within the YAML file will be non-localizable. If you insert it within any other node, every matchinig string within that node will be non-localizable.
How to assign keyboard shortcuts
Default keyboard shortcuts are available for some commands, as noted in the table above. You can override them, or add shortcuts for other commands, using the VS Code keyboard shortcut mappings.
CTRL+S to open the Keyboard Shortcuts list.
Search for the command, such as
formatBold, for which you want to create a custom keybinding.
Click the plus that appears near the command name when you mouse over the line.
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
It's a good idea to insert a
when clause into your keybinding, 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 keybinding should look like this in keybindings.json:
// Place your key bindings in this file to overwrite the defaults
"when": "editorTextFocus && editorLangId == 'markdown'"