I use a static site generator HuGo for Talotics.com.

This is an ongoing collection of tips, to remind me of amendments I’ve made when working with HuGo.

I use the static site generator HuGo for Talotics.com.

I also use it for a few other sites and I’ve basically hacked those together.

For talotics.com I’m trying to learn how to use it ‘properly’.

Here are a few things I’ve learned (and they are basically just notes to me so that I remember)

Override Rather than Amend a Theme

To amend a theme it is better to ‘override’ the theme files using layouts folder in the root directory of your content folder. This allows you to switch between themes more easily and update themes to new versions without losing your changes.

Configure RSS Feed Limit and Full Content

Configure the RSS feed to have a limit, otherwise it grows to have all your content. Given that one of my sites has 500 posts, that is too big a feed.

• add an rssLimit variable in config.toml as described in the RSS template documentation

For Full Content Feed override the embedded rss.xml

• embedded templates are ‘built in’ so copy and paste from the web site into a file in your layouts folder
• amend the RSS template (by creating a version in your layouts folder layouts\_default\rss.xml and amend the description to use .Content rather than .Summary (this creates a full content feed rather than a summary feed where you have to click through to read the content)

<description>{{ .Content | html }}</description>

Use the html comment more to split a post

On the list pages we just want the summary, on the feed and pages we want the full content.

To achieve this use the more comment, and don’t add spaces in there ever.

<!--more-->

Make posts draft

Remember to add a space after the colon.

draft: true

Use Short Links

When sharing on social media, we could use bitly etc. but sometimes those links are not easy to type.

Create custom short links for posts by using the alias command.

Putting them in a single char directory allows you to have more categories and keep the links readable e.g. below reads as a tactic micro blogging

aliases: ["/a/tactic/micro-platform/"]

Default Variables

I have found Hugo to be hard to work with default variables between releases.

For my custom templates I tend to take the easy way out and use default values that are defined in the template itself, rather than in the Site.

Then I use the page params to override the default value.

    {{$old := "Default Description for the site" }}
    <meta name="description" content="{{default $old (.Params.description)}}"/>

NOTE: I am not sure why I experienced difficulties with this, it may have been a bug in a version of Hugo. I try to avoid this but it is worth knowing about in case this issue returns.

Meta Description

Hugo, by default in the internal templates, supports open graph description, but not the basic SEO description tag

I found the internal templates listed online

I used the internal templates to add the following to a custom baseof.html file which my template was using as its source of page headers

<meta name="description" content="{{ with .Description }}{{ . }}{{ else }}{{if .IsPage}}{{ .Summary }}{{ else }}{{ with .Site.Params.description }}{{ . }}{{ end }}{{ end }}{{ end }}">

You can find more SEO tips for Hugo here)

Create meta data for debugging

When I have struggled with some deugging, I find it useful to display variables as meta fields.

<!-- useful for debugging hugo displays -->
<meta name="X-HUGO-PAGE-KIND" content="{{.Kind}}" />
<meta name="X-HUGO-PAGE-TYPE" content="{{.Type}}" />

I never go live with this code. But if I did it wouldn’t really matter.

The benefit of using meta tags is that they are at the top of the dev tools in the browser which makes them easy to find.

404

Add a 404 redirect in .htaccess

ErrorDocument 404 /404.html

And make sure your 404 page has some content:

{{ define "header" }}{{ partial "page-header.html" . }}{{ end }}
{{ define "main" }}
    <article class="center cf pv5 measure-wide-l">
      <h1>
        This is not the page you were looking for
      </h1>
            <p>If it helps then we have a list of pages below:</p>
            <ul>
                {{ range .Data.Pages }}
                <li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
                {{ end }}
            </ul>
    </article>
{{ end }}

Image Sizes

By default images will be width of the container when using Markdown.

![](/images/tools/google-docs/sheet-contact-us/settings-cog.png)

To control the size, drop back down to HTML:

<div style="width:300px">
   <img class="html" src="/images/tools/google-docs/sheet-contact-us/settings-cog.png"/>
</div>

Alt Tags on Images

When adding images, the temptation is going to be:

![](/images/myimage.png)

But don’t do this. You’ll miss out the alt tags which are important for accessiblity and SEO

![this becomes my alt tag](/images/myimage.png)

Make sure you do a final ‘find’ for ![] to try and catch these before they go live.

Don’t try keywords stuffing, treat them as descriptions, with SEO as a knock on effect.

Open Graph Tags

See this post by Brendan Quinn on Open Graph with Hugo

ShortCodes

Short codes are an incredibly powerful way of extending markdown and keeping your code maintainable and consistent across the site.

See Create your own short codes

Previously I would embed html into the markdown:

<p class="text-center">
 <a class="btn btn-lg btn-success" style="margin-bottom:4px;white-space: normal;"
    href="/files/trifoldAgilePrintYourOwn.pdf">
       Download "The Evil Tester's Guide to Agile Testing PDF"
 </a>
</p>

Now I use a shortcode:

{ {< button colour="btn-success" margin="10" href="/files/trifoldAgilePrintYourOwn.pdf" >}}
    Download "The Evil Tester's Guide to Agile Testing PDF"
{ {</button>}}

This is just an html file in \layouts\shortcodes and the file is called button.html

<p class="text-center">
    <a class="btn btn-lg {{ .Get "colour" | default "btn-success"}}"
       style="margin:{{ .Get "margin" | default "4"}}px;white-space: normal;"
       {{ with .Get "href" }}href="{{.}}"{{ end }}
        >
        {{ .Inner }}
    </a>
</p>

I build this by:

• create the HTML code I want
• create the button.html file
• copy the HTML into the file
• write the { {<button>}} code in the markdown
• ensure that the default button works
• incrementally replace the HTML with the macros to paramaterise it
• then use button throughout my markdown

This makes the code so much more readable and maintainable.

To allow me to have ‘quick hacks’ I have a rawhtml shortcode:

{{ .Inner | safeHTML }}

This allows me to ‘wrap’ markdown with html without the html interfering with the markdown processing

    

        

            

            
            
            



Some markdown text

- possibly a list
- of items


            
        
    

This is temporary until I generalise to a proper shortcut, but allows me to experiment with layout while still using markdown.