Hugo

Hugo is one of the most popular open-source static site generators.

The easiest way to use Hugo on NixOS is to install Hugo and git from nixpkgs:

{ pkgs, ... }: {
  environment.systemPackages = [
    pkgs.git
    pkgs.hugo
  ];
}

You can now follow the Hugo Quick start tutorial and not much is different from running Hugo on other Linux distributions.

A dev shell

You may, however, want to limit the installation to your Hugo-specific projects. This makes it possible for you or others to download your repository and work with its dependencies, since they are fully specified within the project.

{ pkgs ? import <nixpkgs> {} }:
  pkgs.mkShellNoCC {
    packages = [
      pkgs.git
      pkgs.hugo
      pkgs.just
    ];
  }

To avoid having to type nix-shell or nix develop to access the dev shell, consider enabling nix-direnv.

A theme

To make the site look nice, find a theme and pin it:

{ pkgs ? import <nixpkgs> {} }: let
  hugo-theme = builtins.fetchTarball {
    name = "hugo-theme-m10c";
    url = "https://github.com/vaga/hugo-theme-m10c/archive/8295ee808a8166a7302b781895f018d9cba20157.tar.gz";
    sha256 = "12jvbikznzqjj9vjd1hiisb5lhw4hra6f0gkq1q84s0yq7axjgaw";
  };
in
  pkgs.mkShellNoCC {
    packages = [
      pkgs.git
      pkgs.hugo
      pkgs.just
    ];

    shellHook = 
      mkdir -p themes
      ln -snf "${hugo-theme}" themes/m10c
    ;
  }

To activate the theme, after running hugo new site . --force, a hugo.toml file with something like:

baseURL = 'https://nix.tools/'
languageCode = 'en-us'
title = 'nix.tools'
theme = 'm10c'

and a justfile with something like:

 # See available `just` subcommands
 list:
     @just --list

# Create scaffolding and hugo.toml
init:
    hugo new site . --force

# Serve website on http://127.0.0.1:1313/
serve:
    hugo serve -D

# Create new post in content/posts/
post MDFILE:
    mkdir -p content/posts
    hugo new content 'content/posts/Template:MDFILE' || true

and a .gitignore like:

# Hugo output
public/

# Misc.
.hugo_build.lock
.direnv/

the justfile serves to remind what commands are useful to operate the static site.

Simplified deployment via SSH/SCP

Deployment with Nix gets a little complicated, so let’s just rehash how one might do it without:

# Generate static assets in public/
$ hugo

# Compress and upload static assets
$ tar cfz public.tgz public/
$ scp public.tgz server:/var/www/website
$ ssh server 'cd /var/www/website && tar xfz public.tgz'

This can be summarized as a justfile action:

# Deploy to DIR on SERVER using tar/ssh/scp
deploy SERVER='nix.tools' DIR='/var/www/nix.tools':
    hugo
    tar cfz public.tgz public/
    scp public.tgz https://nixos.wiki:Template:DIR
    ssh https://nixos.wiki 'cd Template:DIR && tar xfz public.tgz'

and running e.g. just deploy or just deploy nix.tools /var/www/nix.tools.

Deploying a static website like this is enough for a lot of people.