New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RSS description tag should contain hugo .summary #3219

Merged
merged 1 commit into from Mar 25, 2017
Jump to file or symbol
Failed to load files and symbols.
+1 −1
Diff settings

Always

Just for now

RSS description tag should contain hugo .summary

  • Loading branch information...
DarwinJS committed Mar 22, 2017
commit e4c7d572b7b14250c05d5109ca6d2fd67a542e28
@@ -84,7 +84,7 @@ func (t *GoHTMLTemplate) EmbedTemplates() {
<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
{{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
<guid>{{ .Permalink }}</guid>
<description>{{ .Content | html }}</description>
<description>{{ .Summary | html }}</description>

This comment has been minimized.

@rdwatters

rdwatters Mar 23, 2017

Contributor

@DarwinJS Seems the description page variable with a default summary value makes more sense since it provides the user more control.

{{ .Description | default .Summary | html }}
@rdwatters

rdwatters Mar 23, 2017

Contributor

@DarwinJS Seems the description page variable with a default summary value makes more sense since it provides the user more control.

{{ .Description | default .Summary | html }}

This comment has been minimized.

@bep

bep Mar 23, 2017

Member
  1. The description is something completely different and would be a pretty breaking change.
  2. This PR is itself a breaking change and, while agree it is a good thing, we should not just merge it without thought.
@bep

bep Mar 23, 2017

Member
  1. The description is something completely different and would be a pretty breaking change.
  2. This PR is itself a breaking change and, while agree it is a good thing, we should not just merge it without thought.

This comment has been minimized.

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - that is a nuance of Hugo that I am not aware of. I would go with whatever is considered best by PR reviewers.

@rdwatters - could you explain a bit more about your modification - I am curious.

All I know is that RSS feeds don't generally include entire articles in a feed, but rather a summary the norm.

@bep - perhaps hugo should take parameter like "contentofRSSdescription" that would default to the current, full post body and can be configured as "contentofRSSdescription=summary" ? Although it still doesn't seem like the default behavior should be full body, this might be more discoverable than what I had to do.

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - that is a nuance of Hugo that I am not aware of. I would go with whatever is considered best by PR reviewers.

@rdwatters - could you explain a bit more about your modification - I am curious.

All I know is that RSS feeds don't generally include entire articles in a feed, but rather a summary the norm.

@bep - perhaps hugo should take parameter like "contentofRSSdescription" that would default to the current, full post body and can be configured as "contentofRSSdescription=summary" ? Although it still doesn't seem like the default behavior should be full body, this might be more discoverable than what I had to do.

This comment has been minimized.

@rdwatters

rdwatters Mar 23, 2017

Contributor

@DarwinJS Sure thing. I think the problem is the terms we are using, and I apologize for any confusion.

tl;dr

  1. Hugo .Summary == "lead"
  2. Hugo .Description == user-defined summary of content (e.g., synopsis or meta description)
  3. .Content is part of Atom and not RSS

Explanation

The .Summary in Hugo is really a "lead" in publishing. So, a first paragraph or specific word count could be a summary of the article, but I think this assumes too much from authors in the context of Rich Site Summaries (now, usually, Really Simple Syndication). The summaries Hugo automatically generates are really excerpts or extracts. This point has been called out more specifically in the new Hugo docs in hopes of making this clearer, but please provide feedback if you think of other improvements! 😄

A description is a more focused and deliberate paragraph of text that does in fact summarize the full content of the page, although—I'm guessing—the way it was originally intended in Hugo was in the case of meta descriptions, which serve the same purpose but are usually <160 characters as a matter of convention and SEO considerations.

As far as the RSS <description> tag containing the full-length .Content, this is a case of confusing RSS with Atom, which allows for an optional summary or full content. RSS actually requires this field. Here is an excellent resource from Harvard on the RSS spec. NB, <description> in RSS can either mean "channel description" or "item synopsis" depending on it's location in the feed.

My logic is that .Description => .Summary follows a model of deliberate usage/override => sane default, which I think dovetails with the mental model of Hugo's other conventions, but @bep makes a good point about this being a major change from what we've had before. However, I'm not sure how it's "breaking." Can you expand, @bep?

HTH.

P.S. In case you are asking about the default syntax specifically, and excuse me if you know this, but I love this function and feel like it's underused: you can see the docs on it here.

@rdwatters

rdwatters Mar 23, 2017

Contributor

@DarwinJS Sure thing. I think the problem is the terms we are using, and I apologize for any confusion.

tl;dr

  1. Hugo .Summary == "lead"
  2. Hugo .Description == user-defined summary of content (e.g., synopsis or meta description)
  3. .Content is part of Atom and not RSS

Explanation

The .Summary in Hugo is really a "lead" in publishing. So, a first paragraph or specific word count could be a summary of the article, but I think this assumes too much from authors in the context of Rich Site Summaries (now, usually, Really Simple Syndication). The summaries Hugo automatically generates are really excerpts or extracts. This point has been called out more specifically in the new Hugo docs in hopes of making this clearer, but please provide feedback if you think of other improvements! 😄

A description is a more focused and deliberate paragraph of text that does in fact summarize the full content of the page, although—I'm guessing—the way it was originally intended in Hugo was in the case of meta descriptions, which serve the same purpose but are usually <160 characters as a matter of convention and SEO considerations.

As far as the RSS <description> tag containing the full-length .Content, this is a case of confusing RSS with Atom, which allows for an optional summary or full content. RSS actually requires this field. Here is an excellent resource from Harvard on the RSS spec. NB, <description> in RSS can either mean "channel description" or "item synopsis" depending on it's location in the feed.

My logic is that .Description => .Summary follows a model of deliberate usage/override => sane default, which I think dovetails with the mental model of Hugo's other conventions, but @bep makes a good point about this being a major change from what we've had before. However, I'm not sure how it's "breaking." Can you expand, @bep?

HTH.

P.S. In case you are asking about the default syntax specifically, and excuse me if you know this, but I love this function and feel like it's underused: you can see the docs on it here.

This comment has been minimized.

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - that's a rocking explanation - I'm going to update my custom rss template!

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - that's a rocking explanation - I'm going to update my custom rss template!

This comment has been minimized.

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - question regarding best implementation on my setup - should I run a custom template for mailchimp only and leave the system default as is?

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - question regarding best implementation on my setup - should I run a custom template for mailchimp only and leave the system default as is?

This comment has been minimized.

@bep

bep Mar 23, 2017

Member

@digitalcraftsman you decide this.

@bep

bep Mar 23, 2017

Member

@digitalcraftsman you decide this.

This comment has been minimized.

@rdwatters

rdwatters Mar 23, 2017

Contributor

@DarwinJS I'm at a loss on that one man, haha. I don't actually use MailChimp, but FWIW, I don't think it should be up to mailchimp to redefine the spec. Let's see what @digitalcraftsman says about it and go from there. BTW, thanks for submitting this PR; I hadn't ever looked at the built-in template.

@rdwatters

rdwatters Mar 23, 2017

Contributor

@DarwinJS I'm at a loss on that one man, haha. I don't actually use MailChimp, but FWIW, I don't think it should be up to mailchimp to redefine the spec. Let's see what @digitalcraftsman says about it and go from there. BTW, thanks for submitting this PR; I hadn't ever looked at the built-in template.

This comment has been minimized.

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - I guess I'm functioning under the assumption MailChimp has picked the broadest compatibility option since they are integrated to by many services? Not sure if you had a chance to actually look at their page?

Thanks for all the help.

@DarwinJS

DarwinJS Mar 23, 2017

Contributor

@rdwatters - I guess I'm functioning under the assumption MailChimp has picked the broadest compatibility option since they are integrated to by many services? Not sure if you had a chance to actually look at their page?

Thanks for all the help.

This comment has been minimized.

@digitalcraftsman

digitalcraftsman Mar 24, 2017

Member

Even if the Atom spec allows the usage of the full content I think the original intention of RSS is to deliver a sneak-peak for content I subscribed to. Hence the usage of .Summary as replacement makes sense. Many themes just show the summary on the homepage as well.

@digitalcraftsman

digitalcraftsman Mar 24, 2017

Member

Even if the Atom spec allows the usage of the full content I think the original intention of RSS is to deliver a sneak-peak for content I subscribed to. Hence the usage of .Summary as replacement makes sense. Many themes just show the summary on the homepage as well.

This comment has been minimized.

@bep

bep Mar 25, 2017

Member

Agree. But I think @rdwatters is right about the Description | Summary. I'm not sure how many uses that actively. But I think we'll start with this one.

@bep

bep Mar 25, 2017

Member

Agree. But I think @rdwatters is right about the Description | Summary. I'm not sure how many uses that actively. But I think we'll start with this one.

This comment has been minimized.

@irl

irl Sep 30, 2017

This change has broken blog aggregators that expect the full content to be available in the feed. See for example any of the feeds syndicated by:

I could give more examples.

@irl

irl Sep 30, 2017

This change has broken blog aggregators that expect the full content to be available in the feed. See for example any of the feeds syndicated by:

I could give more examples.

This comment has been minimized.

@irl

irl Sep 30, 2017

For anyone stumbling across this from Google and looking for a workaround, I have published a fix on my blog at https://iain.learmonth.me/blog/2017/2017w396/

@irl

irl Sep 30, 2017

For anyone stumbling across this from Google and looking for a workaround, I have published a fix on my blog at https://iain.learmonth.me/blog/2017/2017w396/

</item>
{{ end }}
</channel>
ProTip! Use n and p to navigate between commits in a pull request.