HuMC

(aka Hugo Master Controller or Hugo Multi-site Controller)

HuMC is:

• A script, 'hum' to help manage, develop and deploy a collection of web sites built with Hugo.
• A starter site for Hugo (it may become several possible starter sites).
• A starter theme for Hugo based on HTML5 Boilerplate called Bunait.

I pronounce HuMC as 'hum'.

Dependencies

The new-site task relies on sed, this works fine on Linux but some BSD based sed versions don't allow case insensitive search - AFAIK that includes OSX - so install gnu-sed using your preferred package manager (Brew, Macports etc).

You'll need Hugo of course. You'll need a hugo-extended version to have the PostCSS asset processing in Bunait work. I use a script -- you'll find a copy at extras/hugo-update.sh -- derived from David Kebler's originalhugo-update script. See the comments inextras/hugo-update.sh for details and links.

Setup and run the hugo-update script:

chmod +x hugo-update.sh
# Check the script contents before running it!
sudo mv hugo-update.sh /usr/local/bin
sudo hugo-update.sh

You'll need Nodejs installed for some asset processing.

PostCSS is used to process CSS. Install postcss-cli globally, it is not listed as a dev dependency in package.json of the Bunait starter theme.

npm i -g postcss-cli

The setup task will check if these are installed, with the exception of gnu-sed.

Note

Commands documented below always use the short cli flag. If you wish to learn the long option name run: 'hum -h'.

Install & setup

Clone HuMC from Github.

Create a symbolic link into your $PATH for easier use.

sudo ln -s /path/to/HuMC/hum /usr/local/bin/hum

Run setup task.

cd HuMC
hum --setup

Test HuMC.

cd starters/five-page
hugo serve

And visit localhost:1313 to check everything is working.

Use 'ctrl-c' to quit server.

Init configuration or clone existing

Hum uses the sites/conf directory to store configuration files for each site. Hum will create this path and init a git repository when --create-conf is run.

hum -c

However if you use multiple devices or collaborate with other site developers you'll need portable configuration of the sites HuMC manages. On the first HuMC instance add a remote to a git repository in sites/conf and push.

On further installations of HuMC you wish to keep in sync you should clone this conf repository instead of running hum -c.

Start a new site

From within the HuMC directory run hum --new-site SITENAME e.g. for a site named 'awesome' do:

hum --new-site awesome

Or using the short cli flag:

hum -n awesome

This will create a new site at sites/awesome with a the base theme Bunait sites/awesome/theme/bunait ready to go. It will also have run git init, git add ., git commit and created staging plus production git branches.

(Optional, but wise) Next add a git remote and push the starter code before you begin work.

Use the '--all' flag to push all branches at once:

cd sites/awesome
git remote add origin forgejo@forgejo.example.com:username/awesome.git
git push -u origin --all

It's a good idea to set the baseURL for the staging and production sites at this point if you know what they'll be. For our example site 'awesome' edit sites/awesome/config/staging/config.toml and sites/awesome/config/production/config.toml.

To view your new site and begin work change directory and launch Hugo's built in server:

cd sites/awesome
hugo server

Then visit localhost:1313 in your browser as normal for Hugo.

Workflow

Keeping synced instances up to date

Run with -u to update the sites/conf directory, then -p to update sites/SITENAME working copies (note that currently this only updates the checked out branch, not all branches) and finally with -j to update node_modules in any site directories.

hum -u
hum -p
hum -j

Development

cd into sites/SITENAME and run hugo serve. Normal Hugo site development applies.

The new site command creates staging and production branches in addition to main. Development happens on main, the use of staging and production branches should be self evident!

The site is created with a duplicate of the Bunait theme. Bunait is intended as a starter theme which you modify per site. You can add any other theme's you choose, however - don't forget to update Hugo config to use them.

Content editing

Content should be edited as normal.

Deployment

Deployment will be assumed to be via Git.

Add a post commit script to your git repository that deploys code from the staging branch to a staging site and ditto for production.

(TODO: Link to my Momod project as an example of automated deployment setup. Issue here.)

List of available hum commands

• hum -s Check hum setup.
• hum -c Creates the sites/conf directory
• hum -u Update the sites/conf directory working copy.
• hum -p Update sites/SITENAME working copies including checking out any new sites.
• hum -j Update node_modules in theme folders (use after hum -p).
• hum -n SITENAME Creates a new site in sites/SITENAME with config file in sites/conf/SITENAME.conf.
• hum -l List sites.
• hum -k Clean sites/ directory. Any site found in sites/ but without a matching SITENAME.conf will be archived.
• hum -a Archive site. Creates a tar+zip of the named site and moves it to archived/ then removes the SITENAME.conf file and updates plus pushes changes to the conf repository.

History Note

This project was originally titled web-starter-hugo the code of which is on the git branch wsh-1.0.