About

The instructor

This website is authored and maintained by Jeff Avery.

Other links

• My home page: more about me and my interests.
• Personal GitLab projects: smaller projects that haven’t graduated to the course GitLab.

This site

This site consists of markdown files and related assets, which are converted to a static site using Hugo. The theme is Hextra, which provides the look-and-feel of the site, and extends Hugo’s functionality.

Quick reference

• Hugo shortcodes
• Hextra shortcodes
• Heroicons

Installation & Setup

Here’s a record of what I had to do to setup and configure this site ¹.

Step 1: Installation

I recommend just following the Getting-Started Guide. Install Hugo first, then the theme.

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

Authoring Content

Markdown isn’t a complete specification, so there’s 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. Both Hugo and Hextra include shortcodes.

• Hugo Shortcodes are always available from the base system. e.g., figure, YouTube, Ref.
• Hextra Shortcodes are additions based on the theme e.g., icon, callout, steps.
• Heroicons are available through the icon shortcode.

Manipulating Images

Markdown image notation will display images at full-size, centred. If you want them aligned differently, or resized, use raw HTML. e.g.

<img src="hello-kotlin-button1.gif" alt="Hello Kotlin Button 1" width="700" />

You can also add captions this way (and even embed links in them).

<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. e.g.,

[Schedule](/lectures/schedule) 

Gotchas

Things that look like bugs.

You really need a folder for each page.

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