Should .Site.RegularPages include custom output formats?

[Jura]

Quick question: on Hugo 0.20, I noticed that looping over .Site.RegularPages returns an array that includes custom output files too (like .json) files. Is that correct?

My understanding of the docs is different, which say that .Site.RegularPages is:

A shortcut to the regular page collection. Equivalent to where .Site.Pages “Kind” “page”.

I thought we had .Site.Pages for all rendered content (including custom outputs) and .Site.RegularPages for actual, rendered webpages.

Or are json, css, csv, and calendar files “pages” too?

[bep]

@Jura

Or are json, css, csv, and calendar files “pages” too?

The short answer is: It is if you define it to be.

But .Site.RegularPages will always (i.e. the Permalink) refer to the main output format, by default the HTML. But if you define regular pages to output both HTML and JSON, then there will be a .OutputFormats with both and .AlternativeOutputFormats with only the JSON.

[Jura]

@bep

But .Site.RegularPages will always (i.e. the Permalink) refer to the main output format, by default the HTML. But if you define regular pages to output both HTML and JSON, then there will be a .OutputFormats with both and .AlternativeOutputFormats with only the JSON

Thanks for replying. I have one custom format file, with the following front matter:

+++
date = "2017-04-11"
outputs = ["json"]
url = "search-index.json"
+++

Since I set the outputs to only "json", I think that this custom page is not defined to be a regular page? (Because I don’t do both HTML and JSON for this particular file.) Do I understand that correctly?

I’d like to get an array with only the actual HTML pages rendered by Hugo. Because I do not want the custom output formats to show up in the sitemap, RSS feed, recent article list, random article list, etc.

@bep

if you define regular pages to output both HTML and JSON, then there will be a .OutputFormats with both and .AlternativeOutputFormats with only the JSON.

Are .OutputFormats and .AlternativeOutputFormats page or template variables? I can’t find them on the docs page.

[bep]

See https://gohugo.io/extras/output-formats/#link-to-output-formats

We will update the Page part of the docs, eventually …

As to RegularPages, your JSON is a regular page, so if you don’t want it in listings, you will have to filter it out somehow.

I would also try to set slug=“search-index” instead of using the url, to test out the new media type logic.

[Jura]

@bep

your JSON is a regular page, so if you don’t want it in listings, you will have to filter it out somehow.

Is it also possible to generate a JSON file that’s not a regular page?

If I rename search-index.md to search-index.json, I see that the Hugo output after building is one less “regular pages created”. But the .json file is copied over, not processed into a custom output.

@bep

See Custom output formats | Hugo

I’m familiar with that page, but find it hard to grasp after reading it several times.

Based on your comment, the way I understand that page now is:

• Hugo takes the file suffix into consideration (table named “Media Types”).
  • But Hugo can also look at the front matter or config.toml file (section “Output Formats for your pages”).
• That file suffix (or manual configuration) influences the output format (table “Output Formats”).

With that putting a .json file in /content/ would generate a JSON file but that’s not happening.

[bep]

With that putting a .json file in /content/ would generate a JSON file but that’s not happening.

The feature is called OUTPUT FORMATS, content in /content would fall into the INPUT category.

As I wrote that documentation you struggle to understand, and I spent some time to make it as clear as possible, you will have to wait for others to chime in with an alternative way of explanation.

[Jura]

@bep

As I wrote that documentation you struggle to understand, and I spent some time to make it as clear as possible, you will have to wait for others to chime in with an alternative way of explanation.

Just for the record since you seem to read it differently than I intended: I wasn’t criticising the docs nor your efforts.

[Jura]

I know this is an old topic, but I still think the question is relevant. I have a hard time explaining why .Site.RegularPages contains custom output format pages, even when the main output format is only HTML.

Aside from the technological aspect, it also feels counterintuitive: regular pages that include custom output.

Should we do better in this area?

@bep

But .Site.RegularPages will always (i.e. the Permalink) refer to the main output format, by default the HTML.

[bep]

@Jura

I have a hard time explaining why .Site.RegularPages contains custom output format pages,

I have a hard time understanding your question. There is nothing special about the custom output formats other than the … custom part. Some people want to create their own HTML output format which uses plain text templates. It is still HTML, just slightly customized. I think it would be harder to explain to people why these somehow were left out.

[Jura]

@bep

I have a hard time understanding your question.

I think I didn’t explain myself properly, but I’m also not a native English speaker so perhaps there’s some term/meaning confusion there on my part.

I agree with you that some custom output formats should be included in .Site.RegularPages since they’re indeed “regular content pages”.

But I also see my that custom output RSS (.xml) pages are included in .Site.RegularPages (Hugo 0.40.3). I struggle to understand why RSS feeds are “regular pages”. For me they don’t really belong in there. From how I understand the word ‘regular’ it means ‘normal’ or ‘usual’. I’d say that .xml pages are special pages, not the usual type of pages.

[bep]

@Jura

I’d say that .xml pages are special pages, not the usual type of pages.

So, if I understand you correctly:

• You have a content page that has outputs = RSS only.
• This page will end up in .Site.RegularPages

I think I understand, but I’m having a little bit hard understanding the “.xml pages are special”. This is in the eye of the beholder, and not something that Hugo can decide. We could improve this somehow, but I don’t think we can remove them… That would at least be a rule that we need to put in the output format definition…

Also note that I’m not a native English speaker. I’m from Norway.

[TotallyInformation]

@bep

Also note that I’m not a native English speaker. I’m from Norway.

In my experience, Scandinavians often speak better English than English people! Yes, I’m from England.

[Jura]

@bep

if I understand you correctly:

• You have a content page that has outputs = RSS only.
• This page will end up in .Site.RegularPages

That’s true, this is my whole page:

+++
outputs = ["SectionRSS"]
url     = "/platform/rss.xml"
layout  = "section-rss"
+++

@bep

I think I understand, but I’m having a little bit hard understanding the “.xml pages are special”. This is in the eye of the beholder, and not something that Hugo can decide. We could improve this somehow , but I don’t think we can remove them…

I more or less agree with you here. It’s indeed a bit odd to say that “.xml pages are special”.

But aside from my own assumptions about the meaning of “regular” and “custom”, I see that Hugo also struggles with what ‘special’ and what ‘regular’ is.

That’s because the standard RSS feeds and the sitemap.xml both do not appear in .Site.RegularPages. But my custom .xml files do.

So standard RSS pages are not ‘regular’ (not in .Site.RegularPages), but custom output .xml files are ‘regular’ (appear in .Site.RegularPages). This is also a bit confusing to me.

@bep

That would at least be a rule that we need to put in the output format definition…

That sounds like a good idea because it isn’t code breaking for people that expect .Site.RegularPages to hold custom output pages. It also saves me from having to pre-filter all range loops to exclude the xml pages.