Hugo Hints and Tips on Much Ado About IT

Embed a diagram in a Hugo page

Julian Knight — Fri, 14 Dec 2018 12:56:01 +0000

It is great to be able to define a diagram in code directly in your web pages. This article shows you one way to achieve that using Gravizo.

Summary

We want to be able to generate neat diagrams for our website. This can, of course, be done offline using Microsoft Visio or some other diagramming tool. There are online ones too. But sometimes, we want to be able to generate a diagram using code or we just need something quick and simple. That is where tools such as GraphViz or PlantUML come in handy.

But currently, there are no direct addin’s for Hugo to achieve this.

We can, however, use an external tool to create the diagram dynamically from code embedded in the page. There are several tools that we could use, I will update this page as and when I try those tools.

MermaidJS

MermaidJS is a JavaScript library that you can easily embed on your page. It is widely used and well supported.

Mermaid supports several types of diagram including: Sequence, Flowchart, Gantt (timeline), Class (beta), Git graph (beta).

MermaidJS is available for installation on your own configuration using Node.JS or you can use the UnPkg CDN.

Gravizo

We can use Gravizo to embed diagrams of various kinds in a web site.

Gravizo has a number of ways to embed or access the source and supports GraphViz (DOT language), PlantUML and UMLGraph (though there are some limitations on the latter).

Graviso will produce the following types of diagram: Graph (DOT), UML Sequence, UML State, UML Class, Activity, SVG custom.

You can output the diagram as SVG or PNG graphics by changing the URL.

Note that you are using a 3rd party website if you use these methods. As always, I recommend turning off 3rd-party cookie support in your browser to help prevent any tracking. The advantage however, is that you don’t need any JavaScript on your page.

Using a Hugo custom shortcode

shortcodes/gravizo.html

{{ $title := "Diagram" }}
{{ if .IsNamedParams }}
 {{ with .Get "title" }}
 {{ $title = . }}
 {{ end }}
{{ else }}
 {{ with .Get 0 }}
 {{ $title = . }}
 {{ end }}
{{ end }}

<figure>
 <img
 src='https://g.gravizo.com/svg?{{ .Inner }}'
 alt='{{ $title }}'
 />
 <figcaption>{{ $title }}</figcaption>
</figure>

To use:

{ {< gravizo "DOT Language (GraphViz) Example" >}}
 digraph G {
 aize ="4,4";
 main [shape=box];
 main -> parse [weight=8];
 parse -> execute;
 main -> init [style=dotted];
 main -> cleanup;
 execute -> { make_string; printf}
 init -> make_string;
 edge [color=red];
 main -> printf [style=bold,label="100 times"];
 make_string [label="make a string"];
 node [shape=box,style=filled,color=".7 .3 1.0"];
 execute -> compare;
 }
{ {< /gravizo >}}

DOT Language (GraphViz) Example

PlantUML Example

Note that the UMLGraph example below from the Gravizo website doesn’t work in this context - it is unclear why but I expect it to be something to do with an invalid HTML entity.

UMLGraph Example

Inline Markdown code

An alternative to needing a shortcode is to embed the source directly into the page.

Note that this method does not allow blank lines so the source is hard to read. This is because Markdown uses a blank line as a paragraph separator.

![Alt text](https://g.gravizo.com/svg? @startuml; actor User; participant “First Class” as A; participant “Second Class” as B; participant “Last Class” as C; User -> A: DoWork; activate A; A -> B: Create Request; activate B; B -> C: DoWork; activate C; C –> B: WorkDone; destroy C; B –> A: Request Created; deactivate B; A –> User: Done; deactivate A; @enduml )

![Alt text](https://g.gravizo.com/svg?
@startuml;
actor User;
participant "First Class" as A;
participant "Second Class" as B;
participant "Last Class" as C;
User -> A: DoWork;
activate A;
A -> B: Create Request;
activate B;
B -> C: DoWork;
activate C;
C --> B: WorkDone;
destroy C;
B --> A: Request Created;
deactivate B;
A --> User: Done;
deactivate A;
@enduml
)

This method does allow the UMLGraph example to work as long as you remove the blank lines:

![Alt text](https://g.gravizo.com/svg? /** *Structural Things *@opt commentname *@note Notes can *be extended to span multiple lines / class Structural{} / *@opt all @note Class / class Counter extends Structural { static public int counter; public int getCounter%28%29; } / *@opt shape activeclass *@opt all *@note Active Class */ class RunningCounter extends Counter{} )

![Alt text](https://g.gravizo.com/svg?
 /**
 *Structural Things
 *@opt commentname
 *@note Notes can
 *be extended to
 *span multiple lines
 */
 class Structural{}
 /**
 *@opt all
 *@note Class
 */
 class Counter extends Structural {
 static public int counter;
 public int getCounter%28%29;
 }
 /**
 *@opt shape activeclass
 *@opt all
 *@note Active Class
 */
 class RunningCounter extends Counter{}
)

Automatically updating Hugo

Julian Knight — Tue, 29 May 2018 21:28:30 +0000

Hugo is still changing very quickly. So it is helpful to be able to easily download and install the latest version directly from GitHub.

Summary

The tricks are firstly to use GitHub’s latest link for software releases and download the webpage. Secondly, to find the link to the actual software download in the content of the page. Once you have this, you can download the latest built version file automatically, unpack it over the top of the existing files and then delete the downloaded file.

NOTE: For hopefully obvious reasons, the Hugo server cannot be running when you run this.

Many thanks to @pgr on the Hugo Discourse for the original idea.

Using PowerShell on Windows 10

# get-hugo.ps1
# Get the latest copy of Hugo for Windows (64bit) from GitHub and install it

# -- CHANGE THESE IF NEEDED -- #

# The folder containing the Hugo `bin` subfolder
$hugoRoot = "c:\Hugo"
# A regular expression to find the right platform link name
$hugoPlatform = "Windows\-64bit\.zip"
# Location of the Hugo executable (relative to $hugoRoot or use absolute path)
$hugoBin = "bin"

# ---------------------------- #

# ================================================== #
# -- Shouldn't need to change anything below here -- #
# ================================================== #

Set-LocationEx -Path $hugoRoot # AKA `cd ...`
# Make TLS 1.2 the primary version otherwise get from most sites will fail
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11, tls"
# Get the GitHub page containing the latest version of Hugo
$latest = Invoke-WebRequest -Uri https://github.com/gohugoio/hugo/releases/latest
# Find the file details for the Windows 64bit version
$file = $latest.ParsedHtml.links | Where-Object{$_.nameProp -match $hugoPlatform} | select pathname, nameProp
# Download the actual file
Invoke-WebRequest -Uri ("https://github.com/" + $file.pathname) -OutFile $file.nameProp
# Unpack the zip file into the `bin` folder - NOTE: This requires PowerShell v5 or above (Windows 10 1709)
Microsoft.PowerShell.Archive\Expand-Archive -Path $file.nameProp -DestinationPath $hugoBin -Force
# Delete the zip file
Remove-Item $file.nameProp

#EOF

Hugo Cloud Deployment with Netlify

Julian Knight — Tue, 10 Apr 2018 22:00:00 +0000

Netlify is a great cloud-based hosting and CDN service. It has great support for Hugo and other static site builders and is easily integrated into cloud-based GIT services. This makes deployment and updates a snap. \ \ On this page, we list a few snippets of information that help us remember how to do things.

Netlify Website

Netlify Dashboard

GitLab TotallyInformation Dashboard

Forestry.IO Dashboard

My new site creation workflow

Create a new private repository on GitLab - this will host the source for the site which we keep private.
Clone the new repo to your development device.
Use the clone folder to create a new site.
Clone a suitable Hugo theme as a GIT submodule to the themes folder.
Make any changes or add content as required.
Commit changes for the site repo and sync back to GitLab.
Create a new site in Netlify that uses the GitLab repo.
Configure Netlify as required.
Updates to GitLab will now automatically rebuild and deploy the site.

If I want to have an online editor, I will also link up Forestry.IO.

My site update workflow

Make updates to the site.
Commit changes for the site repo and sync back to GitLab.
Netlify automatically rebuilds and deploys the site.

Test/Preview and other temporary deploys

To test or preview a site change without disturbing live, all that is needed is either:

Create a Pull Request (AKA a Merge Request) in GitLab. Typically, this comes from someone outside your repo/organisation.
Create a GIT branch. This can happen on the development device or in GitLab.

Each PR/branch is given its own URL.

Configuration of PR/branch versions is done via the netlify.toml file in your site repo.

Netlify Hints & Tips

Netlify provides a number of environment variables. They are described in the docs here.

It is easiest to configure Netlify using the netlify.toml file you include in the root of your site repository. Details on what goes in there are in the docs here.

Netlify provides a Forms capability. I use this to provide a contact form on this site. Data is fed back into the dashboard but you can also use Netlify’s webhooks to provide alerting for new form submissions. I have this wired up to alerts via my Slack org.

In addition to the netlify.toml control file that you put in your site root, Netlify provides two additional files _redirects and _headers. Their use is pretty obvious but worth noting that you can test those files using Netlify’s online test pages: Test _redirects, Test _headers. Simply paste the content of the files into the test pages.

Redirects

It isn’t clear in the documentation but the _redirects file has to be in your static delivery folder, /static by default for Hugo. The file is not actually made accessible from the web. However, be careful if you ever move to alternative deployments since the file WILL then be available via the web.

Alternatively, use the redirects test page to convert to TOML format and include that in your /netlify.toml file.

Hugo Snippets and Code Examples

Julian Knight — Sun, 08 Apr 2018 11:00:00 +0000

A somewhat random collection of code for Hugo so that I don't have to keep looking things up all over the Internet.

Index

Markdown oddities and extensions in Hugo
Shortcode to render a code example in a page/post
List the sub-sections of a section
Reset a Scratch variable to an empty array (slice)

Markdown oddities and extensions in Hugo

Hugo uses the Blackfriday markdown engine.

Some differences that you might want to be aware of:

GitHub Flavoured Most of the GitHub style markdown features are available. The default settings are a little more strict however (e.g. blank lines between heading and paragraph are required).
Nested Lists THere is a subtle bug in Blackfriday that it uses a logical tab spacing of 4 rather than the more normal (form markdown) 2. This means that nested content in a list has to be 1 tab or 4 spaces in, not 2 spaces which is the default for most versions of markdown libraries.
Alternative Rendering Engine It is possible to use the Mmark engine instead of Blackfriday. Put markup: mmark in a page frontmatter or name files *.mmark.

Header IDs Are enabled by default so each header gets an id. e.g.

<h3 id="shortcode-to-render-a-code-example-in-a-page-post">Shortcode to render a code example in a page/post</h3>

Dashes By default, Latex style smart dashes are used. -- is an – – and --- is an — —. In addition, a single dash between words is translated to an – e.g. 12 June - 3 July becomes 12 June – 3 July
Syntax Highlighting triple backticks are used to wrap code blocks. Chroma is used for the highlighting.
Alternatively, the older Pygments engine can be used.
Use the {{ < highlight >}} markup form if you want to use extended controls such as line numbers, line highlights, etc.
Configuration is done in config.toml, see the content-management/syntax-highlighting section of the docs for details.

The list of Highlight languages is given in the docs.

Definition Lists Are easily marked up as:

Cat
: Fluffy animal everyone likes

Internet
: Vector of transmission for pictures of cats \
Don't forget the blank line between the terms
: You can use multiple definition lines

Tables

Name | Age
------|------
Bob | 27
Alice | 23

Footnotes

This is a footnote.[^1]

[^1]: the footnote text.

Strikethrough Uses 2 tildes ~~.
Trailing backslash Inserts a line break.

Many of these are optional, see the content-management/formats section of the Hugo docs for details.

Shortcode to render a code example in a page/post

layouts/shortcodes/render-code.html

{{ $file := .Get "file" | readFile }}
{{ $lang := .Get "language" }}
{{ (print "```" $lang "\n" $file "\n```") | markdownify }}

And in a post/page:

{{ % code file="/static/some-script.js" language="js" %}}

List the sub-sections of a section

I use this on my main blog site to list out the knowledgebase sections.

{{ range (where .Site.Pages "Section" "kb") }}
<ul>
 {{ range .Sections }}
 <li><a href="{{ .Permalink}}"> {{ .LinkTitle }} </a></li>
 {{end}}
</ul>
{{ end }}

Reset a Scratch variable to an empty array (slice)

{{- $.Scratch.Set "myvar" slice -}}

Hugo Benefits and Issues

Julian Knight — Sat, 07 Apr 2018 22:00:00 +0000

A discussion of Hugo vs Jekyll and WordPress.

Benefits of Hugo over Jekyll

Simple binary install for local builds.
Far easier to build a site, even from a blank theme.
Shortcodes - gist, ref and relref, speakerdeck, tweet, vimeo, youtube. Plus the ability to create your own very easily.

Examples: spf13, Hugo Docs.
No need to faff with escaped Liquid tags - makes embedded code examples a LOT simpler.
Seems to have far more logical and useful variables such as the .Parent, etc for shortcodes.
Migration of old sites is made much easier due to aliases and url frontmatter fields.
Use archetypes to template creation of new pages/posts/etc
Aliases - Why don’t other site generators use this!! Great for migrating sites. You can supply any number of aliases and Hugo will generate a redirect page automatically - no more 404 errors when migrating.
Wordpress migration - it actually works. Not only that but it creates sensible url and date metadata. The Jekyll equivalent never worked for me.

Disbenefits of Hugo over Jekyll

Cannot use variables in page/post content. Have to use a shortcode.

Converting from Jekyll

Change all instances of updated in frontmatter to lastMod

Converting from Wordpress

Some posts didn’t get a title frontmatter. They were all draft articles.
Some posts didn’t get a proper date (1970-01-01)
The excerpt field used in WordPress was not converted. It still appeared in the frontmatter. I manually (well vscode file search/replace) converted these to descriptions.
Link tags came across as HTML rather than markdown. Not too big an issue except many didn’t have nofollow on them. Probably that’s carried from the original though.
Code sections came across wrapped in HTML <code></code> tags instead of GitHub markdown codefenses or Hugo’s highlight tag.
Pages need tweaking, especially to reproduce the same custom navigation menu.
No dynamic data (Pods, WP-Pipes, Express Curate, Feedburner redirect, Twitter mentions as comments) - have to do this some other way or not at all.
No automation: tag/category lookups/suggestions, no auto-dates, no auto-SEO, no auto-share
No search
No PODs (Custom data & forms) - have to export to JSON, add the json to the data folder, create a shortcode to display.
Export from WP created a frontmatter var of dsq_thread_id as a list, this needs changing to disqus_identifier and making text in order for it to be used by the internal Disqus template.
My export had some leftover frontmatter URL’s in the form blogger_permalink from when I merged to Blogger blogs. I renamed these as aliases.
Draft posts came across with 1970 dates and URLs in the format ``, I removed all of the URL’s for these.

General “Gotcha’s”

When using a partial, make sure to pass “.” as a parameter othwise the partial does not get any context variables.

e.g. {{ partial "partialname.html" . }}
When using hugo server, pages and other resources that are moved or deleted MAY not be released by the live reloader. May need to stop/restart the server for them to actually disappear.
Site and page variables are defined without leading caps. But they are used with leading caps.
lastMod in a page frontmatter is actually used as .Page.Lastmod - note the change of case!

Honestly, this kind of thing really puts people off.