Docs Authoring Pack

The Docs Authoring Pack provides a series of extensions to help docs.microsoft.com authors work better and more efficiently. You can read more about all of the Docs Authoring Pack features here in the overview guide. The Docs Authoring Pack provides the following extensions to help author content for docs.microsoft.com:

• Docs Markdown, which provides Markdown authoring assistance, including support for inserting custom Markdown syntax specific to docs.microsoft.com. The rest of this readme provides details on the Docs Markdown extension.
• Docs Preview, which uses the docs.microsoft.com CSS for more accurate Markdown preview, including custom Markdown.
• Docs YAML, which validates Docs .yml files against the appropriate YAML schemas.
• Docs Images, which compresses and resizes images.
• Docs Metadata, which speeds up editing of metadata throughout a Docs repository.
• Docs Article Templates, which allows users to apply Markdown skeleton content to new files.
• Docs Scaffolding, which automatically generates Learn modules based on standard patterns and automates renaming, inserting, deleting, and reordering units.
• Docs Linting, which provides markdown linting specific to docs.microsoft.com.
• Docs Visual Areas, which provides visualizations of tabs and zones specific to markdown files for docs.microsoft.com.
• markdownlint, a popular linter by David Anson.
• Code Spell Checker, a fully offline spell checker by Street Side Software.
• LinkCheckMD, which generates a report on the links in the document, including broken links.

How to use the Docs Markdown extension

To access the Docs Markdown Authoring 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 access the Docs commands from the VS Code command palette by hitting F1 and typing to filter. All the Docs commands begin with "Docs":

Prerequisites and assumptions

To accurately insert relative links, images, and other embedded content with Docs Markdown, you must have your VS Code workspace scoped to the root of your cloned OPS repo. Some syntax supported by the extension, such as alerts and snippets, are custom Markdown for Docs, and will not render correctly unless published via Docs.

For more information about the Docs Markdown commands, see the Docs Markdown readme.

How to use Docs Images extension

To access the Docs Images menu, right click on a folder or individual image file. Select Compress all images in folder or Compress image from the context menu.

For more information about the Docs Images extension, see the Docs Images readme.

How to use Docs YAML extension

• The code intellisense is more intelligent now; the extension can provide the intellisense according to the schema structure, not just text mapping. To invoke intellisense, hit CTRL + Space to view the list of schema options.
• The extension can generate an input template for object (including required properties and optional properties with default value).
• You can type a - and hit CTRL + Space to trigger the intellisense for generating a new array item.

Intellisense is automatically triggered by CTRL + Space to get what you can type.

For more information about the Docs YAML commands, see the Docs YAML readme.

How to use Docs Preview extension

You can open Docs Preview by opening a markdown document and clicking on the preview button. One opens the preview in your current window, and the other opens the markdown preview to the side. Alternatively you can hit Alt + M and select Preview or you can hit F1 and select Docs: Preview to open up the markdown preview panel.

For more information about the Docs Preview commands, see the Docs Preview readme.

How to use Docs Linting extension

Docs Authoring Pack also supports comes with custom linting rules to aid in catching errors many run into when contributing to docs. This should automatically work with Docs Authoring Pack, and you will see the output in the "Problems" pane.

For more information about the Docs Linting commands, see the Docs Linting readme.

Docs Markdown keyboard shortcuts and toolbar

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 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 Docs 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+,).

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

   

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

License

MIT