LuaSnip for Hugo Shortcodes

• Updated: March 11, 2024
• docs  
• documentation  

This setup came about because I continually forgot the mechanism Hugo utilizes for writing advanced markup to add to markdown documents, so I made my setup even lazier and wrote some snippets to help me generate even the most convoluted of shortcodes. I was already familiar with snippets for Latex, so inevitably a lot of copy-paste took place here. I’m including in this post the snippets I rely on the most.

To me configuration is a bit like a being in a jacuzzi. Sometimes, usually at the beginning, it’s relaxing and enjoyable. But eventually the chlorine seeps in, your fingers corrugate (its a real word), and your heart begins excavating through your ribcage - so while the below is useful, I wouldn’t want to set it up again, and I’m hoping that every post on this site doesn’t end up being the equivalent of flaky salt.

I know that at some point an AI will probably liberate me from configuration hell. In fact it’s probably achievable right now, but like Dobby, I guess I’m still waiting for my sock to be freed.

Here are my most common shortcodes, starting with the one I use to generate code snippets

Trigger : Keystroke or Text Used to Generate Snippet

IMPORTANT: To get this post to render the Hugo code below needed to be escaped. So if copy-pasting, remove the % % pairs within the Hugo shortcodes enclosed in double brackets.

Generate Code Snippet

Description: Wrapper for highlight.js support.

Trigger: mdcode:

1
2
3
4
5
6
7
8
9

s({trig="mdcode", dscr="markdown code syntax highlighting",
snippetType="autosnippet"},
 fmta( [[ 
{{% << highlight <>  "linenos=table" >> %}}
<>
{{% << / highlight >> %}}
 ]],
 { i(1,"c"),i(2)}),
   { delimeters= '<>'}),

Absolute Hugo Reference

Description: Point to another Hugo page.

Trigger: hgref:

1
2
3
4
5
6
7

 s({trig="hgref", dscr="hugo reference",},
 fmta( [[ 
 [<>]({{%<< ref "/<>" >>%}})
 ]],
 { i(1),i(2) }),
   {delimeters= '<>'} 
 ),

Tufte Sidenote

Description: Generate a tufte sidenote (see sidenote). This is a sidenote. Notice it's annotated to correspond to it's location in the text.

Trigger: tufteS:

1
2
3
4
5
6
7

 s({trig="tufteS", dscr="insert tufte css marginnote",},
 fmta( [[ {{%<< tufteSn for="<>" id="<>" >>*/}} 
 <> 
 {{/*<< / tufteSn >>%}} ]],
 { i(1),rep(1),i(2) }),
   {delimeters= '<>'} 
 ),

Tufte Margin Note

Description: Generate a tufte margin note.

Trigger: tufteM:

1
2
3
4
5
6
7

 s({trig="tufteM", dscr="insert tufte css marginnote",},
 fmta( [[ {{%<< tufteMargin id= "<>" >>*/}} 
 <> 
 {{/*<< / tufteMargin >>%}} ]],
 { i(1),i(2) }),
   {delimeters= '<>'} 
 ),

Make an epigraph

Description: Create a formatted epigraph.

Trigger: epg:

1
2
3
4
5
6
7
8

s({trig= "epg", dscr="tufte epigraph",
snippetType="autosnippet"},
  fmta([[
  {{%<< epigraph citation="<>">> %}}
  {{%<</ epigraph >> %}}  }}
  ]], {i(1,"todo")}),
    {delimiters="<>"}
    ),

Render Plotly

Description: Render a Plotly Diagram in a Hugo post.

Trigger: mdplot:

Here, the json parameter is a path to a subfolder in the static directory containing exported json data from a D3.js diagram. Plotly includes options for exporting plot data to json.

1
2
3
4
5
6
7

s({trig= "mdplot", dscr="render plotly diagram",
snippetType="autosnippet"},
  fmta([[
  {{%<< plotly json="<>" height="<>" >> %}}]], 
  {i(1,"/plotly/placeholder.json"), i(2,"400px")}),
    {delimiters="<>"}
    )

Math Block Environment

Description: Mathematical processing block environment using Mathjax.

Trigger: $$ e^{\pi i } = cos \theta + i sin \theta $$

1
2
3
4

s({trig = "dm", wordTrig = true, 
regTrig = false ,snippetType = "autosnippet"},
fmta([[ \[ <> \]]],
{ i(0), }))

Coming Soon…

Subscript Expansion

Generate List

Quick MD Table

I’ll likely revisit this post with updates or changes from time to time.