Articles
How this Site was Made

How this Site was Made

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
9

export DEST_DOMAIN=<YOUR_DOMAIN_HERE>
brew install mise
cd ${DEST_DOMAIN}
mise use hugo[@<some version>]

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
hugo.yaml
1
2
3

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

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"
type: docs
# prev:
# next:
sidebar:
  open: true
---

Markdown Tips

This site supports CommonMark as a “standard” Markdown:

  • Bold text uses **asterisks**
  • Italic text uses *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

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.

Next: Wouldn’t it be nice if …?

Testing

Pre-commit

Linting

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

Link checking

ArticlesMacOS: Configuration