About This Site

This website is generated from Markdown files by Hugo, a static site generator.

The theme is Hextra, which provides the look-and-feel, and a lot of additional functionality. I’ve sampled a lot of Hugo themes for course websites, and this has proven to be one of the best!

• Hextra Documentation
• Hugo Documentation

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. No issues.

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

Writing Content

Things to keep in mind when writing content. Markdown isn’t a complete specification, so there’s sometimes hacks or workarounds needed to display content appropriately.

• Markdown Hacks
• Heroicons

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 align="left" width="300" src="https://upload.wikimedia.org/wikipedia/commons/a/af/Logo_of_Hugo_the_static_website_generator.svg"><br><br><br><br>

Note that this will be a floating image, which is why you need a ton of
afterwards to realign content.

Referencing Contents

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

[Schedule](/docs/syllabus/schedule/)