Tips For Writing Hugo Blog Posts

I often find myself referring to past blog posts to find the syntax for these specific tips. Instead of continuing to hunt through my posts, I figured I could write a single blog post with all the little things I often have to lookup.

Hugo has a wonderful thing “short codes”, which are small snippets of code to help you format your blog posts. Your theme should have come with some, generally you can find these in themes/[theme-name]/layouts/shortcodes, which is the same directory you can use to write your own.

For example, I use the uBlogger theme and the author uPagge has done a fantastic job writing some short codes, with my favorite being admonition.

This short code allows you to bring some beautiful attention to some specific test, specifically supporting these types:

Example Note
I’m a note!
Example Abstract
I’m an abstract!
Example Info
I’m an info!
Example Tip
I’m a tip!
Example Success
I’m a success!
Example Question
I’m a question!
Example Warning
I’m a warning!
Example Failure
I’m a failure!
Example Danger
I’m a danger!
Example Bug
I’m a bug!
Example Example
I’m an example!
Example Quote
I’m a quote!

This look great and are easy to use by simply writing the following in one’s markdown blog post content:

1
2
3
{{< admonition type=note title="Example Note" >}}
I'm a note!
{{< /admonition >}}

I was able to write this short code, without it rendering by adding a /* after the initial {{ and a */ after the closing }}. I learned this from this wonderful blog post.

Perhaps you’re working on a new segment to a post, but you don’t want that particular piece to be rendered yet. We’ll once again leverage shortcodes to achieve this. Simply make a shortcode with the following content, I named it comment.html

1
{{ if .Inner }}{{ end }}

Now all you have to do is wrap your content you don’t want to render with that shortcode. For example:

1
2
3
4
5
6
7
I want this to render

{{< comment >}}
I don't want this to render
{{< /comment >}}

I want this to render

This can be achieved with a default Hugo Short code, described here.

Which is done by the following content:

1
{{< youtube w7Ft2ymGmfc >}}

An abbreviated look at my blog’s repository’s directory structure is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
GregHilston
├── README.md
├── greghilston
│   ├── Makefile
│   ├── content
│   │   ├── post/
│   │   └── project/
│   ├── static
│   │   ├── Greg_Hilston_Resume.pdf
│   │   ├── post/
│   └── themes
│       └── uBlogger

For every post in Greghilston/greghilston/content/post that has an image to be displayed, outside of the featured cover image at the top, there is a corresponding directory in GregHilston/greghilston/static/post. Once the file is in this directory, the post’s index.md can reference the image simply by writing:

scouty.jpg

![](file-name.png

How To Link To Another Post

To link to another blog post simply write

1
[text you want to display for the link]({{< ref "post/name-of-post" >}}).

here’s an example by linking to my post on how to make a Franken Quest 2.

Tip
Make sure the post you’re linking to is not a draft, otherwise the post will not be found!