Markdown with VS Code

Posted on Edited on In ,

Preface

As I will be writing lots of Markdowns, I spend some time researching VS Code Markdown extensions and creating snippets to enhance the writing experience.

Extensions

markdownlint

markdownlint applies a set of linting rules to Markdown file.

To exclude certain rules, you can add following configuration to VS Code settings at .vscode/settings.json (This settings file only applies to Workspace level, which I recommend it over User level).

Below is an example to exclude inline-html from linting:

vscode/settings.json
1
2
3
4
"markdownlint.config": {
    // Exclude inline-html from linting
    "MD033": false
}

Coloring Header

Markdown Header Coloring colors Markdown header tags.

I use a dark theme called Shades of Purple for VS Code. In this theme, the heading syntax is not very prominent, as the author says he prefers the syntax to be as hidden as possible. I like this theme a lot, but my only complaint is this hidden heading syntax, hence I find this extension extremely helpful!

GitHub Style Preview

Markdown Preview GitHub Styling changes the built-in markdown to match GitHub’s styling.

Snippets

Code snippets are templates that make it easier to enter repeating code patterns, such as loops or conditional-statements.

From Snippets in VS Code. (You can try for in a JavaScript file with VS Code to learn how to use a snippet.)

Enable Quick Suggestion

Before using snippets in a Markdown file, quick suggestions in VS Code needs to be enabled. From the Intellisense page, it is enabled only for certain languages (Like JavaScript, TypeScript, JSON and etc.). Support for other languages (e.g. Python, Go and etc.) are managed by their corresponding extentions.

For Markdown, we can enable quick suggestions in VS Code settings (Code -> Preferences -> Settings):

  1. Once in the settings page, you can decide whether to apply this setting to User or Workspace level by toggle between User and Workspace. (I prefer to keep language specific settings at Workspace level though.)
  2. Go to the top right corner and look for “Open Settings (JSON)” button and click it.
  3. Type "[markdown]" and select [markdown] from the quick suggestion popup window (Because the settings file is JSON, so quick suggestion works there 😜).

Markdown Snippets

Then change the [markdown] settings to:

settings.json
1
2
3
4
5
6
7
8
9
"[markdown]": {
    "editor.unicodeHighlight.ambiguousCharacters": false,
    "editor.wordWrap": "on",
    "editor.quickSuggestions": {
        "other": true,
        "comments": false,
        "strings": false
    }
}

After that we can start adding customized snippets for Markdown in VS Code. Go to User Snippets (Code -> Preferences -> User Snippets) and select markdown.json. Below are snippets I used:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
  "link": {
    "description": "Insert link",
    "prefix": "lk",
    "body": "[${1:name}](${2:url})"
  },
  "link with clipboard url": {
    "description": "Insert link with url from clipboard",
    "prefix": "lku",
    "body": "[${1:name}]($CLIPBOARD)"
  },
  "link with clipboard text": {
    "description": "Insert link with name from clipboard",
    "prefix": "lkt",
    "body": "[$CLIPBOARD](${1:url})"
  },
  "image with clipboard url": {
    "description": "Insert image with url from clipboard",
    "prefix": "imgu",
    "body": "![${1:alt_text}]($CLIPBOARD)"
  },
  "link with header id": {
    // markdown specific for hexo
    "description": "[hexo]\n \"## Header something\" should be \n \"Header-something\"",
    "prefix": "lkh",
    "body": "[${1:name}](#${2:url})"
  },
  "table": {
    "description": "Insert table",
    "prefix": "table",
    "body": [
      "| Header1 | Header2 |",
      "| --- | --- |",
      "| content | content |",
      "| content | content |",
    ]
  },
  "more button": {
    // markdown specific for hexo, but can be used to put hidden comments in markdown
    "description": "[hexo]\n \"Read More >>\" button in blog article for hexo next theme",
    "prefix": "more",
    "body": "<!-- more -->"
  },
  "hr line": {
    // to obey markdownlint's MD035 - Horizontal rule style
    "description": "Insert consistent hr",
    "prefix": "hr",
    "body": "---"
  },
  "codeblock with language": {
    "description": "codeblock with frequently used languages",
    "prefix": "block",
    "body": [
      "```${1|python,diff,shell,json|}",
      "```"
    ]
  }
}

Referrence