Create VSCode Snippets for Markdown Blog Workflows
Tags: vscode, markdown
Published: 2023-01-03 10:42:41

---
title: Create VSCode Snippets for Markdown Blog Workflows
published: true
date: 2023-01-03 15:09:34 UTC
tags: vscode, markdown
canonical_url: https://www.yongliangliu.com/blog/vscode-snippets/
---

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

```markdown
---
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](https://code.visualstudio.com/docs/editor/userdefinedsnippets).

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:

```js
{
	// 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:

```js
{
  "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`:

```js
{
  "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:

```js
{
  "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`:

```js
{
  "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

- [Snippets in Visual Studio Code](https://code.visualstudio.com/docs/editor/userdefinedsnippets)
- [How to insert current date time in vscode?](https://stackoverflow.com/questions/38780057/how-to-insert-current-date-time-in-vscode)