Debug

Debug v1.5.20

This module for GoHugo adds debugging partials for everything you need to debug.

Add this module
[[module.imports]]
path = "github.com/davidsneighbour/hugo-debug"
disable = false
ignoreConfig = false
ignoreImports = false
Latest Version v1.5.20 (2022-09-22)
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 slows down the build process. Knowledge about variables in our template and NOT speed is our main priority. It is advised to add the module only the development configuration or check if the layout is processed by the development server to minimise its impact.
  • This module is based on the work in kaushalmodi/hugo-debugprint.

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 its usage is the following debugging of a pages data:

 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        </div>
13      </div>
14    </div>
15  </footer>
16{{- 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 the 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 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 occur 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]
2  [dnb.debug]
3    debuglevel = 8
4    disablenote = false
5    namespace = 'dnb'
1dnb:
2  debug:
3    debuglevel: 8
4    disablenote: false
5    namespace: dnb
1{
2   "dnb": {
3      "debug": {
4         "debuglevel": 8,
5         "disablenote": false,
6         "namespace": "dnb"
7      }
8   }
9}
  • 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: (bool) disables the note at the beginning that the debug module is used.

Styling

A quick Bootstrap 5 based SASS style is mounted into assets/scss/_debugprint.scss to be used via @import "debugprint";. Depending on your own styles you can add your own styles based on the following structure:

1.debugprint table,
2table.debugprint {
3  td, th {}
4  .true {}
5  .false {}
6}

Formatters

Formatters are dedicated layout files for certain variable types. dnb-hugo offers reusable templates for any structural need (two and three column tables or plain printout) and takes over the markup and styling of the output.

The configuration for a single formatter offers the following parameters:

 1[dnb]
 2  [dnb.debug]
 3[[dnb.debug.formatters]]
 4    catch = 'navigation\.MenuEntry$'
 5    class = 'struct'
 6    description = ''
 7    internal = 'map'
 8    label = 'Menu Entry'
 9    slug = 'menuentry'
10    type = 'navigation.MenuEntry'
11    weight = 100
 1dnb:
 2  debug:
 3    formatters:
 4    - catch: navigation\.MenuEntry$
 5      class: struct
 6      description: ""
 7      internal: map
 8      label: Menu Entry
 9      slug: menuentry
10      type: navigation.MenuEntry
11      weight: 100
 1{
 2   "dnb": {
 3      "debug": {
 4         "formatters": [
 5            {
 6               "catch": "navigation\\.MenuEntry$",
 7               "class": "struct",
 8               "description": "",
 9               "internal": "map",
10               "label": "Menu Entry",
11               "slug": "menuentry",
12               "type": "navigation.MenuEntry",
13               "weight": 100
14            }
15         ]
16      }
17   }
18}
  • internal (required, if no catch or type is used) - Set to map or slice to give a general indicator of the variable type.
  • catch (required, if no type or internal is used) - A regular expression to match on the type. For instance "navigation\\.MenuEntry$"
  • type (required, if no catch or internal is used) - A string expression to match on the type. For instance boolean.
  • class - A type class to define the output format. Not yet implemented.
  • weight - This parameter is used to sort the formatters before they are used to display a variable type. If no weight is given then the order in the configuration is used. First come (based on type or catch) first serve.
  • slug (required) - Filename part for the formatter layout in layouts/partials/debugging-formatters/SLUG.html.
  • label (required) - A title to show for the debugging-table that is used to debug dictionaries and slices.
  • description (required) - A description to show as overlay for the debugging-table that is used to debug dictionaries and slices.

Evaluation of the type is done in the order or internal, then catch, then type. First come first serve.