Add dump template func for debugging

[bep]

See https://github.com/sanity-io/litter

The output is great (as below from a random test), but may be "too much" even for the advanced user:

&hugolib.Page{ // p0
  pageInit: &hugolib.pageInit{},
  Kind: "home",
  Pages: nil,
  Params: map[string]interface {}{
    "draft": false,
    "expirydate": time.Time{},
    "iscjklanguage": false,
    "lastmod": time.Time{},
    "outputs": output.Formats{ // p1210
      output.Format{
        Name: "JSON",
        MediaType: media.Type{
          MainType: "application",
          SubType: "json",
          Suffix: "json",
          Delimiter: ".",
        },
        Path: "",
        BaseName: "index",
        Rel: "alternate",
        Protocol: "",
        IsPlainText: true,
        IsHTML: false,
        NoUgly: false,
        NotAlternative: false,
      },
    },
    "publishdate": time.Time{},
    "title": "JSON Home",
  },
  Content: "\n\n<h1 id=\"doc\">Doc</h1>\n\nShortJSON\n\nOtherShort: <h1>Hi!</h1>\n",
  Summary: " Doc ShortJSON OtherShort: Hi! ",
  TableOfContents: "<nav id=\"TableOfContents\">\n<ul>\n<li><a href=\"#doc\">Doc</a></li>\n</ul>\n</nav>",
  Aliases: nil,
  Images: nil,
  Videos: nil,
  Truncated: false,
  Draft: false,
  Status: "",
  PublishDate: time.Time{},
  ExpiryDate: time.Time{},
  PageMeta: hugolib.PageMeta{
    Weight: 0,
  },
  Markup: "markdown",
  Layout: "",
  Source: hugolib.Source{
    Frontmatter: nil,
    Content: nil,
    File: source.File{
      Contents: nil,
    },
  },
  Position: hugolib.Position{
    Prev: nil,
    Next: nil,
    PrevInSection: nil,
    NextInSection: nil,
  },
  GitInfo: nil,
  Site: &hugolib.SiteInfo{
    Taxonomies: hugolib.TaxonomyList{ // p34
      "categories": hugolib.Taxonomy{
      },
      "en": hugolib.Taxonomy{
      },
      "tags": hugolib.Taxonomy{
      },
    },
    Authors: hugolib.AuthorList{
    },
    Social: hugolib.SiteSocial{ // p1204
    },
    PageCollections: &hugolib.PageCollections{ // p35
      Pages: hugolib.Pages{
        p0,
      },
      AllPages: hugolib.Pages{ // p687
        p0,
        &hugolib.Page{ // p1
          pageInit: &hugolib.pageInit{},
          Kind: "home",
          Pages: nil,
          Params: map[string]interface {}{
            "draft": false,
            "expirydate": time.Time{},
            "iscjklanguage": false,
            "lastmod": time.Time{},
            "outputs": output.Formats{ // p1202
              output.Format{
                Name: "JSON",
                MediaType: media.Type{
                  MainType: "application",
                  SubType: "json",
                  Suffix: "json",
                  Delimiter: ".",
                },
                Path: "",
                BaseName: "index",
                Rel: "alternate",
                Protocol: "",
                IsPlainText: true,
                IsHTML: false,
                NoUgly: false,
                NotAlternative: false,
              },
            },
            "publishdate": time.Time{},
            "title": "JSON Nynorsk Heim",
          },
          Content: "\n\n<h1 id=\"doc\">Doc</h1>\n\nShortJSON\n\nOtherShort: <h1>Hi!</h1>\n",
          Summary: " Doc ShortJSON OtherShort: Hi! ",
          TableOfContents: "<nav id=\"TableOfContents\">\n<ul>\n<li><a href=\"#doc\">Doc</a></li>\n</ul>\n</nav>",
          Aliases: nil,
          Images: nil,
          Videos: nil,
          Truncated: false,
          Draft: false,
          Status: "",
          PublishDate: time.Time{},
          ExpiryDate: time.Time{},
          PageMeta: hugolib.PageMeta{
            Weight: 0,
          },
          Markup: "markdown",
          Layout: "",
          Source: hugolib.Source{
            Frontmatter: nil,
            Content: nil,
            File: source.File{
              Contents: nil,
            },
          },
          Position: hugolib.Position{
            Prev: nil,
            Next: nil,
            PrevInSection: nil,
            NextInSection: nil,
          },
          GitInfo: nil,
          Site: &hugolib.SiteInfo{
            Taxonomies: hugolib.TaxonomyList{ // p688
              "categories": hugolib.Taxonomy{
              },
              "en": hugolib.Taxonomy{
              },
              "tags": hugolib.Taxonomy{
              },
            },
            Authors: hugolib.AuthorList{
            },
            Social: hugolib.SiteSocial{ // p1196
            },
            PageCollections: &hugolib.PageCollections{ // p689
              Pages: hugolib.Pages{
                p1,
              },
              AllPages: p687,
              RegularPages: nil,
              AllRegularPages: nil,
            },
            Files: &nil, // p1197
            Menus: &hugolib.Menus{ // p691
            },
            Hugo: nil,
            Title: "Tittel på Nynorsk",
            RSSLink: "http://example.com/blog/index.xml",
            Author: map[string]interface {}{ // p1199
            },
            LanguageCode: "",
            DisqusShortname: "",
            GoogleAnalytics: "",
            Copyright: "",
            LastChange: time.Time{},
            Permalinks: hugolib.PermalinkOverrides{ // p1200
            },
            Params: map[string]interface {}{ // p690
              "languagename": "Nynorsk",
              "title": "Tittel på Nynorsk",
              "weight": 2,
            },
            BuildDrafts: false,
            Data: &map[string]interface {}{ // p43
            },
            Language: &helpers.Language{ // p40
              Lang: "nn",
              LanguageName: "Nynorsk",
              Title: "Tittel på Nynorsk",
              Weight: 2,
              Cfg: &viper.Viper{}, // p39
            },
            LanguagePrefix: "/nn",
            Languages: helpers.Languages{ // p41
              &helpers.Language{ // p38
                Lang: "en",
                LanguageName: "English",
                Title: "Title in English",
                Weight: 1,
                Cfg: p39,
              },
              p40,
            },
          },
          Title: "JSON Nynorsk Heim",
          Description: "",
          Keywords: []string{} // p3
,
          Data: map[string]interface {}{
            "Pages": nil,
          },
          Date: time.Time{},
          Lastmod: time.Time{},
          Sitemap: hugolib.Sitemap{
            ChangeFreq: "",
            Priority: -1,
            Filename: "",
          },
          URLPath: hugolib.URLPath{
            URL: "/",
            Permalink: "",
            Slug: "",
            Section: "",
          },
        },
      },
      RegularPages: nil,
      AllRegularPages: nil,
    },
    Files: &nil, // p1205
    Menus: &hugolib.Menus{ // p42
    },
    Hugo: nil,
    Title: "Title in English",
    RSSLink: "http://example.com/blog/index.xml",
    Author: map[string]interface {}{ // p1207
    },
    LanguageCode: "",
    DisqusShortname: "",
    GoogleAnalytics: "",
    Copyright: "",
    LastChange: time.Time{},
    Permalinks: hugolib.PermalinkOverrides{ // p1208
    },
    Params: map[string]interface {}{ // p36
      "languagename": "English",
      "title": "Title in English",
      "weight": 1,
    },
    BuildDrafts: false,
    Data: &p43, // p1209
    Language: p38,
    LanguagePrefix: "",
    Languages: p41,
  },
  Title: "JSON Home",
  Description: "",
  Keywords: p3,
  Data: map[string]interface {}{
    "Pages": nil,
  },
  Date: time.Time{},
  Lastmod: time.Time{},
  Sitemap: hugolib.Sitemap{
    ChangeFreq: "",
    Priority: -1,
    Filename: "",
  },
  URLPath: hugolib.URLPath{
    URL: "/",
    Permalink: "",
    Slug: "",
    Section: "",
  },
}

