✨ feat: introduce a 'series of post' feature

[ZzMzaw]

Summary

This PR introduces a series of posts feature.

It tries to cover all the discussion and proposal we had in the previous one: #360.

I noticed an important PR to improve style for RTL (#381).
I did my best to respect it but as I am not used to deal with RTL, I may have introduced some regressions.

I am not very happy with the rendering of the series navigation feature which is just a copy/paste of the global one.
IMHO, result takes too much space in the page and is too hard to easily distinguish from the usual navigation.
Feel free to propose anything which would fit better as I don't have much ideas.

Articles orders is broken in a series' page when using reversed pagination (as I cannot know it using the get_section function).
I have a pending PR on zola to solve this: getzola/zola#2653.
Meanwhile, we just can put a big red warning in the documentation.
Neverthless, I am not sure pagination will be a real use case for series.

Documentation is not there yet (at least, you can look at the code :-)) but I thought using it to demonstrates some series features could be interesting.
I introduced 3 articles (some retroactively) with dummy text for that purpose. I'll make them complete soon.
Could you please let me know if it would be fine for you?

As usual, translation are missing (only English and French are here).
Others will have to be completed for sure but as I was only able to use automatic translation, I prefer to let you do those you know better.
I'll finish with automatic translation for the remaining ones.

Last but not least, I did a design choice I would like you to cross-check.
I decided to deal with elements related to a series in a page as macros to make clear that a series' section pages are not in the relevant order and we need to use a dedicated variables which has been sorted properly.
I thought it would be easier to remind for future evolution but I am not sure about this choice.
If useless, I can easily reintroduce everything in the page itself (as I did at first).

I tried to develop all features as much as I could but we can make some of them less complex if you think it doesn't worth it.
Some questions I have are:

• Should we let users define different series information depending on series' page?
• Should we seperate series' description from the section's description?
• Should we allow variables in all types of series introduction?

I hope this will allow a great series feature and I am waiting for your feedback :-)

Many thanks.

Related issue

Discussion started in #256 .

Changes

Declaring a series can be done by creating a section with extra.series set to true.
This section should be transparent.
Most of the tests have been done that way but non transparent section may work as well.

In order to reuse existing posts listing feature, I had to refactor it a bit to support not only dates but also indexes.

Serie's info displayed in a page is controlled through the variable extra.series_page_introduction in a series section and can be:

• none: nothing displayed
• list (default): a headline mentioning this page is part of a series with a link to it
• summary: a headline mentioning this page is part of a series with a link to it and a clickable list of all its articles
• custom: something completely custom

Introduction (whatever its type) supports pre-defined and user-defined variables replacement.

Accessibility

Nothing special but I tried to respect what is already done (semantic HTML, ARIA attributes and colour contrast).
Nevertheless, I don't how to test any accessibility feature on my own.

Screenshots

I propose to use the documentation as a demo of the feature.
I introduced 3 dummy articles (some retroactively).
If this is accepted, I'll update them with relevant documentation.

Type of change

• Bug fix (fixes an issue without altering functionality)
• New feature (adds non-breaking functionality)
• Breaking change (alters existing functionality)
• UI/UX improvement (enhances user interface without altering functionality)
• Refactor (improves code quality without altering functionality)
• Documentation update
• Other (please describe below)

---

Checklist

• Mention series in README, linking to post introducing them
• Ensure RTL-compatible styling
• I have verified the accessibility of my changes
• I have tested all possible scenarios for this change
• I have updated theme.toml with a sane default for the feature
• I have made corresponding changes to the documentation:
  • Updated config.toml comments
  • Updated theme.toml comments
  • Updated "Mastering tabi" post in English
  • (Optional) Updated "Mastering tabi" post in Spanish
  • (Optional) Updated "Mastering tabi" post in Catalan

[netlify]

✅ Deploy Preview for tabi-demo ready!

Name	Link
🔨 Latest commit	3c83cb2
🔍 Latest deploy log	https://app.netlify.com/sites/tabi-demo/deploys/67232af69bdd330008746270
😎 Deploy Preview	https://deploy-preview-406--tabi-demo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[welpo]

I'll take a look during the week! Thank you.

[welpo]

Thanks for the hard work!

• Should we let users define different series information depending on series' page?

