Flexible control over `description` and summary usage

[tzinm]

Summary and motivation

Currently, tabi handles description field and summary with different priority depending on the context;

• In list_posts.html macro, if description is available, it is used; otherwise, it falls back to summary.

{% if post.description %}
    <p>{{ post.description | markdown(inline=true) | safe  }}</p>
{% elif post.summary %}
    <p>{{ post.summary | markdown(inline=true) | trim_end_matches(pat=".") | safe }}…</p>
{% endif %}

• In atom.xml file, if summary exists, it is used; otherwise, it falls back to description.

{% if page.summary -%}
    <summary type="html">{{ page.summary | markdown(inline=true) | safe }}…</summary>
{% elif page.description -%}
    <summary type="html">{{ page.description }}</summary>
{% endif -%}

Since feeds in tabi are visually styled but do not render markdown syntax inside the summary tag, it might make sense to encourage keeping description field free for markdown syntax, especially because it lives in the frontmatter. In that case, giving priority to description in feeds and using summary for blog post listings could offer a cleaner and more consistent experience.

Implementation details

Introduce configuration options to define the priority between description and summary, possibly with the following flexibility:

Global setting:

Introduce a global option to allow users to define whether description or summary should have priority when rendering post lists and RSS feeds.

Optional page setting:

Allow posts to optionally override the global setting via a field in their frontmatter, offering more flexibility for specific cases.

Separate configuration for posts and feeds:

Provide the ability to set different priorities depending on the context. For example, showing summary in the blog post list while preferring description in the RSS feed.

Checklist

• [x] I've searched existing issues to make sure this feature hasn't already been requested.
• [x] This feature aligns with tabi's philosophy (minimal JS, accessible…)
• [x] I'm willing to contribute to the implementation of this feature.

[welpo]

I don't like the inconsistency. To me, post.description > summary, so we should use that in both places.

I'm not sure about adding more settings. What's the use-case for different description/summary for RSS vs homepage?

[tzinm]

Adding a description field to the frontmatter (plain text, without markdown syntax) and using summary would allow making a clear distinction:

• Use the summary for the text displayed under the title on the homepage.
• Use the description for the blog feed.

Why make this distinction?

1. Thanks to one of the latest PRs that was merged, the text shown under the post title on the homepage can now render markdown.

2. On the other hand, in the feed, the content is plain text.

Therefore, if the feed displays the summary (which might contain markdown syntax), the formatting could break or some context could be lost.

<summary type="html">No tenía previsto hablar sobre este tema en la segunda entrada del blog, pero tras leer el artículo “Modelos experimentales de microblog” del blog danirod.es me apetecía compartir mi opinión al respecto…</summary>

[welpo]

Have you checked how feed readers render markdown in the descriptions?

[tzinm]

No, I haven’t been able to test it directly.

Anyway, some applications may display the Markdown summary correctly, while others don't. It depends (I think) on how they parse the content.

I've checked the parser used by Miniflux (my RSS reader), and it doesn't seem to be able to render the markdown content. I guess it would only display the special characters used in markdown syntax.

https://github.com/miniflux/v2/blob/27253c8a9758bf83fa7490550d30c31cd99e719c/internal/reader/atom/atom_10.go#L130

https://github.com/miniflux/v2/blob/27253c8a9758bf83fa7490550d30c31cd99e719c/internal/reader/atom/atom_10.go#L159-L164

[welpo]

Something to keep in mind is in the previous PR I added the option to render markdown on both description and summary.

On one hand: I think we need consistent usage/hierarchy for both atom and main page.

On the other, we could probably escape / clean text passed to the atom template (i.e. ignore markdown, and not add any signs).

Thoughts?

[tzinm]

This is how it works now ( besides the inconsistency between the home page and the feed). The displayed text, whether it's the description or the summary, is clean and free of markdown syntax when displayed in the feed.

Note that this use case may be a bit niche and not something that most tabi users will run into, but here are the two approaches I had in mind:

Keep it consistent, with no user configuration:

• If there is a description, use it both on the home page and in the feed.
• If there is no description, but there is a summary, use it in both places. In either case, make sure the feed output is clean and doesn't include markdown formatting.

Make it configurable:

Add options to the configuration so that users can choose what is displayed on the home page and what in the feed. If nothing is configured, follow the default behavior of point 1.

The easiest way is the first one. With a small change it would be resolved the consistency between the home page and the feed. It wouldn't solve the inconsistency (in the home page the markdown is rendered but not in the feed) that can be seen in the images I shared in a previous comment.

What I'm not entirely sure about (and I guess it's not really possible) is whether feed could render markdown when viewed directly (like one of the pictures shown in a previous comment), but appear as clean text when parsed by an RSS reader.

[welpo]

Let's do the first change: be consistent and always prioritise description > summary.

I wouldn't add any extra options for now. Does that sound good? Could you create a PR?

[tzinm]

It would be great to extend the functionality, but it seems fair at the moment to only make the change to be consistent with the homepage and feed.

I'll take care of creating the PR 🙂

[welpo]

Thank you.

Your main need to prioritise one over the other with a setting was the markdown parsing, or something else?

Not sure I see the benefit of adding a setting

[tzinm]

Your main need to prioritise one over the other with a setting was the markdown parsing, or something else?

Yes, it's just for visual aspects. As I had pointed out in a previous comment, it is the way to be able to selectively choose what to show on the homepage and what to show in the feed.

So, on the homepage we could display a text snippet of the blog post, while in the feed we could see what is in the description field.

But I understand that this is a feature specific to a particular use case. Most users enjoying the tabi theme probably won't be using it.

[welpo]

For your use-case, would you make the description and summary match, except one would have no markdown?

[tzinm]

For your use-case, would you make the description and summary match, except one would have no markdown?

I have considered it. But I don't think I like it.

• It duplicates the content in the description field. I would prefer to use it as a place where I explain what the blog post is about.
• Although the markdown is rendered on the home page, it's not the case in the feed. This looks a bit weird depending on what content is being shared.

[welpo]

I see.

Does that mean you've given up on the original request for this issue? Or does it mean you would write entirely different content?

[tzinm]

Not trying to be rude 😅, but I feel like we’re going in circles here. Let’s just close the issue. At least we fixed the inconsistency between the homepage and the feed 🤜🤛

[welpo]

As you wish!

I was trying to understand:

• if you intended to set the same values in description and summary to avoid RSS issues, we could look into a way to fix this (I was thinking parse markdown then strip HTML?)
• if you had an idea to set different values on each, I was curious to hear more and see if it might be worth adding the feature

I'll leave it up to you as to whether to close the issue or keep discussing :)

[tzinm]

Sorry for the delay in replying. It's been a busy week.

Exactly, the idea is that the content of the description property of the frontmatter not match the text above the <!-- more --> tag.

Why? For me, each has a different purpose.

• Description: is simply a brief overview of the entry.
• Summary: is an excerpt of the entry.

On the other hand, the behavior between the homepage and the feed is different.

• Homepage: it's a space where entries are displayed and given the space available the content displayed below the title of the entry can be larger. In addition, thanks to one of the latest improvements of the theme the content with markdown tags is displayed correctly.

• Feed: assuming that probably the value included in the description field will be shorter than the summary, it may fit better. Especially because it's the content that ends up in the RSS readers. In addition, although styles have been applied to make it human readable from the web, RSS readers don't parse the markdown tags which may be included in the description field of the atom.xml file.

Images above show the difference between the homepage and the feed. Not sure if I've been better explaining myself 😅

[welpo]

thanks to one of the latest improvements of the theme the content with markdown tags is displayed correctly

This is true of both settings

assuming that probably the value included in the description field will be shorter than the summary, it may fit better

I don't understand this. Fit better in what way?

To me both homepage and feed serve the same purpose: give an introduction/description to the topic to allow the visitor to decide whether they want to read more.

And now I'm thinking I should set full_content_in_feed = true as the default value (docs). That's the most RSS-user friendly option.

I'll close the issue for now, but happy to see other users support this or listen to arguments in favour of adding the feature.

Thanks!