Debug

This module for GoHugo adds debugging partials for many use cases.

Add this module
[[module.imports]]
path = "github.com/davidsneighbour/hugo-debug"
disable = false
ignoreConfig = false
ignoreImports = false
Latest Version v1.5.19 (2022-07-31)
Fix to this version
hugo mod get github.com/davidsneighbour/[email protected]

Notes

  • This is a GoHugo module to use while you are developing your theme or website. It will slow down the build process. Knowledge about variables in our template and NOT speed is our main priority.
  • This module is based on the work in kaushalmodi/hugo-debugprint.

Installing

First enable modules in your own repository if you did not already have done so:

1hugo mod init github.com/username/reponame

Then add this module to your required modules in config.toml.

1[module]
2
3[[module.imports]]
4path = "github.com/davidsneighbour/hugo-debug"
5disable = false
6ignoreConfig = false
7ignoreImports = false

The next time you run hugo it will download the latest version of the module.

Updating

1# update this module
2hugo mod get -u github.com/davidsneighbour/hugo-debug
3# update to a specific version
4hugo mod get -u github.com/davidsneighbour/[email protected]
5# update all modules recursively over the whole project
6hugo mod get -u ./...

Usage

Either add disabled = true to your live server configuration or check, if you are on a development server by using {{- if site.IsServer -}} around your calls to the partials.

A quick sample for it’s usage is the following partial that I use in my footer area:

 1{{- if site.IsServer -}}
 2  <footer id="debugging">
 3    <div class="container">
 4      <div class="row">
 5        <div class="col-12">
 6          {{- partial "debugprint.html" . -}}
 7          {{- partial "debugprint.html" .Params -}}
 8          {{- partial "debugprint.html" .Site -}}
 9          {{- partial "debugprint.html" .Site.Menus -}}
10          {{- partial "debugprint.html" .Resources -}}
11          {{- partial "debugprint.html" .File -}}
12          {{- $layoutTrace := .Scratch.Get "trace" -}}
13          {{- with $layoutTrace -}}
14            {{- partial "debugprint.html" . -}}
15          {{- end -}}
16        </div>
17      </div>
18    </div>
19  </footer>
20{{- end -}}

Debug from within layouts

To print a variable in one of your layouts:

 1{{ partial "debugprint" . }}
 2{{ partial "debugprint" .Params }}
 3{{ partial "debugprint" site }}
 4{{ partial "debugprint" site.Menus }}
 5{{ partial "debugprint" .GitInfo }}
 6{{ partial "debugprint" .Resources }}
 7{{ partial "debugprint" .File }}
 8
 9{{/* in shortcodes */}}
10{{ partial "debugprint" . }} <!-- this will debug the internals of the shortcode -->
11{{ partial "debugprint" .Position }} <!-- this will show where the shortcode was called -->

Exchange the context . with whatever variable you want to debug. Sub-collections or sub-slices might require extra setup to be debugged, depending on the structure and type of the values.

Debug from within markdown (content) files

To debug page data from within a Markdown file:

1{{< debugprint >}} <!-- the same as -->
2{{< debugprint "page" >}} <!-- debugs page variable -->
3{{< debugprint "params" >}} <!-- debugs page params -->
4{{< debugprint "site" >}} <!-- debug sites params -->
5{{< debugprint param="bla" >}} <!-- debugs .Params.bla -->

Debugging from within Markdown requires very explicit configuration in the shortcode template. Open a new issue if you require a specific debugging subject.

Debug from your layout file into the CLI/server log

Some times we developers want to inform and warn our users, or even throw an error. The debug partial is your connection to the CLI with some more options than GoHugo’s internal error functionality.

1{{- partial "debug.html"
2      (dict
3        "message" "going into PostProcessing"
4        "context" .
5        "severity" "warn"
6        "level" 4
7        "slug" dnb-some-error
8      )
9-}}

Note: Multiline layout functions are supported since Hugo 0.81.0. In older versions remove the new lines in these samples.

