Beautiful Hugo Improvements

Fixed issue #142

Two weeks ago, Google Webmasters complained about the broken urls in this blog’s Tags page. This was reported by Joakim Vivas as issue #142 half a year ago. Pascal had submitted pull request #165 to fix this. However, he self-closed his PR.

Since the last commit by Michael Romero, Beautiful Hugo’s owner, was five months ago, it seems that he has abandonned his project. Therefore, I used Kaushal Modi’s solution to fix this at commit ff536782.

Upgraded to Font Awesome 5.3.1

Icons are good for illustrations since one remembers pictures much better than text. However, the later is quicker to type, but harder to read. If all text are replaced with icons (say “GitHub” → ), then I won’t be able to search for a certain word in web browsers, and I will have to grep source file(s) for a word—that’s inconvenient.

I’ve choosing the CSS version despite reduced functionalities to minimize the amount of coding.

1. Link to a newer CSS version, see commit c8dac925. (I chose all.js and downloaded a local copy.)
2. Run Esteban De La Fuente Rubio’s update script with flags -e md and -e html.
3. Some icons were still broken. I applied commit eb94ada4 to fix this.

Most of the icons are brand type, with a few exceptions, such as and .

Custom CSS

Googling on this, I found Kevin A. Smith’s introduction to Hugo’s Academic theme. He suggested adding the file name custom_css = ["custom.css"] to config.toml. I tried this but it didn’t work.

In another web page on Hugo’s forum about the same topic, Digital Craftsman suggested using the whole relative path css/custom.css. I tried this at commit f3380a0c and this worked.

Looking back, the reason that adding only the file name didn’t work for me for the first time is the missing folder /css preceeding the filename. Compare George Cushen’s working example

87
88
89

  {{ range .Site.Params.custom_css }}
  <link rel="stylesheet" href="{{ "/css/" | relURL }}{{ . }}">
  {{ end }}

with mine.

1
2
3

{{ range .Site.Params.custom_css -}}
    <link rel="stylesheet" href="{{ . | absURL }}">
{{- end }}

Chroma syntax highlighting

Syntax highlighting on Octopress used to be a headache before my migration to Hugo. The gems for line numbers didn’t work well:

1. no support for custom line number start
2. broken line number highlighting

Even though I can’t observe the visual effect of the second feature under Beautiful Hugo theme, I’m satisfied with the first one.

Apart from the customizable starting line number in code blocks, Chroma, as a Pygment port to Go, loads much quicker than Pygment.

Convenient inline $\KaTeX$ wrapping

I’ve chosen Beatiful Hugo as the theme for this blog because it comes with $\KaTeX$, which loads math much quicker than MathJax.

In Beatiful Hugo’s math sample page, all math expressions are in block style. $\KaTeX$’s default syntax \(...\) for wrapping math was too inconvenient to use, when compared to MathJax’s $...$. To enable this for $\KaTeX$, I uesd Vincent Pace’s script at commit 79cb0ba0.

12
13
14
15
16
17
18
19
20
21
22
23
24

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