I don't see a use-case for this. I like that you've added the ability to set placeholders for description and such. I think that's perfect.

Should we seperate series' description from the section's description?

You mean as it is now? With section.extra.series_page_description and the section.description? The section.description is used for metadata in the HTML and is probably helpful for SEO. I'd keep it as is.

Should we allow variables in all types of series introduction?

I prefer simple. How about we get rid of the types? It simplifies the code and documentation. We can directly use the series_page_description passed through a markdown filter. If users want a details/summary, they can add it there. They could even make it an admonition, if they wanted.

What do you think? I've made a couple of commits to render markdown on the header and description for the series.

I introduced 3 articles (some retroactively) with dummy text for that purpose

I need to think about this. I don't like the idea of having empty articles just to showcase the series. I also don't like the idea of not having anything to showcase the series on the demo. I'm thinking of alternatives:

• Turn some existing posts into a series
• Create some new ones
• Link to another website using tabi series as a real example

This is not a priority, though.

IMHO, result takes too much space in the page and is too hard to easily distinguish from the usual navigation.

I'd lean towards using 100% the exact same navigation as the rest of the site (blog/main page). More cohesive, more maintainable, hopefully clearer for the visitors.

Perhaps the only change I'd make is regarding the number/indexing instead/in addition to the date.

RTL

I'll take a look before merge.

I decided to deal with elements related to a series in a page as macros to make clear that a series' section pages are not in the relevant order and we need to use a dedicated variables which has been sorted properly.

Perfect.

[ZzMzaw]

Many thanks for your review.

Should we let users define different series information depending on series' page?

I don't see a use-case for this. I like that you've added the ability to set placeholders for description and such. I think that's perfect.

Agreed.
I'll change the setting configuration to ignore the page and only take config or the series section into account.
There is no need to change anything if we get rid of types.

Should we seperate series' description from the section's description?

You mean as it is now?

Yes.

With section.extra.series_page_description and the section.description? The section.description is used for metadata in the HTML and is probably helpful for SEO. I'd keep it as is.

Agreed.

Should we allow variables in all types of series introduction?

How about we get rid of the types?

I thought it would help to have a way to quickly setup the feature with default choices without having to think about how to structure the introduction on your own.
The only difference I see if we remove the types is that you won't be able to configure it once for the entire website in config.toml (when not using custom for sure). You'll have to repeat it for each series.
Nevertheless, I am not sure it is a big deal and it could be easily compensated with some real examples in the documentation.
The only point I want to check is if we'll be able to reproduce the 'none' type.
I'll look into it and propose an update.

Documentation

I need to think about this. I don't like the idea of having empty articles just to showcase the series. I also don't like the idea of not having anything to showcase the series on the demo.

Sorry, I was unclear. I want to use those articles to document the series feature in tabi's website but I didn't had time to write documentation yet.
I though 3 articles would be enough so I just created them as placeholders.
For sure, we'll also update 'Mastering tabi' but the global configuration is not the most important for this feature and describing everything here would be too much IMHO.
Based on our current discussion, I would propose the 3 following articles:

1. An article explaining how does the series feature works in tabi with all the variables
2. An article explaining how to order series' pages in a series (as there are several ways to achieve the same result but with different benefits)
3. An article giving concrete configuration examples associated with screenshots of the result (to replace the types as mentioned above) and clarify how the feature can be used for real

Navigation

I'd lean towards using 100% the exact same navigation as the rest of the site (blog/main page). More cohesive, more maintainable, hopefully clearer for the visitors.

Sorry, I was unclear once again and I am not sure we are speaking about the same thing.

I was not mentioning the navigation in the series' section. I completely agree with you on the fact it is fine as it is, in line with the blog/main page navigation.
Having both indexes and dates is only possible through code for now but we definitely could make it a configuration if you think it can be useful.

I was referring to the navigation at the bottom of a series' page.

I feel it is a bit confusing to have two exact same navigation elements on top of each other.
Maybe integrating the two may be better but I am really unsure what would fit best in terms of design.

RTL

I'll take a look before merge.

Many thanks

[welpo]

I've pushed a commit to simplify the style and make it more in line with the rest of the theme.

Before

After

---

Reasoning for the changes:

