Development Notes

Hugo Config

#

Sometimes, the configuration of hugo can get complicated. Typically, configurations will be in:

% tree -aF config
config/
└── _default/
    ├── hugo.toml
    ├── languages.en.toml
    ├── markup.toml
    ├── menus.en.toml
    └── params.toml
└── <environment>/*.toml
└── ...

To see excatly how the server is configured, use this command and replace <config-dir> with the top level directory containing your configuration files:

# from the root of your project
hugo config --configDir <config-dir> | less

so in tthe case were all your configuration environments live under the config directory, the command would be:

hugo config --configDir config | less

Setting up hugo theme and modules

#

This site uses the blowfish theme and the dilex-hugo-shortcodes module. The bare minimum hugo.toml file looks like this:

baseURL = "https://example.com/"
languageCode = "en"
title = "Example hugo website"

[module]
  [[module.imports]]
    path = "github.com/nunocoracao/blowfish/v2"

  [[module.imports]]
    path = "github.com/DilexNetworks/dilex-hugo-shortcodes/module"

The website needs to be set up as a go module after setting up the configuration file. This can be done with the following command where the github part is the name of the github repo:

hugo mod init github.com/example.com

We also need to add a hook to grab css and js files for the dx/ shortcodes module. We can do this by adding a file to our partials which will be called layouts/partials/extend-head.html with the following content:

{{/* DX shortcodes head integration */}}
{{ if templates.Exists "partials/dx/extend-head.html" }}
  {{ partial "dx/extend-head.html" . }}
{{ end }}

The minimal(ish) directory tree is going to look something like:

website-repo/
├── .git/
├── .gitignore
├── .hugo_build.lock
├── .idea
├── .gitignore
├── .pyenv
├── archetypes
    └── default.md
├── assets
├── config
│   └── _default
│     └── hugo.toml
├── content
│ └── design
│     └── design-concepts.md
├── data
│   ├── authors
│   │   └── andrew.json
│   └── version.json
├── go.mod
├── go.sum
├── layouts
│   └── partials
│       └── extend-head.html
├── Makefile
├── requirements
│   └── development.txt
└── version.txt

Debugging

#

In hugo templates you can detect whether you are running in draft mode or not by checking:

{{ $isDev := .Site.BuildDrafts }}

One nice feature of this is that you do not have to actually change any code when going back and forth between production and development environments. All the code stays the same and just behaves slightly differently when changing modes.

The check looks like this:

{{ if $isDev }}
  {{ warnf "DX DEBUG: debug message print to console" }}
{{ end }}

Another option is to include something like this in your extend-head-uncached.html partial (in `layouts/partials’):

{{/* expose a tiny JS flag only in dev so our scripts can check it */}}
{{ if $isDev }}<script>window.__DX_DEV__=true;</script>{{ end }}

which will create a global JS flag __DX_DEV__ that you can check in your scripts. This would go at the top of you javascript file:

var __DEV__ = (typeof window !== 'undefined' && window.__DX_DEV__ === true);
if (__DEV__) { try { console.log('dx: photo.js loaded'); } catch(e){} }