Static site generators and the modern web.

Static site generators have liberated modern web development. No, they don‘t scale up for dynamic, websites. Those still need server-side logic. No, they don’t make it easier than Geocities once did, neither as Wix or Cargo or anything like that. They’re not meant for ease of use. You need to own a web server, know how to use an FTP client or (gasp) an SSH terminal.

Enter Hugo

Hugo is a static site generator. In short, it is a small executable programme (it’s 2018, we could say an app) that takes Markdown formatted text files and outputs plain HTML files, and it’s very fast. It’s pretty extraordinary that it comes with no depedencies, or frameworks to install. It just runs and makes things. But you need to handle it through the terminal, of course.

It is however perfect for very fast, websites of any size that are maintained by few users. It is perfect for future-proof websites, that can keep living no matter how the stack changes.

Hugo makes use of themes in which it wraps your content. At the time of writing, this website uses argil a purpose built, modular theme. It’s not production ready yet —and most likely will never be— but it‘s usable enough.

Hugo on Windows 10

The following are —mostly— notes hastily thrown together. My own workflow benefited a lot from other scraps posted in forums or blogs, so here’s hoping that the prove useful to some one.

On Windows, it would probably look like the following: your content lives in a directory named /content and your output HTML files would lie in /public.

├── /archetypes
├── /assets
├── /content
├── /data
├── /layouts
├── /static
├── /themes
├── config.yaml
└── hugo.exe

On Windows, batch files are handy to quickly run repetitive commands. To quickly run Hugo for local testing, you could use something along these lines, to open a browser window and run the Hugo local server, Save the following as run-server.bat in the same directory above:

start "" http://localhost:1313/
hugo.exe server -D || pause

More complex instructions, are better handled with Bash, via the Windows Linux Subsystem, which you first need to install. The following generates the files to upload to your server, minifies them with another single-executable utility called Minify, then uses rsync to sync to your remote server. Save the following as deploy.sh in the same directory above:

## make sure you use Unix line endings

## change the following variables appropriate

## delete the previously generated files
rm -r ${LOCALDIR} &&

## run hugo
./hugo.exe &&

## run minify against all files in the public directory
./minify.exe -r -o ${LOCALDIR}/ ${LOCALDIR} &&

# remotely sync to the webserver
# see https://explainshell.com/
# --whole-file is workabound for WSL bug https://github.com/Microsoft/WSL/issues/2138
rsync -huavz --partial --progress --delete --exclude '.dat*' --exclude '.git*' ${LOCALDIR}/ ${USER}@${HOST}:~/${REMOTEDIR}

## open in web browser
explorer.exe "http://heracl.es/" &&

exit 0

Unfortunately Bash scripts cannot run from Windows with double-click, but a Batch file can run them instead. Save the following as run-deploy.bat in the same directory above:

bash deploy.sh

Other workflows

Some notes on workflows and Hugo theme development that I found useful when getting started: