Personal blogging with HUGO

Synopsis

Here I provide an example of static website creation using the HUGO generator hosted with Github Pages, which is expected to be widely useful for professional purposes. Moreover, the general procedures and tips here should be hopefully useful for amateur HUGO users like me.

This work is licensed under CC BY-SA 4.0

Github Pages repository

1. Create a new Github repository named <user>.github.io where <user> is your Github username. By default, website https://<user>.github.io will load the index.html in the root of this repository. Even if this repository has private visibility, contents in this repository will still be publicly accessible via HTTP once your site is deployed.
2. By default, once you push to this repo, Github Pages will be automatically set up and your site will be deployed.

HUGO with the PaperMod theme

1. Install HUGO following the official Installation guide. With this tutorial you do not need to install the GO interpreter. However, git is required for installation and upgrade of HUGO themes.
2. Once hugo is in your search path, create a new website directory under the working directory with hugo new site <site_dir> --format yaml. Your website contents will be stored in <site_dir>.
3. Change directory to <site_dir> and then run the following commands to install the PaperMod theme: git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1.
4. By default, hugo.yaml is used as the single site generation configuration file. Refer to the PaperMod demo site configuration file and the PaperMod documentation for configuration details.
5. To create a new post, use hugo new content post/<post_name>.md. This will create a new markdown file for your new post at content/post/<post_name>.md. If you have a customized template at archetypes/post.md, the new file will be filled accordingly (more detail below).
6. Personal preferences and tips are included in the next section below.

Optional functionalities

Here I include personal notes on functionalities used in my site.

Chroma-based syntax highlighting

HUGO provides Chroma as the default code highlighter, which performs server-side syntax highlighting of code fences and/or inlines. Once your website is built with hugo or tested with hugo serve, code styling is hardcoded in the HTML+CSS of your site.

Apart from Chroma, the PaperMod theme provides an alternative client-side highlighter Highlight.js. Follow the steps below to set-up Chroma highlighting properly. Refer to the PaperMod documentation for more information.

1. Edit the configuration file hugo.yaml to disable Highlight.js and configure Chroma behavior. Refer to the HUGO highlighting documentation for details.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

params:
	assets:
		disableHLJS: true # Disable Highlight.js

markup:
	highlight:
		noClasses: true # use classes for CSS styling instead of inlines
		style: monokai # highlight style
		codeFences: true # highlight code fences
		lineNos: true # show line numbers
		lineNoStart: 1 # default line number start
		guessSyntax: true # guess syntax if possible

2. Refer to the style gallery to choose your preferred style. Once the style is specified in the configuration file, generate the CSS class file. Create directories as needed.

1

hugo gen chromastyles --style=monokai > assets/css/extended/monokai.css

3. With this syntax highlighting should be enabled for code fences. You may explicitly specify syntax right after the starting triple backticks.

1
2
3

```bash
echo "Hi!"
```

4. Highlighting of inline code spans requires explicit usage of the built-in highlight shortcode. Refer to the HUGO forum post for details.
5. To configure rendering of tabs in your code, put the following CSS code in your static files (e.g., creating a new CSS assets/css/extended/tabwidth.css):

1
2
3

pre.chroma {
  -moz-tab-size:2;-o-tab-size:2;tab-size:2;
}

6. Some of the highlight settings can be set per code block, see an example below. Refer to the HUGO docs for more details. See an example below:

1
2
3
4
5
6
7

```r {linenostart=101}
# This:
library(readr)
df <- read_csv("test.csv")
# do something
# do something
```

101
102
103
104
105

# Renders to:
library(readr)
df <- read_csv("test.csv")
# do something
# do something

Client-side math typesetting with KaTeX

At this point, the easiest way for math typesetting is client-side rendering using either KaTeX or MathJax. For KaTeX-based typesetting see below or the PaperMod docs. The key point here is that we would like to load the KaTeX (with auto-render extension) only when required.

1. Create a partial template in layouts/partials/helpers/katex.html. You may want to check KaTeX Auto-render extension page for version updates. You may also host the files in your Github Pages repository. Create directories as needed.

1
2
3
4

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>

2. If in-line equations are desired, add an additional script element to the partial created above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<script>
	document.addEventListener("DOMContentLoaded", function() {
		renderMathInElement(document.body, {
			delimiters: [
				{left: "$$", right: "$$", display: true},
				{left: "$", right: "$", display: false}
			]
		});
	});
</script>

3. To load the KaTeX template in headers, add the following to layouts/partials/extend_head.html. Create the file if needed.

1
2
3

{{ if or .Params.math .Site.Params.math }}
{{ partial "helpers/katex.html" . }}
{{ end }}

4. To enable math rendering in a page, add parameter math: true to the front matter of the content file. To enable math rendering globally, add parameter math: true to the configuration file.
5. Some examples below.

Inline math example (use single dollar sign $): $log(\frac{I_0}{I})=A=\varepsilon l c$

Block math example (use double dollar sign $$): $$ \rho (x, t) = \frac{N}{\sqrt{4 \pi D t}}e^{-\frac{x^2}{4Dt}} $$

Content template

HUGO archetypes are templates used for new content. Because posts are the typical content I put on my website, I created a post template at archetypes/post.md. When new content is created with hugo new content post/.../new_post.md, the template is evaluated for the new content.

For an example template, refer to the PaperMod docs.

Images

HUGO provides the following methods for working with images in a post.

1. Markdown image which is part of the markdown standard implementation.
2. HUGO built-in shortcode figure which is a wrapper of HTML figure tag.

An example for markdown image:

1

![alt_text](/full/path/to/image.png "optional title")

An example for the figure shortcode:

1

{{< figure src="/full/path/to/image.png" title="optional title" caption="optional caption" >}}

Note on resources path

One straightforward way for specifying path to the image is the absolute path (root being thecontent folder of the HUGO project). Alternatively, you can use relative path directly if page bundle organization is used.