Update Output Formats documentation (v0.38) #404

kaushalmodi · 2018-03-09T17:24:51Z

Merge AFTER v0.38 release

Updates Output Formats documentation as per the change in v0.38.

bep · 2018-03-09T18:13:26Z

content/templates/output-formats.md

+By default, **all** pages will render to the `HTML` output format. Every `Page`
+also has a [`Kind`][page kinds]. Except for the `page` `Kind`, by default, all
+other *Kinds* will also render to the `RSS` output format.
+


I think the language here is a little technical.

I would suggest something in the line of: "By default, all ... HTML ... Also, every list page will, by default, render to the RSS output format."

"list page" may not be perfect, but it is easy for people to understand.

But it's clearer that way. People will anyways needs to understand Kinds to be able to configure outputs.

And also, doesn't feel right mis-documenting.. RSS, 404, etc kinda are not "list pages".. I think that's what you were inferring too.

I have attempted to make this a bit more clearer in my last force-pushed commit to this PR, while retaining the correctness.

bep · 2018-03-09T18:18:25Z

content/templates/output-formats.md

+
+{{% note %}}
+If you add an `outputs` config section, the *output format* for all the
+unspecified *Kinds* will be set to only `HTML`.


I think you take the "half-empty" approach to this. I would much prefer something in the line of:

If you add an outputs config section, you replace the Hugo default output configuration with your own and must provide a complete configuration. You will get HTML for any missing page Kind entry.

Done (this, and also the next hunk where you commented).

bep · 2018-03-09T18:19:24Z

content/templates/output-formats.md

-* The names used must match the `Name` of a defined `Output Format`.
-* Any `Kind` without a definition will default to `HTML`.
+* The output definition is per [`Page` `Kind`][page kinds] (i.e, `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`).
+* Any `Kind` not defined in this `outputs` config section will default to `HTML`.


You have already said this before.

OK, will remove it from here.

regisphilibert · 2018-03-09T20:26:25Z

Even though the .Kind home, page and section are rather obvious. I have been and saw a lot of people being confused as to what is a taxonomy page and a taxonomyTerm page. This PR is the perfect opportunity to fix that.
Following the recent exchange in this thead, I think we could add a better description to each kind along the line of the following:

home: the homepage
page: a page showing one entry
section: a page listing entries from a section
taxonomy: a page listing entries from a given taxonomy term
taxonomyTerm: a page listing the terms of a given taxonomy.

I use the word entry to avoid common confusion surrounding the word page in Hugo. But there may be a better wording.

kaushalmodi · 2018-03-09T20:54:58Z

@regisphilibert Thanks for the feedback. I have now rephrased that part taking in your input.

regisphilibert · 2018-03-09T21:42:01Z

A page listing all taxonomies under a taxonomy term

I think this wording is confusing. I'm sure not every body agrees on what a taxonomy is, but the documentation clearly states how a term relates to a taxonomy using its movie example. Following this logic:

A taxonomyTerm page lists all terms belonging to a given taxonomy.
So if the taxonomy is sport, the taxonomyTerm page of sport will list

football
baseball
tennis

While the taxonomy page of football will list every entries belonging to football.

regisphilibert · 2018-03-09T21:48:14Z

Also I believe the evocation of the layout and content file is a bit confusing as it does not always follow the naming logic of the page kinds. This is the simple approach I would recommend:

home
: The home page

page
: A page showing one entry or regular page

section
: A page listing entries from a given section

taxonomy
: A page listing entries from a given taxonomy term

taxonomyTerm
: A page listing terms from a given taxonomy

kaushalmodi · 2018-03-09T22:08:13Z

How about now?

regisphilibert · 2018-03-09T22:23:30Z

Yes :) I still have reservation about the HTML structure illustrations as not everybody goes looking under the public/ hood. But that’s just my view.

kaushalmodi · 2018-03-09T22:29:27Z

I still have reservation about the HTML structure illustrations

I didn't understand the reference.

Update: Ah OK, you mean the /index.html and other examples.. If people are getting into understanding Kinds, I would hope that those example help them associate them with actual pages.

Update 2: For ease of understanding.. may be remove the index.html part? And simply have /, /posts/, /tags/, and so on?