• If a tabi user anticipates a very long description (thought I'd assume this is a rare case), they can link to the posts themselves within the section text. We can add an admonition tip on the docs regarding the #posts-list id.
• I feel like the SERIES label is redundant. The series text (section content) will (or should) describe what the end user is seeing. It looked a bit cluttered to me.
• The "Series posts:" felt redundant too.
• Made the text take up the whole width, as with the rest of non-article sections
• Overall, this makes the theme more maintainable: less i18n strings, less CSS, simpler template code.

Having said that, I am open to reverting changes and modify further. This is just a quick attempt to increase cohesion with the rest of the theme. I'm open to feedback.

[ZzMzaw]

If a tabi user anticipates a very long description (thought I'd assume this is a rare case), they can link to the posts themselves within the section text. We can add an admonition tip on the docs regarding the #posts-list id.

As for types, it is just how much effort it will take to have consistent series across the website.
I see the series page content as an article putting the series in its context without having to put it in the first article of the series.
If we consider the series as a film, the series page content could be a kind of mix between a synopsis and a making of.
This may be why I anticipate on very long description most of the time.
I see a series as both a section and an article.

An optional "jump to post" button may be useful as a per-series configuration.
It definitely can be put back in the text itself with good documentation.
Nevertheless, I don't manage to figure out how much the result will feel as a workaround instead of being fully integrated with the theme.
I need to test it a bit to see what could be the final result.

I feel like the SERIES label is redundant. The series text (section content) will (or should) describe what the end user is seeing. It looked a bit cluttered to me.

Agreed

The "Series posts:" felt redundant too.

As a series description may be a full article, it might be a bit blurry where the article ends and where the posts' list starts.
If could be compensated by adding a manual <hr> at the end of the article but this may not work every time.
As an example, if using footnotes in the series' content, it might not be possible to add anything between the end of the article and the beginning of the posts' list.
An optional "Series posts:" separation may be useful as a per-series configuration but I don't know how much it is something generic or just linked to my personal usage of the feature.
I'll test this as well to see if I can accommodate it.

Made the text take up the whole width, as with the rest of non-article sections

Agreed

Overall, this makes the theme more maintainable: less i18n strings, less CSS, simpler template code.

Agreed

[ZzMzaw]

I just removed the types of introduction.
Introduction will be displayed only if there is an introduction defined.
If not defined (or empty), it will have the same result than the previous 'none' introduction type.

[welpo]

The only difference I see if we remove the types is that you won't be able to configure it once for the entire website in config.toml (when not using custom for sure). You'll have to repeat it for each series.

Is this still the case? Could we leverage the hierarchy to solve this?

Based on our current discussion, I would propose the 3 following articles:

I understand the goal of the articles is to (1) document the feature and (2) showcase it.

(1): I believe the feature documentation should be in one spot (max two, with a mention in Mastering tabi + its own post, if necessary) to avoid making users jump around.

(2): This is where I think it might be a good idea to use a real website using tabi with the feature. I know I would implement it on my own site, for example. The goal is to not clutter the tabi demo with too many posts and to show a functional example.

I feel it is a bit confusing to have two exact same navigation elements on top of each other.

Ah! Absolutely. Agreed. I'm not sure how to solve this. Having both is definitely ugly and confusing, even with the (Series) label. My initial thought is to have only one such section, defaulting to serie's posts. This could be overriden with a config. I'm not too sure this is the best approach, though.

This may be why I anticipate on very long description most of the time.

I understand. It makes sense.

Nevertheless, I don't manage to figure out how much the result will feel as a workaround instead of being fully integrated with the theme.

Yeah, this was my main concern. I'm not at all sure what the expectations would be for someone visiting a serie's main page. For now I'm leaning for an admonition tip on the docs similar to:

Tip

You can add a link to jump to the posts by adding a link to the anchor #posts-list. For example: [Jump to the posts](#posts-list).

I'm definitely open to alternatives, though.

As a series description may be a full article, it might be a bit blurry where the article ends and where the posts' list starts.

Fair point. What do you think about using the already existing i18n string all_posts (i.e. "All posts")? This, with the appropriate header level (3, I think?) + the bottom-divider class for an underline.

[ZzMzaw]

Is this still the case? Could we leverage the hierarchy to solve this?

It is not the case anymore.
Simplifying introduction makes it easy to define in config.toml even if defining it in the series section may remain the preferred solution.
So far, defining the series introduction in the config.toml doesn't work (sorry, my previous test was incorrect...).
Anyway, after thinking about it twice, I am not sure it is required.
We should encourage having the series introduction aligned with the series section content so it makes sense to have it defined in the series section itself.
Do you think we should support the definition in config.toml?

I understand the goal of the articles is to (1) document the feature and (2) showcase it.

Yes, exactly.
OK, let's keep tabi website simple and link to other websites for demo. I'll implement the series feature as well for sure.
Would you like to keep "Mastering tabi" the last post which means we can add the series documentation just before?
Or do you to respect chronology and add the series documentation just after?
Once decided, I'll regroup all the documentation in one post.

Ah! Absolutely. Agreed. I'm not sure how to solve this. Having both is definitely ugly and confusing, even with the (Series) label. My initial thought is to have only one such section, defaulting to serie's posts. This could be overriden with a config. I'm not too sure this is the best approach, though.

I completely agree it is ugly as it is today. I didn't invested much in design because I was not sure how to deal with it properly as well.
Nevertheless, either we should have the two navigations (with a good design making it better integrated) or we should only have the global navigation.
IMHO, switching the global navigation to a series navigation only for series will be confusing and will break the flow of those who just want to switch from one article to another.
In the case of series, you can still put a clickable list of series articles in the introduction which would make navigation still easily accessible.

Yeah, this was my main concern. I'm not at all sure what the expectations would be for someone visiting a serie's main page. For now I'm leaning for an admonition tip on the docs similar to: ...

I had no time to test it yet. I'll give it a try and keep you posted.

Fair point. What do you think about using the already existing i18n string all_posts (i.e. "All posts")? This, with the appropriate header level (3, I think?) + the bottom-divider class for an underline.

Looks good. I'll implement it as soon as possible.

[ZzMzaw]

Do you think we should support the definition in config.toml?

If we enable setting introduction in config.toml, it will become complex to manage translations.
This would work only for single language websites which would defeat internationalisation capabilites of tabi.
I would be more in favor of forcing the introduction in the series section itself and not supporting hierarchy.

Yeah, this was my main concern. I'm not at all sure what the expectations would be for someone visiting a serie's main page. For now I'm leaning for an admonition tip on the docs similar to: ...

I had no time to test it yet. I'll give it a try and keep you posted.

I took some time to test the proposed solution and [Jump to the posts](#posts-list) failed with following error:

Error: Found 1 broken internal anchor link(s)
  1. The anchor in the link `@/posts/testseries/_index.md#posts-list` in /home/user/testsite/content/posts/testseries/_index.md does not exist.

Using raw HTML will prevent anchor link verification and following snippet works: <a href="#posts-list">Jump to the posts</a>.

For my personal use-case, I can definitely live with: <div class="jump-to-posts"><a href="#posts-list">Jump to the posts</a></div> repeated in all of my series and associated with the following class definition in a custom CSS file (as we have to introduce a custom CSS for styling the introduction anyway):

.jump-to-posts {
    text-align: end;
}

The result looks fine:

Fair point. What do you think about using the already existing i18n string all_posts (i.e. "All posts")? This, with the appropriate header level (3, I think?) + the bottom-divider class for an underline.

Looks good. I'll implement it as soon as possible.

It has been implemented with h2 (as there is only the title above which is h1).
Tell me if you want to use h3 instead.

The result looks fine as well:

I'll focus on documentation until we decide if series navigation worth it (or figure out a better design).

Keep you posted as soon as possible.

[welpo]

I would be more in favor of forcing the introduction in the series section itself and not supporting hierarchy.

Perfect.

It has been implemented with h2 (as there is only the title above which is h1).
Tell me if you want to use h3 instead.

Perfect as is.

the proposed solution and [Jump to the posts](#posts-list) failed

The solution is not too user-friendly (though I guess people could copy-paste). I'll try to think of solutions this week.

until we decide if series navigation worth it (or figure out a better design).

I'll focus on this too. I hope to have some ideas before Friday.

[ZzMzaw]

Thanks for your feedback.
I just share my thought if it can be useful for you.

The solution is not too user-friendly (though I guess people could copy-paste). I'll try to think of solutions this week.

I can see 3 ways to manage complexity here:

1. Put back a configuration to show the jump to posts link on series (property should follow hierarchy similar to what was initally proposed)
2. Add a variable to use in the series introduction but I am not sure how to easily manage style
3. Propose a shortcode but once again, how to easily manage style (and it may be meaningless in other contexts)

until we decide if series navigation worth it (or figure out a better design).

(edited to explain better the idea)
We could think about adding variables for next and previous series posts to be used in a series' page introduction.
This would let users manage how they want to navigate within the series on their own in a textual way (e.g. "This series continues with <next_article_title_link>."). Nevertheless, I am not sure how to deal with variables presence as we won't always have a previous or next page for the series.
As you can already have a list of all the pages in the introduction (so navigation is easy from there), we could also imagine to add an outro similar to the series' page introduction but displayed at the bottom of the page.
If we do some, we could manage previous/next page presence by letting user defining several outro (one generic, one for previous_only, one for next_only and one for both).

[welpo]

I've added back the jump to posts:

I've documented the feature on the cheatsheet article. It's visible on the PR demo here (forced to true).

In short: it's shown by default with descriptions of over 2000 characters. Can be set in config or section, following hierarchy.

[welpo]

we could also imagine to add an outro similar to the series' page introduction but displayed at the bottom of the page

Yeah, I like this idea. I'm thinking of how to implement this. We definitely need to account for no next/previous posts and make it user friendly to edit, without being overwhelming. Working on it!

[welpo]

My last push:

• Add templating for outro, similar/extended from intro code. Docs.
• Renames series_page_introduction_placeholders to series_template_placeholders
• Removes show_previous_next_series_article_links in favour of outro templates
• Docs for variables

Would love your feedback!

And one question: is it possible right now to have the series sort by date, and have the same sorting as the current demo? (i.e. from oldest to most recent, instead of newest->oldest, like in the main page) That would be my ideal setup, but I don't think it's possible right now (though also not hard to add).

[ZzMzaw]

Would love your feedback!

This is awesome. You just moved the feature to the next level.

is it possible right now to have the series sort by date, and have the same sorting as the current demo?

Right now, it is not possible. When not paginated, reversing pages order is programmatic (using the reverse filter) and when paginated, the information is for now only available in the section itself. This means the order will be good when displaying the series itself but when in a series' page, order will be incorrect.
Nevertheless, this should be achievable with the next release of Zola.
I made a small contribution to make pagination info available in a section's page as well which will allow us to sort series' pages the right way.
In that case, setting pagination to 99999 and reverse it should do the job.

Regarding series pages sorting, I find slug interesting with page names starting with numbers 01-xxx, 02-yyy, 03-zzz, ...
The advantage is that the generated path will completely match the principle of the series: series-name/01-xxx, ...
Using weight may work as well by incrementing it with each page.
Whatever sorting you choose for the series, it will be ignored by the section above.

---

One question on my side:
I thought about adding an unimplemented class "series-pages-list" on the ol tag of $SERIES_PAGES_OLIST and on the ul tag of $SERIES_PAGES_OLIST to help styling effortlessly.
I also thought about adding "series-page-previous", "series-page-next" and "series-page-current" on the li tags for the same reason.
Do you think it would be worth it?

---

It looks like the only remaining work is to transform the series into a single page and describe how to sorts pages and, if agree, how to style templates.
I'll try to take care of it by the end of next week if it is not to late.
Otherwise, no problem if you want to handle it by then.

Many thanks.

[ZzMzaw]

I just merged the documentation in a single page in its current state.
There are still a few elements missing (styling and some other properties).

I put it in a page just before Mastering Tabi (which has to be updated as well) but please let me know if you prefer to have it at the end.

I'll continue on documentation as soon as I have some time.

[ZzMzaw]

Documentation might be almost ready.
We just need to decide if we want to add a few CSS classes as proposed above and if we want to move the series article after 'Mastering tabi' (which has been updated as well but only in English).
We also need to take a few captures but I am not sure I have anything to take screenshot other than png files for now.

I did some clean up on remaining elements of removed features and useless articles and I also resolved the conflict with the main branch.

This PR is almost ready for review.