[moorereason]

I'd be in favor of a general dump template function.

[kaushalmodi]

may be "too much" even for the advanced user

That might be alright is user can specify what they want to be printed. Assuming that the template fn name is dump, may be:

{{ dump .Params }} <!-- Print Page Params when called from a page template -->
{{ dump .GitInfo }} <!-- should also work for structs -->
{{ dump .File }}

I gave the above examples because I ended up creating something like dump but with whatever was available in user-land.. also printing structs needs the user to know the exact elements at the moment.

PS: The .File object is a special PITA as discussed on discourse.

[regisphilibert]

I agree with @kaushalmodi and @moorereason we should be able to print whatever with it.

It is just about presenting readable data to someone who knows what he is looking for.

[bep]

It is just about presenting readable data to someone who knows what he is looking for.

Or someone who does not know what he is looking for finds something that looks interesting and starts using it and one of two things happens

• I change a name, thinking: This cannot be used by anyone?
• They don't understand what it returns and start a new thread on the forum saying ".Moo returns no value. I expect it to return something ... cow related maybe?"

[regisphilibert]

Or someone who does not know what he is looking for finds something that looks interesting and starts using it and one of two things happens

Everybody is already using printf to do just that. (I didn't need a dump func to find about.Resource.AbsSourceFilename).

At least with your own dump function, you get to control what is printable and what is not. Would it be that hard to filter certain keys from the page context ? (chances are 90% of the time people will be dumping something from the page context)

PS: I don't agree with the filtering, but if it's a middle ground, I'll take it.

[bep]

We have legacy history in Hugo with a liberal PR merge policy (with some additions' design looking sub-optimal in retrospect), exported fields/methods that should probably not been exported to the templates (AbsSourceFilename being one recent example; I should have spent the extra amount of work needed to hide it from the templates).

We have once said something in the line of "we merge this now, and see how it works -- if we like it, we document it." That model breaks once people learn how to use printf and GoDoc. But it is still true: If it is not documented on https://gohugo.io/, it is not recommended to use it. Because it may be removed/redesigned in the near future.

So, this dump function will only be added once I'm convinced that it reduces the net Hugo support traffic.

[gerrywastaken]

So, this dump function will only be added once I'm convinced that it reduces the net Hugo support traffic.

I don't know how it would be possible to prove this without testing it. Conversely I find it difficult to imagine a scenario where

• somebody would come to the realisation that they need to check the contents of a variable
• find this page: https://gohugo.io/templates/template-debugging/
• add the printf command to their page

but then stop and not use a variable because it wasn't formatted nicely.

I imagine most would do something similar to what I did... a couple of annoying search and replace operations in my editor to add new lines after {, } and ,. Found the variable I was looking for and then used that to find the appropriate documentation in the Gohugo docs.

The obfuscation of the data didn't stop me from using the variable, it just made me wonder why it was so poorly formatted.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.