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
andobsidian
- 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 includetheme=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 tofalse
- 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.