regisphilibert · 2018-03-10T02:03:20Z

The reason why I don't think we should make any parallel with the url structure or the content structure is that the page kind naming follows its own logic.

A page of kind section is the landing page of the said section.
A page of kind taxonomy, following the logic from above, should be the landing page of a taxonomy (listing its terms). It is not. It is the landing page of a taxonomy term (listing its pages).
A page of kind taxonomyTerm following the logic from section should be the landing page of a taxonomy term (listing its pages), it is not, it is the landing page of a taxonomy (listing its terms).

I'm afraid we risk confusing the reader or worse having him question the naming logic or the veracity of the doc itself by using exemples. I therefore support simply stating what every kind is, using the best sentence we can. I'm sure those can still be improved.

But then again, I might be wrong. Any third opinion would be welcome.

kaushalmodi · 2018-03-12T15:11:43Z

@bep Do you want to move me as a PR to hugo core, or do we just wait for v0.38 release?

bep · 2018-03-12T17:29:01Z

just wait for v0.38 release?

Wait. Less work.

kaushalmodi force-pushed the output-formats branch from 62dfcb7 to 43ab113 Compare March 9, 2018 17:44

bep reviewed Mar 9, 2018

View reviewed changes

kaushalmodi force-pushed the output-formats branch from 43ab113 to 5e60068 Compare March 9, 2018 18:51

kaushalmodi force-pushed the output-formats branch 2 times, most recently from 466ff96 to ec722c6 Compare March 9, 2018 20:54

kaushalmodi force-pushed the output-formats branch from ec722c6 to fe001f9 Compare March 9, 2018 22:08

kaushalmodi mentioned this pull request Mar 12, 2018

Update Page Kinds documentation #412

Merged

kaushalmodi changed the title ~~Update Output Formats and Page Kinds documentation~~ Update Output Formats documentation (v0.38) Mar 12, 2018

Update Output Formats

4560631

kaushalmodi force-pushed the output-formats branch from fe001f9 to 4560631 Compare March 12, 2018 15:11

bep merged commit 18114d4 into gohugoio:master Apr 2, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Output Formats documentation (v0.38) #404

Update Output Formats documentation (v0.38) #404

kaushalmodi commented Mar 9, 2018 •

edited

Loading

bep Mar 9, 2018

kaushalmodi Mar 9, 2018

kaushalmodi Mar 9, 2018

kaushalmodi Mar 9, 2018

bep Mar 9, 2018

kaushalmodi Mar 9, 2018

kaushalmodi Mar 9, 2018

bep Mar 9, 2018

kaushalmodi Mar 9, 2018

regisphilibert commented Mar 9, 2018 •

edited

Loading

kaushalmodi commented Mar 9, 2018

regisphilibert commented Mar 9, 2018 •

edited

Loading

regisphilibert commented Mar 9, 2018 •

edited

Loading

kaushalmodi commented Mar 9, 2018

regisphilibert commented Mar 9, 2018

kaushalmodi commented Mar 9, 2018 •

edited

Loading

regisphilibert commented Mar 10, 2018

kaushalmodi commented Mar 12, 2018

bep commented Mar 12, 2018

Update Output Formats documentation (v0.38) #404

Update Output Formats documentation (v0.38) #404

Conversation

kaushalmodi commented Mar 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

regisphilibert commented Mar 9, 2018 • edited Loading

kaushalmodi commented Mar 9, 2018

regisphilibert commented Mar 9, 2018 • edited Loading

regisphilibert commented Mar 9, 2018 • edited Loading

kaushalmodi commented Mar 9, 2018

regisphilibert commented Mar 9, 2018

kaushalmodi commented Mar 9, 2018 • edited Loading

regisphilibert commented Mar 10, 2018

kaushalmodi commented Mar 12, 2018

bep commented Mar 12, 2018

kaushalmodi commented Mar 9, 2018 •

edited

Loading

regisphilibert commented Mar 9, 2018 •

edited

Loading

regisphilibert commented Mar 9, 2018 •

edited

Loading

regisphilibert commented Mar 9, 2018 •

edited

Loading

kaushalmodi commented Mar 9, 2018 •

edited

Loading