First Steps with Hugo

I have started with Hugo for my static site generation since it is so popular and has no external dependencies. My initial plan was to self-host on S3 but decided to follow the lead of the video listed below instead. If I ever change my mind it is a trivial task to add a GitHub Action to handle it.

The actual steps performed were:

System Preparation

  • Install hugo and obsidian
  • Create invariantproperties organization
  • Create blog repository
  • Create invariantproperties.github.io repository
$ sudo apt-get install hugo obsidian

Hugo site preparation

These steps prepare a Hugo site with proper GitHub submodules.

  • Clone blog repository
  • Create new site
  • Include the selected theme via a git submodule
  • Link to the destination repository via a git submodule
  • Edit hugo.toml to include theme=hugo-flex
  • (optional) Launch the test server
$ git clone git@github.com:invariantproperties/blog.git
$ cd blog
$ hugo new site invariantproperties
$ git submodule add https://github.com/ldeso/hugo-flex.git invariantproperties/themes/hugo-flex`
$ git submodule init invariantproperties/themes/hugo-flex
$ git submodule add -b main git@github.com:invariantproperties/invariantproperties.github.io.git invariantproperties/public
$ echo theme=hugo-flex >> hugo.toml
$ hugo server

Obsidian setup

I’m evaluating Obsidian as my primary Markdown editor.

  • Launch Obsidian
  • Click on current vault (lower left-hand corner) and select Manage vaults...
  • Select Open folder as vault
  • Select the top of the Hugo site - not the top of the blog repository

Create and publish the first post

We can create new posts via either the command line or via our editor. We should use the former, at first, since this ensures any required properties are set.

  • Create a new document
  • Edit and save this document. It will not be visible in the generated website unless draft is set to false
  • Generate the static pages
  • Commit the pages
  • Commit the source pages
$ cd blog/invariantproperties
$ hugo new posts/first.md

# (edit and save file)

$ hugo -t hugo-flex

# (commit and push generated pages)

$ cd public
$ git add *
$ git commit -m 'initial post'
$ git push [origin main]

# (commit and push source documents)

$ cd ../..  # (move to top of the repo)
$ git add *
$ git commit -m 'added first page'
$ git push

Publishing the site

We’re almost done - we have to tell GitHub to publish the contents of the repository.

  • Go to the invariantproperties.github.io repositoy page
  • Select settings
  • Click on Use your GitHub Pages website

Another option is the organizational level settings. This is required if you wish to use a custom domain name.

Resources

Creating a Blog with Hugo and Github in 10 Minutes (YouTube)

Other static site generators

Jeykll is another strong contender, esp. if you’re using GitHub Pages to host your site.