Hugo

Prototyping a Hugo debug bar

I spent some time today working on a “debug bar” for my Hugo themes.

Demo is here: https://distracted-volhard-ea30bf.netlify.com/services/accounting/
Github Here: https://github.com/JugglerX/hugo-debug-bar/blob/master/themes/hugo-hero-theme/layouts/partials/debug.html

I posted earlier in another thread some thoughts about why I think this kind of tooling would be beneficial to Hugo Printing template lookup order and chosen template - I could elaborate further if needed.

Much of the logic for printing the hugo variables is taken from here - https://github.com/kaushalmodi/hugo-debugprint/blob/master/layouts/partials/debugprint.html

Mainly I have jazzed that up with some nicer css and javascript. I’ve also briefly taken the time to curate the variables which are shown in a way I feel makes for a better user experience.

Currently the main issue, is that to display the currently chosen template, you must manually declare and pass the template name as an argument to the debug partial. And you must do this from within each layout file. This means that this solution requires a non trivial amount of setup work. It’s also a solution that is implemented at the theme layer, rather than a core feature of Hugo.

My hope would be that this could form the basis and inspiration for further work into a core debug bar for Hugo.

15 Likes

This is very useful. Thank you!

I’ll do my best in the next few days to bundle all the CSS and JS inline inside the debug partial so it’s easier to transport between themes. For the moment you can see scss/debug.scss and js/debug.js along with layouts/partials/debug.html and layouts/partials/debugbar.html for the relevant code.

I have often felt the problem of understanding “where is this coming from?”, especially in my early days with Hugo.

I had wondered about a possible feature like a flag on the server, during build, to tell Hugo to provide me a map of all source files that go into a specific output file.

But this option might actually be nicer. I’ll be keeping an eye on this. Thanks.

P.S. - maybe you can add something to tell us where the CSS is coming from?

Great debug bar.

That’s not Hugo-specific, the browser inspector is usually enough. If you’re using HugoPipes for SASS / SCSS you may want to enable sourcemaps to get more information in the browser. Personally I don’t mind publishing sourcemaps to production (certainly not for CSS, JS is more complex), but you could always alter the dict depending on dev/prod environments.

That’s super cool!

I’m not sure the information of the “template path” (.template) name is that relevant, certainly not to the point of having to copy/pate the debug partial call into every layout files.

For my own need, I would simply add your partial to the baseof, and limit its context the the current page.

Also, I would wrap the call in a {{ if site.IsServer}} as well, but that’s me :wink:

I am not using Hugo Pipes… I can see CSS file names in dev console, but these are just output files. I would like to be able to get to the source files.

The filenames that the console gives me are not enough, because Hugo uses some logic to select which CSS files override which (from the theme, or specific to this site, etc), and that is the kind of thing where you get lost when you’re a newbie. So I think it would fit this “debug bar” perfectly to guide us to all the necessary source files.

Gotcha. I don’t think that information would be available to the page - the partial doesn’t have access to the markup in other layout files (header.html, footer.html etc.)

The template name is the most relevant part for me! The initial reason I made the debug bar was to assist with debugging the Hugo layout lookup order. It’s interested to hear other perspectives thou.

I agree having to copy/paste the debug into each template is a burden and is a big problem. So yeah if the template name is not important to you, you can really simplify things by putting it in the baseof as you say. It makes the debug bar much easier to just “drop in” to a theme

Taking the long-term view, and considering Hugo will grow in popularity tremendously :sunglasses:, I think Hugo should be really transparent about which files it is using, even for people who don’t understand it that well (to the extent that this is possible).

So I would really value this feature to be as complete as possible. “Oh you want to change this bit here? Just go to this file and edit it”. That would not just be cool, it would be Hugo-cool (that’s the next level).

I understand that would require the feature to be built in to the server, the build process. Of course this shouldn’t slow Hugo down (that’s a no-no in this project) but it could be some sort of debug build flag, that builds a data structure indicating which source files went into the production of each output file. Then this could be queried by the debug bar.

I’m just thinking out loud here, I’m not really doing a feature request or expecting it to get done soon. But I’d love to hear your thoughts.