Docs.Microsoft.Com Markdown extension snippets

Docs.microsoft.com publishing extends base Markdown to add functionality for things we need in our documentation. For example, notes, and warnings. These extensions take the form of [!SOMETHING]. For example, [!NOTE] to insert a note section in a document. The following snippets for Atom.io and Visual Studio C​ode provide basic snippets that can save you some keystrokes when you need to use one of these extensions. The approved custom markdown extensions are documented in the Getting Started with Markdown article​.

By using snippets, you type a short piece of text, then hit tab and it will expand into the content of the snippet. For example, with the snippets below, typing note and hitting tab will expand into a note entry, ready for you to begin typing the body of the note.

These snippets cover the following Markdown extensions.

Extension or Section Snippet Shortform
Properties section at beginning of the document prop
[!NOTE] note
[!WARNING] warn
[!IMPORTANT] import
[!TIP] tip
[!VIDEO] video
[!INCLUDE] include

Snippets for Visual Studio Code

  1. Open Visual Studio Code.

  2. From the File menu, select Preferences, User snippets.

  3. From the list of languages, select Markdown. This will open a file named markdown.json.

  4. Merge the following with whatever is in the default. The following example includes the top level { and }. Replace the values in the properties entry with your name, workload, manager, editor, etc.; whatever defaults make sense for you.

    {
    "Properties": {
     "prefix": "prop",
     "body": [
       "---",
       "title: $1 | Microsoft Docs",
       "description: $2",
       "services: hdinsight",
       "documentationCenter: ''",
       "author: Blackmist",
       "manager: jhubbard",
       "editor: cgronlun",
       "tags: azure-portal",
       "",
       "ms.service: hdinsight",
       "ms.devlang: ''",
       "ms.topic: article",
       "ms.tgt_pltfrm: 'na'",
       "ms.workload: big-data",
       "ms.date: $3",
       "ms.author: larryfr",
       "",
       "---"
     ]
    },
    "Note": {
     "prefix": "note",
     "body": [
       "> [!NOTE]",
       "> "
     ]
    },
    "Important": {
     "prefix": "important",
     "body": [
       "> [!IMPORTANT]",
       "> "
     ]
    },
    "Warning": {
     "prefix": "warn",
     "body": [
       "> [!WARNING]",
       "> "
     ]
    },
    "Tip": {
     "prefix": "tip",
     "body": [
       "> [!TIP]",
       "> "
     ]
    },
    "Video": {
     "prefix": "video",
     "body": [
       ">[!VIDEO $1]"
     ]
    },
    "Include": {
     "prefix": "include",
     "body": [
       "[!INCLUDE [$1]($2)]"
     ]
    }​
    }
    

    NOTE: If you have other snippets before this, you will need to add a ',' charcter after the last snippet before these.

  5. Save and close the file.

Snippets for Atom.io

If you are using Atom.io, use the following steps to add snippets.

  1. Open Atom.io

  2. From the File menu, select Open your snippets.

  3. In the snippets.cscon document that opens, add the following at the end of the file. Replace the property entry information with your name, workload, manager, editor, etc.; whatever defaults make sense for you.

    '.source.gfm':
    'properties':
     'prefix': 'prop'
     'body': '---\n
       title: $1 | Microsoft Docs\n
       description: $2\n
       services: hdinsight\n
       documentationCenter: \'\'\n
       author: Blackmist\n
       manager: jhubbard\n
       editor: cgronlun\n
       tags: azure-portal\n
       \n
       ms.service: hdinsight\n
       ms.devlang: \'\'\n
       ms.topic: article\n
       ms.tgt_pltfrm: \'na\'\n
       ms.workload: big-data\n
       ms.date: $3\n
       ms.author: larryfr\n
       \n
       ---\n'
    'note':
     'prefix': 'note'
     'body': '> [!NOTE]\n> '
    'important':
     'prefix': 'import'
     'body': '> [!IMPORTANT]\n> '
    'warning':
     'prefix': 'warn'
     'body': '> [!WARNING]\n> '
    'tip':
     'prefix': 'tip'
     'body': '> [!TIP]\n> '
    'video':
     'prefix': 'video'
     'body': '> [!VIDEO $1]'
    'include':
     'prefix': 'include'
     'body': '[!INCLUDE [$1]($2)]'​
    
  4. Save and close the snippets.cson file.

Using snippets

Just type in the 'prefix' and hit tab. This will expand the text out to the 'body' of the snippet. For most snippets, this just adds the snippet body text. For example, aimport expands to '> [!IMPORTANT]' and saves you some typing. For entries like prop, video, and include, these include tab stops. Tab stops ($1, $2, etc.) insert the snippet text, then put your cursor where the first $# is within the text. You can then type some text, hit tab, and you move to the next highest number position in the snippet text.​