September 14, 2019

Actual content: Hugo

In the previous post we described the basic setup to get an https server running on OpenBSD. This post will continue on how to set up Hugo for a basic markdown-generated website.


\

Let’s go ahead and install hugo and set up its base directories, on the server:

pkg_add hugo git
mkdir /var/www/htdocs/polynomial.space && cd /var/www/htdocs/polynomial.space
hugo new site ./ # hugo will autogenerate its directory structure here

Backing your files in git is technically not needed, but is almost universal for md-generated sites, and most md-gen software expect you to practice ‘draft locally, push finalized.’

For our purposes, a simple non-bare repository should suit our purposes. In more robust environments, you may also find a bare remote to controls a test-production setup.

git init .
git config receive.denyCurrentBranch updateInstead # If you want to push to a non-bare git, you'll want this
git config user.name ${USER}
git config user.email ${USER}@$(hostname)
git add .

As hugo usage is rather tied with git, you’ll find that hugo’s themes are generally in git repositories. Since the site directory is already under git, if you clone a theme, you’ll want to do so as a git submodule

cd themes && git clone 'https://github.com/natarajmb/charaka-hugo-theme.git'
git submodule add https://github.com/natarajmb/charaka-hugo-theme.git charaka-hugo-theme
cp charaka-hugo-theme/exampleSite/config.toml ../config.toml
git commit -am "Fresh hugo install"

Depending on which theme you choose, they might have extra instructions detailed in their own READMEs. Generally they’ll just ask you to pull and edit their config.toml from their exampleSite/ directory. Sometimes you may also have to copy the archetypes/ directory.

From here you can run hugo server and start playing with config.toml to verify that things work.

Since we’re running on a server rather than locally for now, the --bind and --baseURL options will need to be provided.

It is not suggested you actually use hugo’s server feature for actual publishing on the server; it is intended for testing drafts locally.


\

Next, we’ll want to clone the hugo directory from our server so we can have a local copy to write our drafts. On the local machine:

git clone polynomial.space:/var/www/htdocs/polynomial.space
cd polynomial.space && git submodule update --init --recursive

You’ll need to ensure your permissions are appropriate for the webserver to access, and allow you to push changes via git. As this is a simple webserver, I’ve added my user to the daemon group and made the base web directories chmod 664. Note that this is probably inapproprate for larger environments.

As a final touch we can use a git hook to automatically regenerate the website upon pushed changes. From the base git directory on the server:

cat <<\EOF >.git/hooks/post-receive
#!/usr/local/bin/bash

pushd /var/www/htdocs/polynomial.space
hugo --noTimes
popd
EOF

chmod 755 .git/hooks/post-receive

Now we can start authoring pages under content/posts/*.md, preview them with hugo server, and push them to the server with git.