This file documents exactly how I made the repository/website that is the purpose of this repository/project.

For the impatient if you already know how this works (yes, I am talking to future-me here), you can just edit the following and execute it. You should end up with a new GitHub Project/repository for static website and a development environment that is configured with software to develop a website for root of the domain specified.

This assumes you have:

• a github.com account and your shell’s ssh-agent has the private key for the public key that you will use to access that account
• the github cli installed and configured (i.e. such that gh auth status gives a useful response)

Create the Repository

1
2
3
4
5
6
7
8

export DEST_DOMAIN=<YOUR_DOMAIN_HERE>
brew install hugo
cd ${DEST_DOMAIN}

gh repo create ${DEST_DOMAIN} \
  --public \
  --template imfing/hextra-starter-template \
  --description "Sources for ${DEST_DOMAIN}"

Create the website

There are several options to create basic scaffolding for a Hugo website, such as cloning or otherwise copy from a Hugo Theme repository, such as the template repository of the Hextra Theme or using the Hugo CLI.

Hugo CLI

1
2
3

hugo new site SITENAME --format=yaml
cd SITENAME
hugo mod init github.com/USERNAME/SITENAME

Add a theme

• For Beautiful Hugo: use halogenica/beautifulhugo as the repository
• For Hextra: use imfing/hextra as the repository

hugo mod get github.com/imfing/hextra

1
2
3

module:
  imports:
    - path: github.com/imfing/hextra

Customize the Hextra theme

Hextra offers some configurability; this subsection shows a few ways in which I have used the Hextra theme’s customization functionality to change the appearance¹ of the site.

• Fetch a new web font² with some custom HTML in layouts/_partials/custom/head-end.html:

  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Vollkorn:ital,wght@0,400..900;1,400..900&display=swap" rel="stylesheet">

• Use it (everywhere) with some custom CSS in resources/assets/css/custom.css:

  :root {
    font-family: Vollkorn, "LinuxLibertine O", "Hoefler Text", Georgia, Times, serif;
    font-optical-sizing: auto;
    font-weight: 400;
    font-style: normal;
  }

Writing New Posts

To create a new blog post:

1. Create a new file in the blog directory
2. Name it using the format: YYYY-MM-DD-title.md
3. Add front matter at the top:

---
# type:
title: "Your Post Title"
date: YYYY-MM-DD
type: blog
draft: false
---

Writing Pages

For non-blog content, create a new file in the articles directory:

---
title: "About"
date: YYYY-MM-DD
modified:
type: docs
# prev:
# next:
sidebar:
  open: true
---

Markdown Tips

This site supports CommonMark as a “standard” Markdown:

• Bold text uses **doubled asterisks**
• Italic text uses *single asterisks*
• Links use [text](url)
• Images use ![alt text](image-url)
• See some markdown docs for more help
• Footnotes

  Here is some text with a footnote.[^1]
  
  [^1]: And here's the footnote text.

Deeper details

By default, and for this site, Hugo uses Goldmark to render Markdown. This means:

• I can use anything in the CommonMark Spec.
• Various built-in extensions are available by default. As you can see across this site, I use the extensions ‘Definition Lists’ and ‘Footnotes’ extensively.
• Various optional extensions can easily be made available.

Hugo Tips

• Learn more about draft, future, and expired content

Build/Serve locally

hugo server --buildDrafts --disableFastRender --bind 0.0.0.0 --port 8088

Publish/Deploy

Given that Hugo is a Static Site Generator, it outputs plain text files (HTML, CSS, JavaScript) that can be served by any webserver. So there are many simple publishing/deployment options.

• GitLab Pages
• GitHub Pages
• Cloudflare Pages
• or your own tiny server such as a Raspberry Pi, smartphone or other low power computing device.

Currently, this site uses GitHub Actions and GitHub Pages:

• GitHub Actions Workflows

Next: Wouldn’t it be nice if …?

• Additional Goldmark extensions
  • https://github.com/abhinav/goldmark-frontmatter
  • diagrams (via D2 or Mermaid)
  • Table of Contents
• Web Analytics via Plausible Analytics, a simple, open-source, lightweight and privacy-friendly web analytics, using the plausible-hugo integration
• local, static search (i.e. not using SaaS such as Google/Bing/etc.) Perhaps via pagefind?
• Comments? Perhaps via giscus?
• Fediverse/etc. publication?

Testing

Pre-commit

Linting

(Code) syntax checker, grammar/style checker (vale et al.), etc.

Link checking

• Check for broken (internal) links with hyperlink.
• Consider --check-anchors and --sources.
• dump a list of external hyperlinks.