Learn Markdown Extension

Welcome to the Learn Markdown authoring extension! This extension provides Markdown authoring assistance for learn.microsoft.com (Learn) content, including basic Markdown support and support for custom Markdown syntax on Learn. We also now support some YAML authoring commands. Here's a quick demo - the rest of the readme provides details about using the extension. You can also get more details about all of the Learn Authoring Pack features here: Learn Authoring Pack Overview

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 Learn repo.

Some syntax supported by the extension, such as alerts and snippets, are custom Markdown for Learn, and will not render correctly unless published to Learn.

How to use the extension

To access the Learn 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 Learn commands from the VS Code command palette. Hit F1 to open the command palette and start typing to filter. All the Learn commands begin with "Learn".

The following commands are available in Markdown files:

The following commands are available in YAML files:

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.

1. Type CTRL+K then CTRL+S to open the Keyboard Shortcuts list.

2. Search for the command, such as formatBold, for which you want to create a custom keybinding.

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 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
   [
    {
    	"key": "ctrl+b",
    	"command": "formatBold",
    	"when": "editorTextFocus && editorLangId == 'markdown'"
    }
   ]
   

6. Save keybindings.json.

See Keybindings in the VS Code docs for more information.

How to show the docs-markdown toolbar

Users of the pre-release version of the extension will notice that the authoring toolbar no longer appears at the bottom of the VS Code window when the Learn Markdown extension is installed. This is because the toolbar took up a lot of 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 (CTRL+Comma).

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 Learn Markdown Extension Configuration, and select the pencil icon next to the desired setting, and select true. VS Code will automatically add the value to the settings.json file and you will be prompted to reload the window for the changes to take effect.

4. Now you will see the toolbar at the bottom of your VS Code window:

   

Context menus

There are multiple context menu options that have been added to the right mouse click button when editing markdown documents. This includes update metadata, and reformat tables. Or you can right mouse click on a markdown file or folder for the cleanup scripts context menu option.

Cleanup scripts

Cleanup functionality has been added to docs-markdown to move the experience of fixing validation closer to your development environment. Instead of having to wait until build time, you can proactively reduce the number of validation errors and warnings by running these cleanup scripts. Get started by hitting F1 and typing Learn: Cleanup or hit Alt+M and navigate to Cleanup... in the quick pick menu. Or right click on a file or folder in the explorer panel to see the clean up file option in the context menu.

Cleanup scripts available:

• Add periods to alt text: Adds a period at the end of alternate text for images if there isn't one already. This is an accessibility requirement to make screen readers pause appropriately at the end of alt text.
• Capitalization of metadata values: Lowercases certain metadata properties.
• Empty metadata: Removes metadata fields with no values.
• Single-valued metadata: Converts single value arrays of metadata into inline properties without array brackets.
• Microsoft links: Converts http:// to https:// for microsoft docs, azure, technet, and msdn. Removes hardcoded locales (en-us) from url.
• Single-valued metadata: Converts single-valued metadata from array to scalar format.
• Master redirection file: Adds redirect_url entries to the master redirect file and removes redirected Markdown files from the repo.
• Unused images and includes: Removes image and includes files that aren't being used in any parent file.
• Everything: Runs all the available cleanup scripts.

Collapse relative links

Added "Collapse relative links" context-menu item for markdown files. Within a markdown file, right-click to open the context menu. Select "Collapse relative links" to resolve relative links that are unnecessarily verbose. For example, if doc-1.md in the articles directory has a relative link such as ../../articles/sub/doc-2.md, it could be simplified to sub/doc-2.md.

Additionally, an explorer context-menu item has been added to expose this functionality for an entire directory structure. Righ-click on a folder, and select "Collapse relative links in folder" to ensure that all markdown files have their relative links collapsed.

Reformat Markdown tables

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:

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 |
|  |  |  |  |

Update metadata

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

Known issues

• [YAML TOC entries] The Learn-YAML schema validation falsely shows a "Matches a schema that is not allowed" linting error on optional attributes such as displayName. These entries are in fact valid, and we'll be updating the schema linting in an upcoming release.
• [YAML TOC entries] Depending on your settings related to spacing, sometimes attributes in nested TOC entries don't line up correctly. If you experience this issue, make sure all the attributes line up with the nested name attribute. A fix is in progress for this bug.
• [YAML TOC entries] Erroneous invalid location error when trying to add new top level entry after nested entry. A fix is in progress for this bug.
• [Learn Preview] Code blocks only preview in Dark theme, and some colorized text is unreadable in Light theme.
• [External bookmarks] Linux: File list is displayed but no headings are shown to select.
• [Includes] Linux: File list is displayed but no link is added after selection is made.

License

MIT