✅ Deploy Preview for tabi-demo ready!

Name	Link
🔨 Latest commit	2749def
🔍 Latest deploy log	https://app.netlify.com/sites/tabi-demo/deploys/672d4232467e080007017012
😎 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.

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

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.

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

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.

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

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.

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:

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.

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.

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.

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.

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).

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.

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!

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).

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.

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.

Almost done!

I want to review all the code, including RTL-compatible styling (Done!)

I changed the publication date to this Friday 8th of November. Feeling optimistic :)

After some minor refactoring, I think this is ready to merge. The "pinned post" feature will come soon.

Thanks a ton for the hard work, @ZzMzaw! Thanks for the review, @TheAwiteb. And thanks for the early feedback, @stalkerGH!

Hi @welpo and @ZzMzaw Thank you for implementing series feature. That's great news, I was expecting them. My website has several articles meant as chapters so series feature is more than welcome (announced 'pinned post' too!). I'd like to ask when it will be packed to new release (3.x.x)?

I'd like to ask when it will be packed to new release (3.x.x)?

Should be 3.1.0. Probably coming on Monday, after I merge #424 and fix a styling issue regarding post metadata and mobile view :)

I'm trying to use series. I already know how to set up the page in general. I would like to highlight that a post is part of a series, perhaps by giving it an admonition or a box. How do I do that?

Would the series_intro_template work for you?

You can't call shortcodes from there, but you could do:

[extra.series_intro_templates]
default = """
<div class="admonition note">
   <div class="admonition-icon admonition-icon-tip"></div>
   <div class="admonition-content">
      <strong class="admonition-title">SERIES XXX</strong>
      <p>This post is part of a series</p>
   </div>
</div>
"""

Ahhh, <div>. I forgot about it :) Thank you, I'll try.

Here is a config I had in mind if it can help:

• in config.toml:

[extra]
stylesheets = ["series.css"]

• in sass/series.scss

.series-page-intro {
	margin-top: 1rem;
	margin-bottom: 1rem;
	border: 1px solid var(--primary-color);
	border-inline-start-width: 0.3rem;
	border-radius: 10px;
	padding: 1rem;

	p {
		margin: 0;
	}

	summary::marker {
		color: var(--primary-color);
		font-size: 1.3rem;
	}

	details {
		ol {
			margin-top: 0;
			margin-bottom: 0;
		}
	}
}

• in the _index.md of my series:

series_intro_templates.default = """
<details>
    <summary>This article is part of the series: $SERIES_HTML_LINK</summary>
    $SERIES_PAGES_OLIST
</details>

in config.toml:

Wouldn't it be better to set it on the series section? You can save those bits from downloading until users visit a series page (:

@ZzMzaw thank you, this method is clean and elegant.
@welpo Good point. I added stylesheet part to _index.md.

I have one more question. Is it possible to label any post as part of a series without separating it into a 'series' directory? My site now has Blog and Texts sections. In Blog, I briefly announce new texts in Blog and give a link to the full texts in Texts. Some of them are intended as series, so I was glad to see the new feature. But when I moved them to the series folder, they disappeared from the texts folder. It would be nice if they stayed on the main page, and clicking on any part of the series would take you to the series itself. The other solution is to leave the texts of a series in the Texts and Series sections, but that duplicates content and creates clutter. Or maybe there is already such an option in the new feature, only I don't know how to use it?

@welpo:

Wouldn't it be better to set it on the series section? You can save those bits from downloading until users visit a series page (:

Definitely.
I completely forgot stylesheets could be added anywhere and I just added it in config.toml because I already had stuff in there.
Many thanks for the head's up.

--- Added after testing ---
stylesheets from a section is not added to its pages.
Either we need to set stylesheets in config.toml as stated initially or add it to all the pages which are part of a series (which would introduce a risk to have a bad styling for a series' page in case of forgetting).
We could also updates templates/partials/header.html to add the secion's stylesheets to any page's stylesheets but I would expect it to be a breaking change.
So far, I am fine with adding it in every page.
Overload might not be so big as file may be cached in the browser after the first download.

@stalkerGH:

Is it possible to label any post as part of a series without separating it into a 'series' directory?

By design, a series is a section so unfortunately there is no way to group in the same series pages which are not in the same section.
Nevertheless, having transparent = true set in the series section should merge it with the section above.

From my understanding, you had two folders blog and texts which were sections and texts was containing pages you want to group as series. Let's say, you had 5 pages in there: texts/A, texts/B, texts/C, texts/D and texts/E.
If you want to group pages B and D in series1 and pages C and E in series2, the resulting structure would be: texts/A, texts/series1/B, texts/series2/C, texts/series1/D and texts/series2/E.

Doing so, pages A, B, C, D and E should still be available in texts section but B and D will be part of series1 and C and E will be part of series2.

By the way, I am not sure I understood correctly your situation.
Feel free to let me know if I missed something.

@ZzMzaw Your hint helped me a lot, now it works exactly as I'd like :) Thank you!

Happy to see you can use the feature as well in your use case :-)