First Steps with Hugo

Mon, 29 Jul 2024 19:11:41 -0600

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.

The Return Of The Blog!

Mon, 29 Jul 2024 15:05:49 -0600

This blog was originally located on a self-hosted WordPress instance but I decided to shut it down because I had shifted nearly all of my blogging to my employer’s internal blog and I felt I couldn’t commit to the time required to keep my self-hosted instance secure.

I had soft plans to bring it back up briefly to capture a static mirror of the contents but never got around to it. Life, sigh.

Why is it returning now?

There are several reasons. The first is that it’s now a lot easier to use Markdown format. To be specific, I’m currently experimenting with Obsidian (editor) and Hugo (static site generator). It has a good balance between functionality and ease-of-use.

The second reason is that I see a growing need to produce coherent sites from independently produced Markdown documents. This format is flexible enough to support tables, links, etc., but without the endless pits of despair of modern HTML.

The final reason is because I have something to say.

Expect ongoing changes

A final note - the appearance of this site will undoubtedly change over the coming weeks and months since I’ve barely scratched the surface of what Hugo offers.

Invariant Properties

First Steps with Hugo

The Return Of The Blog!