Hugo

Hugo is a static site generator written in Go. It builds websites from content files and templates, supporting features such as Markdown content, themes, and flexible deployment options. Hugo is available in the NixOS ecosystem and can be used for a variety of web publishing tasks.

Installation

Shell

To temporarily use Hugo in a shell environment, you can run:

nix-shell -p hugo

This will provide a shell with Hugo available without adding it to your system configuration.

System setup

To install Hugo, add it to either the system-wide environment.systemPackages in /etc/nixos/configuration.nix or to the user-specific home.packages in ~/.config/nixpkgs/home.nix.

# System-wide installation (in /etc/nixos/configuration.nix)
environment.systemPackages = with pkgs; [
  hugo
  git # Useful for managing Hugo themes and site repositories
];

# User-specific installation (in ~/.config/nixpkgs/home.nix)
home.packages = with pkgs; [
  hugo
  git
];

Then, rebuild your system or apply your Home Manager configuration:

# For system-wide installation
sudo nixos-rebuild switch

# For Home Manager
home-manager switch

Configuration

Basic

Basic Hugo configuration involves creating a new site and choosing themes. Use the following command to create a new Hugo site:

hugo new site my-site

Navigate to the site directory and add a theme as a git submodule or download it directly. For detailed steps, refer to the official Hugo documentation.

Advanced

☶︎

This article or section needs to be expanded. Section incomplete, needs detailed content on advanced configuration with NixOS Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

Tips and tricks

Development Shell

You may want to limit Hugo installation to your project only. This allows contributors to use the exact dependencies specified for the project:

❄︎ shell.nix

{ pkgs ? import <nixpkgs> {} }:
  pkgs.mkShellNoCC {
    packages = [
      pkgs.hugo
      # Other dependencies for your project.
    ];
  }

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

Theming

Nix can be used to deterministically import Hugo themes by pinning them to a specific revision:

❄︎ shell.nix

{ pkgs ? import <nixpkgs> {} }: let
  hugo-theme = pkgs.fetchFromGitHub {
    owner = "vaga";
    repo = "hugo-theme-m10c";
    rev = "862c6e941be9bc46ce8adc6a2fa9e984ba647d6f";
    hash = "sha256-wcJSGjL/u43hPLblPmUhusqiMmadVBWJhihRinRXqzg=";
  };
in
  pkgs.mkShellNoCC {
    packages = [
      pkgs.hugo
      # Other dependencies for your project.
    ];
    shellHook = ''
      mkdir -p themes
      ln -snf "${hugo-theme}" themes/m10c
    '';
  }

After creating a hugo.toml file like the following, activate the theme with hugo new site . --force:

≡︎ hugo.toml

baseURL = 'https://example.com/'
languageCode = 'en-us'
title = 'example-site'
theme = 'm10c'

Troubleshooting

☶︎

This article or section needs to be expanded. Section incomplete, needs detailed troubleshooting steps Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.