Mike Slinn
Mike Slinn

Jekyll Plugin Snippets

Published 2023-01-10.
Time to read: 2 minutes.

This page is part of the jekyll collection.

The Visual Studio Code extension called Snippet by Devon Ray is a real timesaver. I have defined snippets for my Jekyll plugins. To use the VSCode Snippets extension with my snippets, install the plugin, then save the following file to ~/.config/Code/User/snippets/html.json. For some reason, one of my 3 Windows machines needs that file installed to %AppData%\Code\User\snippets\html.json.

{
  // Place your snippets for html here. Each snippet is defined under a snippet name and has a prefix, body and
  // description. 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": {
  // 	"prefix": "log",
  // 	"body": [
  // 		"console.log('$1');",
  // 		"$2"
  // 	],
  // 	"description": "Log output to console"
  // }

  "Insert archive_display invocation": {
    "prefix": "archive_display",
    "body": [
      "{% archive_display $1 %}"
    ],
    "description": "Insert an archive_display plugin invocation"
  },

  "Insert basename invocation": {
    "prefix": "basename",
    "body": [
      "{{ 'blah/blah/filename.ext' | basename }}"
    ],
    "description": "Insert an basename filter invocation"
  },

  "Insert basename_without_extension invocation": {
    "prefix": "basename_without_extension",
    "body": [
      "{{ 'blah/blah/filename.ext' | basename_without_extension }}"
    ],
    "description": "Insert an basename_without_extension filter invocation"
  },

  "Insert days_since invocation": {
    "prefix": "days_since",
    "body": [
      "{{{ '1959' | days_since }}"
    ],
    "description": "Insert a days_since plugin invocation. A wide variety of date formats can be used."
  },

  "Insert dirname invocation": {
    "prefix": "dirname",
    "body": [
      "{{ 'blah/blah/filename.ext' | dirname }}"
    ],
    "description": "Insert an dirname filter invocation"
  },

  "Insert download_link invocation": {
    "prefix": "download_link",
    "body": [
      "{% download_link $1 %}"
    ],
    "description": "Insert an download_link filter invocation"
  },

  "Insert flexible_include maximal invocation": {
    "prefix": "flexible_include_max",
    "body": [
      "{% flexible_include copyButton dark do_not_escape download file='$1' label='$2' highlight='[\\w./\\-_]*django-admin[\\w.\\-_]*' number pre %}"
    ],
    "description": "Insert a flexible_include plugin invocation with all available options."
  },

  "Insert flexible_include minimal invocation": {
    "prefix": "flexible_include",
    "body": [
      "{% flexible_include file='$1' %}"
    ],
    "description": "Insert a flexible_include plugin invocation with only the necessary options."
  },

  "Insert from, to and until invocations": {
    "prefix": "from_to_until",
    "body": [
      "{{ '$1' | from: '$2' | to: '$3' | until: '$3' }}"
    ],
    "description": "Insert chained from, to and until plugin invocations."
  },

  "Insert href minimal invocation": {
    "prefix": "href",
    "body": [
      "{% href url='$1' $2 %}"
    ],
    "description": "Insert an href plugin invocation with only the necessary options."
  },

  "Insert href maximal invocation": {
    "prefix": "href_max",
    "body": [
      "{% href follow match target='none' url='$1' $2 %}"
    ],
    "description": "Insert an href plugin invocation using all available options."
  },

  "Insert img minimal invocation": {
    "prefix": "img",
    "body": [
      "{% img src='$1' %}"
    ],
    "description": "Insert a minimal href plugin invocation with only the necessary options."
  },

  "Insert img maximal invocation": {
    "prefix": "img_max",
    "body": [
      "{% img",
      "  align='left|center|right'",
      "  caption='$1'",
      "  class='rounded shadow'",
      "  size='initial|halfsize|fullsize|quartersize|eighthsize|15px|10%'",
      "  src='$2'",
      "  url='$3'",
      "  wrapper_class=''",
      "  wrapper_style=''",
      "%}"
    ],
    "description": "Insert a maximal href plugin invocation with all available options."
  },

  "Insert months_since invocation": {
    "prefix": "months_since",
    "body": [
      "{{{ '1959' | months_since }}"
    ],
    "description": "Insert a months_since plugin invocation. A wide variety of date formats can be used."
  },

  "Insert nth filter invocation": {
    "prefix": "nth",
    "body": [
      "{{ '1,2,3,4,5' | split: ',' | nth: 2 }}"
    ],
    "description": "Insert an nth plugin invocation."
  },

  "Insert outline invocation": {
    "prefix": "outline",
    "body": [
      "{% outline collection_name %}",
      "  0: Section Head 1",
      "  1000: Section Head 2",
      "  2000: Section Head 3",
      "{% endoutline %}"
    ],
    "description": "Insert an outline plugin invocation."
  },

  "Insert pre minimal invocation": {
    "prefix": "pre_min",
    "body": [
      "<!-- #region -->",
      "{% pre This is a headline %}",
      "$1",
      "{% endpre %}",
      "<!-- endregion -->"
    ],
    "description": "Insert a minimal pre plugin invocation with only the necessary options."
  },

  "Insert pre maximal invocation": {
    "prefix": "pre_max",
    "body": [
      "{% pre class='' clear copyButton dark shell",
      "      highlight='regex'",
      "      style=''",
      "      This is a headline %}",
      "{% noselect %}$1",
      "{% noselect $2 %}",
      "{% endpre %}"
    ],
    "description": "Insert a maximal pre plugin invocation with all available options."
  },

  "Insert HTML region": {
    "prefix": "region",
    "body": [
      "  <!-- #region -->",
      "  <h2 id='$1'>$2</h2>",
      "  <p>",
      "  </p>",
      "<!-- #region -->",
      "  {% pre shell copyButton %}",
      "  {% noselect %}",
      "  {% noselect %}",
      "  {% endpre %}",
      "<!-- endregion -->",
      "<!-- endregion -->"
    ],
    "description": "Insert an HTML region."
  },


  "Insert quote minimal invocation": {
    "prefix": "quote",
    "body": [
      "{% quote %}",
      "  $3",
      "{% endquote %}"
    ],
    "description": "Insert a minimal quote plugin invocation with only the necessary options."
  },

  "Insert quote maximal invocation": {
    "prefix": "quote_max",
    "body": [
      "{% quote break by noprep",
      "     cite='$1'",
      "     url='$2' %}",
      "  $3",
      "{% endquote %}"
    ],
    "description": "Insert a maximal quote plugin invocation with all available options."
  },

  "Insert random_hex_string invocation": {
    "prefix": "random_hex_string",
    "body": [
      "{% assign id = random_hex_string %}"
    ],
    "description": "Insert a random_hex_string plugin invocation."
  },

  "Insert run invocation": {
    "prefix": "run",
    "body": [
      "{% run echo 'asdf' %}"
    ],
    "description": "Insert a run plugin invocation."
  },

  "Insert weeks_since invocation": {
    "prefix": "weeks_since",
    "body": [
      "{{{ '1959' | weeks_since }}"
    ],
    "description": "Insert a weeks_since plugin invocation. A wide variety of date formats can be used."
  },

  "Insert years_since invocation": {
    "prefix": "years_since",
    "body": [
      "{{{ '1959' | years_since }}"
    ],
    "description": "Insert a years_since plugin invocation. A wide variety of date formats can be used."
  }
}

The above file defines the following snippets. I used my run plugin to generate the output, and it shows the bash commands it ran to produce the output, followed by the output (which is unselectable).

Shell
$ cat ~/.config/Code/User/snippets/html.json | \
  grep -v '//' | \
  jq -r 'values[].prefix' 
archive_display
basename
basename_without_extension
days_since
dirname
download_link
flexible_include_max
flexible_include
from_to_until
href
href_max
img
img_max
months_since
nth
outline
pre_min
pre_max
region
quote
quote_max
random_hex_string
run
weeks_since
years_since

But Wait, There Is More!

In addition to snippets for my Jekyll plugins, I defined a snippet, called region, for HTML regions. A region is a foldable section of HTML, set up the way I like when writing blog posts such as this. If you have a long {% pre %}{% endpre %} passage, placing it within a foldable region makes the source HTML much easier to work with. Regions within regions allows you to unfold to any degree of detail you require.

Foldable regions are provided by the regionfolder Visual Studio Code extension by maptz. The inserted nested regions look like this:

<!-- #region -->
<h2 id='$1'>$2</h2>
<p>
</p>
<!-- #region -->
{% pre shell copyButton %}
{% noselect %}
{% noselect %}
{% endpre %}
<!-- endregion -->
<!-- endregion -->

You control the visibility of nested regions with a series of two keystrokes.

  • All nested regions can be folded by pressing Ctrl-K Ctrl-0.
  • Unfolding just the first level of nested regions can be accomplished by pressing Ctrl-K Ctrl-1.
  • Unfolding to the second level of nested regions can be accomplished by pressing Ctrl-K Ctrl-2.

Videos

Here are some videos that show the Visual Studio Code snippets extension in action.