Adding <summary> support

[jpawlowski]

This will add summary support.

• summary text may come from $Page.description or $Page.summary
• subtitle will be added to the content or summary text when appropriate and if available
• a localized text Read more ... will be added when only the summary text will show up (Allow excerpt/read more #2 )
• if summary and content is both there, both of it will be included
• a page parameter .disable_feed_content may be set to enforce truncating the text. Didn't want to introduce this on site level yet (it came too me just now ;-))

[kaushalmodi]

Do we want to include both summary and content?

https://tools.ietf.org/html/rfc4287#section-4.1.2

The spec says that summary is used when content is not present as text.

---

if summary and content is both there, both of it will be included

This will always be the case if .Description is nil. I believe, Hugo sets the .Summary internally automatically if .Content is present. So if the user does not set the description front-matter var, but has some content (this is a common combination), .Summary and .Content both will be non-empty.

[kaushalmodi]

a page parameter .disable_feed_content may be set to enforce truncating the text

What is the use case of this?

[kaushalmodi]

subtitle will be added to the content or summary text when appropriate and if available

I think this is unnecessary complication.

subtitle is a custom parameter probably used by a theme. Why are we looking for it?

[kaushalmodi]

About "Read More", as I mentioned in #2 (comment),

I am a believer of not have to redirect the user just to see the full content (to be further spammed by ads, unnecessary JS, etc.), when the feed itself has the ability to show the full content.

About the summary vs content, I only plan to include the summary tag if .Content is empty. Otherwise we include the content tag and not summary. It's quite simple and elegant that way.

[jpawlowski]

Do we want to include both summary and content?

In my opinion: yes.
You have to distinguish between the spec and what feed readers actually do. From a logical perspective, it is unlikely to assume that any feed reader would simply concatenate summary and content text into a continuous text. They will likely just ignore summary or use it for the index view instead of generating their own summary.

From RSS Best Practices Profile (which I consider to apply for any web feed):

When an item contains both elements, six of the eight aggregators display content:encoded and ignore description. FeedDemon displays the element defined last within the item element and Firefox 2.0 doesn't support descriptions.

Publishers who don't want to employ item summaries in their feeds SHOULD use the description element for an item's full content rather than content:encoded because it has the widest support.

Publishers who employ summaries SHOULD store the summary in description and the full content in content:encoded, ordering description first within the item. On items with no summary, the full content SHOULD be stored in description.

It is a summary, not an introduction text. That's something for content creators to consider.
We could have a site configuration parameter though.

a page parameter .disable_feed_content may be set to enforce truncating the text

What is the use case of this?

If for whatever reason you don't want to fully exclude a page from the feed but need to guide people to the webpage, this is what it is for. There can be many valid use cases, depending on the used theme. Maybe the content cannot be shown properly in a feed reader, may happen easily for mathematical texts I suppose (basically any content that uses additional plugins to render and is not pure markdown).

subtitle will be added to the content or summary text when appropriate and if available

I think this is unnecessary complication.

subtitle is a custom parameter probably used by a theme. Why are we looking for it?

It might be a custom parameter but is still something fairly common. Maybe it is a European thing but it is really something I use a lot and the story is incomplete without it being visible. I would say it is common practice by professional magazine writers as well (successfully transferred from the legacy press world to the digital world).
If someone is not using it, it will not have any impact.

About "Read More", as I mentioned in #2 (comment),

I am a believer of not have to redirect the user just to see the full content (to be further spammed by ads, unnecessary JS, etc.), when the feed itself has the ability to show the full content.

I don't really want to feed on the war of opinions about this, it doesn't really help. I am also a fan to let the reader and also content creator making a choice - both will and do find ways anyway to have it their way. If creators want to shorten something, it is nothing that you as a person can effectively prevent. And it is actually pretty hard to read long texts in a feed reader because they can only provide very limited formatting. Rich HTML with CSS and with a UX that someone had thoroughly thought through is there for a reason, you don't put plain text on your website, do you? ;-)
I do also think that the target audience here is usually not a content creator that produces dozens or hundreds of pages per day or month. For me personally, I don't have a big problem if there is a feed with a new article every couple of weeks and I need to do one more click to open the full content. Sometimes it is even easier if there was just a summary that someone explicitly wrote to get a quick understand about the content and to quickly decide to skip it or not.
Not everyone has in mind to track on me or make money, there can be other valid reasons to not provide the full content, also for non-commercial bloggers. And those small little pro bloggers who may earn little money from showing me an ad that my ad blocker had not filtered may deserve a few cents in return for providing me free content. There is no such think as an evil media corporation per se.

That being said, I vote to let the choice with the people. Default setting should be the full package but if someone wants to customize it and we can technically implement this (and it is now here already), I see no benefit to fight the religious war.

About the summary vs content, I only plan to include the summary tag if .Content is empty. Otherwise we include the content tag and not summary. It's quite simple and elegant that way.

Make it configurable. I disagree and would like to have the option.
I believe we both have no long term experience so we cannot even foresee if there can't be any benefit or not. I imagine there can be great benefits if a feed reader was clever enough to show me the tailored summary text instead of just the first 100 characters or so of the full content that will not give me any real benefit to understand what the post is about. In those cases, I see myself to open the full view very often but that's basically because the automated preview and summary sucks.

Concerning the automated .summary fill of Hugo: I noticed that but don't think it is an actual issue because it is just the same that most feed reader also do when generating their index view.

[kaushalmodi]

Default setting should be the full package but if someone wants to customize it and we can technically implement this (and it is now here already), I see no benefit to fight the religious war.

OK .. talking about subtitle, Hugo already has inbuild description.. aren't they essentially for the same purpose? European or not, I use description heavily (in each post), something like this:

title = "How do I write \"Org mode\"?"
author = ["Kaushal Modi"]
description = """
  You write it just like that in the title --- "Org" with capital "O",
  and then lower-case "mode" separated by a space.
  """

So why cannot we do the below to set that $description in the template?

• Check for .Description
  • If that is not available, use .Param "subtitle"
    • If even that is not available, use .Summary

Using the {{ if ne "" $subtitle }} everywhere in this PR is making the logic unnecessary complex.

The description parameter is internally supported, and the custom parameter subtitle seems to serve the same purpose, so why not set that $description with that? How do you distinguish the subtitle from description?

[kaushalmodi]

Looks like we need to put more thought into the spec of feature before implementing it..

Here's the first hasty draft.

Going back to the feed map, may be it can contain these in the site config or page config, where the page config of course get the precendence. The feed config map will be fetched using .Param "feed" (it will fetch the "feed" map from the page front-matter if available, else it will try to get it from site config)

[feed]
  summary = "yes" # other values "no", "auto"
  content = "yes" # other values "no"

summary and content

• summary

  • "auto" - output only if content is empty
  • "no" - don't output, period.
  • "yes" - output it if available (even if content is non-empty)

• content

  • "yes" - output it if available
  • "no" - don't output, period.

read more

• if content is not empty, and
• if summary is output, append summary with the read more link

no point putting read more link if content is empty

---

Then finally, based on the internal $summary and $content variable we simply insert the summary and content tags if they are non-nil.. that way we do not need so much nested if/else logic.

[kaushalmodi]

Now where should the .Description/subtitle/.Summary go?
What will go as part of content and what will go as part of the summary?

I believe..

• .Description/subtitle gets set as $description.
• The $description gets prefixed at the top of .Content in blockquotes in the content tag (if .Content is non-empty.
• If $description is non-empty, summary tag gets the same, else it gets .Summary.

Does that sound right?

[jpawlowski]

Default setting should be the full package but if someone wants to customize it and we can technically implement this (and it is now here already), I see no benefit to fight the religious war.

OK .. talking about subtitle, Hugo already has inbuild description.. aren't they essentially for the same purpose?

A description and a subtitle are really not the same thing.
It is kind of an alternate title and might give just a little more description of the main title or extend this a bit. It is absolutely not related to the article content as such.
I believe you're not using the built-in description variable properly in your self-produced theme.

Hugo's doc is very vague about what the description variable is about:

the description for the page.

I assume that is the reason way the themes I was looking at never make use of it and instead use a custom variable named summary or abstract (sometimes using both for different page types, because they make a difference between the author's page summary and an abstract about linked external content). So my conclusion as I write this response, I might consider to not even use the summary and description variables interchangeably.

They way you are using the description variable seems to be like an introduction first paragraph of your text. Not sure this was the original intention of that variable but considering that you had put it in front of your actual content part, this is likely what it is for you.

So why cannot we do the below to set that $description in the template?

• Check for .Description

  • If that is not available, use .Param "subtitle"

    • If even that is not available, use .Summary

Because they don't share the same semantics. A subtitle is definitely not a summary of a complete text.

Maybe your confusion is coming from my idea to try to always put "something" into the feed's content area instead of leaving it entirely blank in case there is no content for that page. In that case, one should take the summary, if that's not available too let's then assume that a subtitle may at least give some more info if the author decided to have it visible besides the main title. It is actually pretty easy. Believe me, I put some brainpower in what I am pull-requesting here ;-)

Now where should the .Description/subtitle/.Summary go?
What will go as part of content and what will go as part of the summary?

I believe..

• .Description/subtitle gets set as $description.
• The $description gets prefixed at the top of .Content in blockquotes in the content tag (if .Content is non-empty.
• If $description is non-empty, summary tag gets the same, else it gets .Summary.

A blockquote is not the right thing to begin a text with, unless you are actually quoting something or someone. That's not what a summary does nor what a description is about.
If you insert something in front of the content, the HTML formatting should depend on what it actually is. A subtitle requires <h2></h2>, an introduction text might be good to have in regular font size but bold text. However, if there is only the subtitle present because no summary or content is available to the feed, this will look sluggish so no additional formatting would be best, in particular because in that case we will have the "Continue to read" link being added at the very end as well.
This is all what's considered already in my proposed code.

It is actually really hard to repeat programming code in natural language once again, it is very time consuming. We should use the "comment at code" function of Github, it will be much more helpful.

[kaushalmodi]

@jpawlowski Hello, I'll will eventually merge your 4 standing PR's gradually this week. I'm trying to find time to get to these.

[stefanv]

I'm sending out a gentle ping to see whether there's still interest in bringing some of this work into the fold.