Maintain Websites Using Hugo
This document assumes you have Hugo 0.52 or newer installed. Use the hugo version
command to determine which version you have access to. Once the steps below have been followed to set up Hugo we will migrate an existing site so that it can be managed by it.
Set up Hugo
- Create a directory structure for your new website:
hugo new site <your directory's name>
- Switch to YAML config files instead of the default TOML:
mv config.toml config.yml
- Edit the newly generated configuration file:
languageCode: "en-us"
title: "Your site's name"
- Refer to the official documentation for more information about the default directory structure
- When Hugo runs it creates a
resources
directory which isn't covered in the official documentation. It is a resource cache where generated files, such as images, are stored. - To make use of Hugo's asset processing features a top level
assets
directory needs to exist - The remaining files for your site that won't be processed by Hugo should go in the
static
directory - More information about asset management:
- When Hugo runs it creates a
- Create a new
assets
directory and copy your style sheet to that location:
mkdir -p assets/css
cp ~/path/to/your/style.css assets/css/
- To minify and fingerprint our
style.css
use the following lines in your template
{{ $style := resources.Get "css/style.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">
- Remove any unneeded directories and create three new ones:
rm -rf archetypes data themes
mkdir -p layouts{_default,partials,shortcodes}
- Start the Hugo server:
hugo server
- Visit http://localhost:1313/ Any changes made in your project directory will be reflected in your browser
Migrate a Website to Hugo
We will make changes to the Social Justice Repair Kit site so that it can be managed using Hugo.
- Place any JavaScript, images, and any other non-CSS assets in the
static
directory - In your
layouts/partials/
directory create templates that will be commonly used by other pages, for example,header.html
andfooter.html
These will be referenced by other files using thepartial
keyword - Create a
layouts/_default/baseof.html
template that contains general markup that will be used by every page - Create a
layouts/_default/list.html
template which will be used by every section's index page in your site - Create a
layouts/index.html
template that will be used by the home page - Optionally create additional subdirectories in the layouts directory for any other section pages
- Once the layout templates are in place you can start adding markdown files in your
content
directory which will make up the majority of site maintenance work
It would be ideal if the majority of user managed content is authored solely using markdown with a minimal amount of shortcodes. One way of accomplishing this is by splitting up markdown files in the content
directory, including a type property in the front matter, and then referencing that type property in layout templates where most of the markup can live.
Further Exploration
So far the Inclusive Cities and Social Justice Repair Kit projects have used Hugo to maintain content and only a subset of its features have been tested. As we use it for other projects we will most likely need to spend time trying out the following features:
- Hugo's multilingual support – it looks like translations live along side files for accompanying languages
- Search – Algolia provides free accounts to open source projects