The dictionary options are as follows:

  • message: The message to print. It will be prefixed with the datetime and the severity slug.
  • context: The context to debug, typically the dot. There is currently nothing else than the dot expected, we have explicit debugging on the todo list where the context can be something to debug to the CLI.
  • severity: Slug marking the severity level. one of debug, info (default), warn, error or fatal.
  • level: 1 to 10 for the severity level. Can be used to have a more fine grained control over severity levels.
  • slug: (not implemented, keep an eye on #71) an ID to use so users can silence errors (level 7 and up)
  • namespace: (not implemented as partial option, see configuration section) namespace slug to differentiate yourself from others (default dnb)

The resulting error message will look like this:

SEVERITY TIMESTAMP [namespaceslug/severity-level] message

Note: GoHugo will print all messages that occure more than once will printed only once. This applies to identical error messages. To work around this (if you wish to for instance notify the user about multiple image transformations not working) you should add an identifier (the image url? the resource id?) to the debugging message.

Note2: Hugo makes only ERROR and WARN levels available, so all SEVERITY stamps in the beginning of each log line will be either a red ERROR (from errors and fatals — 1 to 4) or a yellow WARN for all others (debug to warn — 5 to 10).

Debug pages in a comprehensive format

While all other debugging options above are flexible options to debug any value, the debugpage partial opts to show a bunch of interesting information about the page object it is called on. It’s quite specific and tries to cut out the noise.

You can add the following call to any layout file:

1{{ partialCached "debugpage.html" . . }}

or by using the following shortcode in your Markdown:

1{{< debugpage >}}

The Markdown shortcode will take the context of the currently parsed page while the template call will take what you hand over.

Configuration

The debug component is configurable via the params section in your configuration. The following samples will assume your configuration lives in config/_default/params.toml. If you are using a root level configuration don’t forget to add params. in front of each section and put it at the right place.

1[dnb.debug]
2namespace = "dnb"
3debuglevel = 8
4disablenote = false
  • namespace: (string) namespace slug for your plugin/theme. keep it short. three characters are enough. There is no restriction on this, but think about the look of the loglines with longer namespaces.
  • debuglevel: (number, 0 to 10) set the severity level that should maximally be shown. The higher the more info/debug on your CLI. 10 is maximum and can be helpful to debug issues.
  • disablenote: (boolean) disables the note at the beginning that the debug module is used.

Styling

A simple Bootstrap 5 based SASS style is mounted into assets/scss/_debugprint.scss to be used via @import "debugprint";. Depending on your own styles you will probably have to add your own markup.

Formatters

Formatters are dedicated layout files for a certain type. The component offers reusable templates for any structural need (two column, three column tables or plain print) and takes over the markup and styling of the output. The following subsections will explain the procedure by use of some samples.

Configuring formatter

Adding formatter layout

Development

Setup development environment

  • copy .env.sample to .env and fill with your local information
  • run npm install to install all dependencies
  • run npm run server to start the server and see the documentation

The development server includes testing via Cypress and examples for (hopefully at the end) all debugging formatters we have added. Every formatter should have a testing page with at least introductory explanations to it’s functions.

Running tests

  • to be implemented

Contributing to GoHugo Debug

Reporting issues

If you have found a bug in GoHugo Debug or miss some documentation, please use the issue tracker to report. If it’s a support request you can do the same, but please note that this is an open source project and I might not be able to invest much time in getting your problem solved.

Whatever your issue is, please be as precise as possible and add enough information to reproduce your problem/suggestion.

Submitting pull requests

I welcome contributions in form of pull requests. There are no guidelines yet as to how a pull request should be done, so please be as extensive as possible about the reasoning behind your changes and why you think it will be a good addition. Typos of course can be merged without too much discussion.

DNB Org uses Codacy to keep some modest code quality. Keep an eye on your pull requests Codacy badge (on the README.md top of your branch). “If it’s not A it’s not Ok” ;)

FAQ

Should there be frequently asked questions then they will appear here.