About

This site consists of a collection of Markdown files and images, which are converted to a website using Hugo. This site also uses the Hextra theme to extend hugo’s functionality, and provide an appealing layout and color scheme.

Installation & Setup

This is a record of the initial setup and configuration.

This section is mostly a record of what I did for “future me”. If you want to build a site like this, and don’t know where to start, email me and I’d be happy to provide more details.

Step 1: Installation

I followed the Getting-Started Guide. Hugo was installed and setup first, then the theme was installed as a git sub-module.

Step 2: Customize CSS

I wanted to tweak the CSS for table formatting. To customize CSS, add a file /assets/css/custom.css.

table {
  margin: 0 auto;
  border-collapse: collapse;
  width: 100%;
}

th {
  background-color: #EBF8FA;
  color: black;
}

Step 3: Configure HTML passthrough

Markdown has terrible image support, so I find that I often need to use HTML img tags to describe images (with width, floating, margins etc). Most SSGs that I’ve used will “ignore” HTML tags so that they just get emitted to the output HTML and will work. However, the renderer that Hugo uses will NOT pass through HTML directly to the emitted HTML, so you need to set a flag to tell the renderer that it’s ok to do so. Do this, and you can then use img tags with all of the options.

Update the hugo.yaml file to include:

markup:
  goldmark:
    renderer:
      unsafe: true

Creating Content

Markdown isn’t a complete specification, so there are sometimes hacks or workarounds needed to display content appropriately.

Shortcodes

For custom content, Hugo uses shortcodes, basically macros that you can reference in your content. Hextra adds some extra shortcodes.

Hugo Shortcodes are always available from the base system. e.g., figure, YouTube, Ref.
Hextra Shortcodes are additions included in the theme e.g., icon, callout, steps.

Heroicons

Heroicons are available through the icon shortcode and can be included directly in content.

For example, this code

is replaced by

Heroicons are also used anywhere you see an icon e.g., the GitLab icon beside the searchbar.

Manipulating Images

Markdown image notation will display images at full-size, centred. This isn’t always what you want.

Because we configured the renderer to pass-through HTML unmodified, we can also use raw HTML which is more flexible. e.g., here’s a scaled image.

<img src="hello-kotlin-button1.gif" width="700" />

You can also add captions this way, which Markdown doesn’t otherwise support.

<figure>
    <img src="https://imgs.xkcd.com/comics/dependency.png"
         alt="XKCD Dependency" width="400">
    <figcaption><a href="https://xkcd.com/2347">https://xkcd.com/2347</a></figcaption>
</figure>

Referencing Contents

To reference other pages, use a link relative to the content location under content directory.

[Schedule](/lectures/schedule)

I strongly recommend using VS Code for editing markdown. It has one “killer-feature”: it will fill-in filenames for you when you create links like the one above.

By itself that’s somewhat useful. What makes it invaluable is that most of the time, you need to enter a URL to a file relative to the root of the website. This is difficult to figure out if all you have is a bunch of nested directories.

However, if you open the project by typing in code content/ (i.e. editing the content folder in VS Code), then the file paths that it fills in for you will be the correct relative paths.

Gotchas

Things that look like bugs.

Each page needs a folder

Best-practice is to create a folder with the name of the page, and then put the page contents in a file named _index.md. Assets also go in the folder. Failing to do this means that sometimes images won’t load properly. This seems a reasonable workaround.

e.g. this page

.
├── _index.md
├── about
│   └── _index.md

Be careful when renaming

Hugo will cache old content aggresively. If you have a link to a page that works, and you change the folder (i.e. the relative URL to that page) so that the link is invalid, Hugo will serve up the content that used to live at that link! Check your links carefully when renaming anything.

Yes there are linters for Markdown e.g., Markdownlint but none that I’ve found that work with Hugo shortcodes and other niceties (which I use heavily).