Skip to main content

Create VSCode Snippets for Markdown Blog Workflows

· 5 min read

Motivation​

I write my blog posts in Markdown and my personal site is powered by Gatbsy.js. Within a Markdown file, there are frontmatter and content.

  • Frontmatter is a YAML block that contains the post's metadata such as title, date and description. It will be parsed and used by the site generator to generate the post's page.
  • The content is simply Markdown-styled text.

For example, this post will look something like this in the source code:

---
title: Create VSCode Snippets for Markdown Blog Workflows
date: 2023-01-03T15:09:34Z
description: Utilize VSCode snippets to simplify the creation of new posts
tags: ["markdown", "vscode"]
---

## Motivation

I write my blog posts in Markdown and...

And the rest of the body text...

For the past year, what I had to do when creating a new post was to copy the frontmatter from an existing post and then manually update it. This was not particularly pleasant. I am ashamed to admit that I just let laziness take over and did not do anything about it.

Let's fix this with VSCode snippets.

Create a snippet​

A VSCode snippet is a pre-defined text that can be inserted on a trigger. You can specify:

  • the triggering word or phrase
  • what should be inserted
    • can be a simple text
    • can have placeholders
    • can use variables

The details can be found in the VSCode documentation.

Let's go through my use case as a concrete example.

Steps​

What I want to achieve:

  • insert a frontmatter block with the key-value pairs required
  • auto-populate the date field with the current date-time in ISO 8601 format (this is the format that my parser expects)
  • insert some boilerplate headings for the content

1. Create a snippet file​

  1. Open VSCode
    • Open the repository of your choice, if any
    • My blog is contained in a folder called blogging, so I will open that folder
  2. Go to File > Preferences > Configure User Snippets
  3. Choose the scope of the snippet
    • In my case, I want to create a snippet just for my blog project, so I will choose New Snippets file for "blogging"...
  4. Give it a name
    • I will call it blog

With that, a file called blog.code-snippets will be created in the .vscode folder.

2. Create the snippet​

The blog.code-snippets file will be prepopulated with comments:

{
	// Place your blogging workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and 
	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope 
	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is 
	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are: 
	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. 
	// Placeholders with the same ids are connected.
	// Example:
	// "Print to console": {
	// 	"scope": "javascript,typescript",
	// 	"prefix": "log",
	// 	"body": [
	// 		"console.log('$1');",
	// 		"$2"
	// 	],
	// 	"description": "Log output to console"
	// }
}

Read the comments if you would like to understand the default example given. Let's clear the file and start from scratch.

Let's first give the snippet a name and a description:

{
  "Blog template": {
    "description": "Blog template for a new article"
  }
}

This is the metadata of the snippet. The name is what will be displayed in the IntelliSense dropdown. The description is what will be displayed in the snippet preview.

Let's choose a trigger word, here I am choosing a simple two character bt:

{
  "Blog template": {
    // ...omitted for brevity
    "prefix": ["bt"]
  }
}

This means that when I type bt in my project files and press ctrl+space, the snippet option will show up.

Lastly, let's add in what will be inserted when the snippet is applied:

{
  "Blog template": {
    // ...omitted for brevity
    "body": [
      "---",
      "title: ${1:blog title}",
      "date: $CURRENT_YEAR-$CURRENT_MONTH-${CURRENT_DATE}T$CURRENT_HOUR:$CURRENT_MINUTE:${CURRENT_SECOND}Z",
      "description: ${2:blog description}",
      "tags: [$3]",
      "---\n",
      "## Motivation\n",
      "$0",
      "## Conclusion\n",
      "## References\n"
    ]
  }
}

Some details to note:

  • the ${1:blog title}, ${2:blog description} and $3 are placeholders. When the snippet is applied, the cursor will be placed at the first placeholder and the user can tab to move or type to replace/fill in the spot. The tab order is ascending from 1 onwards
    • $0 is the final cursor position.
  • the CURRENT_YEAR, CURRENT_MONTH variables are predefined by VSCode
  • the items in the body array are joined together with a new line

Completed snippet​

For reference, this is the final content in .vscode/blog.code-snippets:

{
  "Blog template": {
    "description": "Blog template for a new article",
    "prefix": ["bt"],
    "body": [
      "---",
      "title: ${1:blog title}",
      "date: $CURRENT_YEAR-$CURRENT_MONTH-${CURRENT_DATE}T$CURRENT_HOUR:$CURRENT_MINUTE:${CURRENT_SECOND}Z",
      "description: ${2:blog description}",
      "tags: [$3]",
      "---\n",
      "## Motivation\n",
      "$0",
      "## Conclusion\n",
      "## References\n"
    ]
  }
}

Conclusion​

My use case is for creating blog posts, but code snippets can be used in other scenarios as well. If VSCode is your main editor, do take a moment to think about what snippets you can create to make your life easier.

References​