diff --git a/templates/macros/series_page.html b/templates/macros/series_page.html
new file mode 100644
index 0000000..d5704a1
--- /dev/null
+++ b/templates/macros/series_page.html
@@ -0,0 +1,162 @@
+{#
+Those macros deal with introduction and navigation for series pages.
+Using macros have been prefered over partial inclusion or inline code to make sure series_ordered_pages is forced to be used.
+A section's pages natural order is invalid in case of reversed pagination which would lead to invalid series' pages order.
+To prevent this, pages are ordered correctly in a separate variable which must be used instead of the series section pages.
+#}
+
+{#
+Computes the introduction of a series's page.
+
+Parameters:
+ - `page`: The page object being part of the series.
+ - `series_section`: The series' section the page belongs to.
+ - `series_ordered_pages`: The series' pages properly ordered (see at the top of this file for an explanation).
+ - `language_strings`: A dictionary containing the translation strings.
+#}
+{% macro process_series_template(template_type, page, series_section, series_ordered_pages, language_strings) %}
+ {%- if "series" in series_section.extra and series_section.extra.series -%}
+ {# Prepare variables for substitution #}
+ {%- set series_title = series_section.title -%}
+ {%- set series_permalink = series_section.permalink -%}
+ {%- set series_html_link = '
' ~ series_section.title ~ '' -%}
+ {# Build series pages list #}
+ {%- set series_pages_list = [] -%}
+ {%- for series_page in series_ordered_pages -%}
+ {%- if series_page.relative_path == page.relative_path -%}
+ {%- set series_pages_list_item = '
' ~ series_page.title ~ '' -%}
+ {%- else -%}
+ {%- set series_pages_list_item = '
' ~ series_page.title ~ '' -%}
+ {%- endif -%}
+ {%- set_global series_pages_list = series_pages_list | concat(with=series_pages_list_item) -%}
+ {%- endfor -%}
+ {%- set series_pages_list = series_pages_list | join(sep="") -%}
+ {%- if macros_settings::evaluate_setting_priority(setting="post_listing_index_reversed", page=series_section, default_global_value=false) == "true" -%}
+ {%- set series_pages_ordered_list = '
' ~ series_pages_list ~ '
' -%}
+ {%- else -%}
+ {%- set series_pages_ordered_list = '
' ~ series_pages_list ~ '
' -%}
+ {%- endif -%}
+ {%- set series_pages_unordered_list = '
' ~ series_pages_list ~ '
' -%}
+
+ {# Get page position and navigation info #}
+ {%- set series_pages_number = 0 -%}
+ {%- set series_page_index = 0 -%}
+ {%- set first_page = series_ordered_pages | first -%}
+ {%- set is_found = false -%}
+
+ {%- for series_page in series_ordered_pages -%}
+ {%- set_global series_pages_number = series_pages_number + 1 -%}
+ {%- if series_page.relative_path == page.relative_path -%}
+ {%- set_global series_page_index = series_pages_number -%}
+ {%- set_global is_found = true -%}
+ {%- else -%}
+ {%- if not is_found -%}
+ {%- set_global prev_page = series_page -%}
+ {%- elif not next_page is defined -%}
+ {%- set_global next_page = series_page -%}
+ {%- endif -%}
+ {%- endif -%}
+ {%- endfor -%}
+
+ {# Determine template to use based on available navigation #}
+ {%- set position = "middle" -%}
+ {%- if prev_page is defined and not next_page is defined -%}
+ {%- set_global position = "prev_only" -%}
+ {%- elif next_page is defined and not prev_page is defined -%}
+ {%- set_global position = "next_only" -%}
+ {%- endif -%}
+
+ {# Get template from config #}
+ {%- set templates_key = "series_" ~ template_type ~ "_templates" -%}
+ {%- set template = "" -%}
+ {%- if series_section.extra[templates_key] is defined -%}
+ {%- if series_section.extra[templates_key][position] is defined -%}
+ {%- set_global template = series_section.extra[templates_key][position] -%}
+ {%- elif series_section.extra[templates_key].default is defined -%}
+ {%- set_global template = series_section.extra[templates_key].default -%}
+ {%- endif -%}
+ {%- endif -%}
+
+ {# Prepare navigation variables #}
+ {%- if prev_page is defined -%}
+ {%- set prev_title = prev_page.title -%}
+ {%- set prev_permalink = prev_page.permalink -%}
+ {%- set prev_html_link = '
' ~ prev_page.title ~ '' -%}
+ {%- set prev_description = prev_page.description | default(value="") -%}
+ {%- endif -%}
+ {%- if next_page is defined -%}
+ {%- set next_title = next_page.title -%}
+ {%- set next_permalink = next_page.permalink -%}
+ {%- set next_html_link = '
' ~ next_page.title ~ '' -%}
+ {%- set next_description = next_page.description | default(value="") -%}
+ {%- endif -%}
+
+ {# Replace standard variables #}
+ {%- set template = template
+ | replace(from="$SERIES_TITLE", to=series_title)
+ | replace(from="$SERIES_PERMALINK", to=series_permalink)
+ | replace(from="$SERIES_HTML_LINK", to=series_html_link)
+ | replace(from="$FIRST_TITLE", to=first_page.title)
+ | replace(from="$FIRST_HTML_LINK", to='
' ~ first_page.title ~ '')
+ | replace(from="$SERIES_PAGES_NUMBER", to=series_pages_number | as_str)
+ | replace(from="$SERIES_PAGE_INDEX", to=series_page_index | as_str)
+ | replace(from="$SERIES_PAGES_OLIST", to=series_pages_ordered_list)
+ | replace(from="$SERIES_PAGES_ULIST", to=series_pages_unordered_list)
+ -%}
+
+ {# Replace navigation variables if they exist #}
+ {%- if prev_page is defined -%}
+ {%- set template = template
+ | replace(from="$PREV_TITLE", to=prev_title)
+ | replace(from="$PREV_PERMALINK", to=prev_permalink)
+ | replace(from="$PREV_HTML_LINK", to=prev_html_link)
+ | replace(from="$PREV_DESCRIPTION", to=prev_description)
+ -%}
+ {%- endif -%}
+
+ {%- if next_page is defined -%}
+ {%- set template = template
+ | replace(from="$NEXT_TITLE", to=next_title)
+ | replace(from="$NEXT_PERMALINK", to=next_permalink)
+ | replace(from="$NEXT_HTML_LINK", to=next_html_link)
+ | replace(from="$NEXT_DESCRIPTION", to=next_description)
+ -%}
+ {%- endif -%}
+
+ {# Custom placeholders #}
+ {%- if series_section.extra.series_template_placeholders is defined -%}
+ {%- set missing_vars = [] -%}
+ {%- for placeholder in series_section.extra.series_template_placeholders -%}
+ {%- if placeholder in template -%}
+ {%- set var_name = placeholder | replace(from="$", to="") | lower -%}
+ {%- if page.extra.series_template_variables is defined and page.extra.series_template_variables[var_name] is defined -%}
+ {%- set_global template = template | replace(from=placeholder, to=page.extra.series_template_variables[var_name]) -%}
+ {%- else -%}
+ {%- set_global missing_vars = missing_vars | concat(with=var_name) -%}
+ {%- endif -%}
+ {%- endif -%}
+ {%- endfor -%}
+ {%- if missing_vars | length > 0 -%}
+ {%- set missing_vars_str = missing_vars | join(sep=", ") -%}
+ {{ throw(message="ERROR: The following variables are included in this page's series templates (`series_template_placeholders`) but have not been set in the `series_template_variables` of this page: " ~ missing_vars_str) }}
+ {%- endif -%}
+ {%- endif -%}
+
+ {# Output the processed template if not empty #}
+ {%- if template | length > 0 -%}
+
+ {{ template | markdown | safe }}
+
+ {%- endif -%}
+ {%- endif -%}
+{% endmacro %}
+
+{# Macro for series introduction #}
+{% macro get_introduction(page, series_section, series_ordered_pages, language_strings) %}
+ {{ macros_series_page::process_series_template(template_type="intro", page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings) }}
+{% endmacro %}
+
+{# Macro for series outro #}
+{% macro get_outro(page, series_section, series_ordered_pages, language_strings) %}
+ {{ macros_series_page::process_series_template(template_type="outro", page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings) }}
+{% endmacro %}
diff --git a/templates/page.html b/templates/page.html
index 969baa0..c269531 100644
--- a/templates/page.html
+++ b/templates/page.html
@@ -180,6 +180,33 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{% endif %}
+ {#- A page is part of a series if one of the sections above (whether it is transparent or not) has the `extra.series` parameter set to true. -#}
+ {#- As a series might be a transparent section in order to mix up its articles with those of the section just above or the root, -#}
+ {#- there is no other way but to compute the potential path of each ancestor section related to the page and look for the first one being a series. -#}
+ {#- Using the `ancestors` field of a section is not possible because transparent sections are not present in this field. -#}
+ {%- set current_path = [] -%}
+ {%- set section_paths = [] -%}
+ {%- for path in page.relative_path | split(pat="/") | slice(end=-1) -%}
+ {%- set_global current_path = current_path | concat(with=path) -%}
+ {%- set section_path = current_path | concat(with="_index.md") | join(sep="/") -%}
+ {%- set_global section_paths = section_paths | concat(with=section_path) -%}
+ {%- endfor -%}
+ {#- The series the page is part of is the closest section flagged as a series, if any -#}
+ {%- for section_path in section_paths | reverse -%}
+ {%- set section_file_exists = load_data(path=section_path, required=false) -%}
+ {%- if section_file_exists -%}
+ {%- set loaded_section = get_section(path=section_path,lang=lang) -%}
+ {%- if "series" in loaded_section.extra and loaded_section.extra.series -%}
+ {%- set_global series_section = loaded_section -%}
+ {%- set_global series_ordered_pages = loaded_section.pages -%}
+ {%- if loaded_section.paginated | default(value=0) > 0 and loaded_section.paginate_reversed -%}
+ {%- set_global series_ordered_pages = loaded_section.pages | reverse -%}
+ {%- endif -%}
+ {%- break -%}
+ {%- endif -%}
+ {%- endif -%}
+ {%- endfor -%}
+
{% if page.extra.tldr %}
@@ -192,18 +219,48 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{% endif %}
- {# Optional table of contents below the header #}
+ {#- Optional table of contents below the header -#}
{% if page.toc and macros_settings::evaluate_setting_priority(setting="toc", page=page, default_global_value=false) == "true" %}
{{ macros_toc::toc(page=page, header=true, language_strings=language_strings) }}
{% endif %}
- {# The replace pattern is used to enable arbitrary locations for the Table of Contents #}
- {# This is Philipp Oppermann's workaround: https://github.com/getzola/zola/issues/584#issuecomment-474329637 #}
- {{ page.content | replace(from="", to=macros_toc::toc(page=page, header=false, language_strings=language_strings)) | safe }}
+ {#- Replace series_intro placeholder -#}
+ {%- set content_with_intro = page.content -%}
+ {%- if "" in page.content -%}
+ {%- set series_intro_html = macros_series_page::get_introduction(page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings) -%}
+ {%- set content_with_intro = content_with_intro | replace(from="", to=series_intro_html) -%}
+ {%- elif series_section -%}
+ {%- set series_intro_html = macros_series_page::get_introduction(page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings) -%}
+ {%- set content_with_intro = series_intro_html ~ content_with_intro -%}
+ {%- endif -%}
+
+ {#- Handle series_outro placeholder -#}
+ {%- set processed_content = content_with_intro -%}
+ {%- if "" in content_with_intro -%}
+ {%- set series_outro_html = macros_series_page::get_outro(page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings) -%}
+ {%- set processed_content = processed_content | replace(from="", to=series_outro_html) -%}
+ {%- elif series_section -%}
+ {%- set series_outro_html = macros_series_page::get_outro(page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings) -%}
+ {#- We want the outro at the end of the article, but before footnote definitions -#}
+ {%- set footnotes_marker = '
- {# Check if comments are enabled, checking that they are not disabled on the specific page #}
+ {#- Check if comments are enabled, checking that they are not disabled on the specific page -#}
{% set systems = ["giscus", "utterances", "hyvortalk", "isso"] %}
{% set enabled_systems = 0 %}
{% set comment_system = "" %}
@@ -219,11 +276,6 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{% endif %}
{% endfor %}
- {# Ensure only one comment system is enabled #}
- {% if enabled_systems > 1 %}
- {{ throw(message="ERROR: Multiple comment systems have been enabled for the same page. Check your config.toml and individual page settings to ensure only one comment system is activated at a time.") }}
- {% endif %}
-
{% if macros_settings::evaluate_setting_priority(setting="show_previous_next_article_links", page=page, default_global_value=true) == "true" %}
{%- if page.lower or page.higher -%}
{% set next_label = macros_translate::translate(key="next", default="Next", language_strings=language_strings) %}
@@ -271,7 +323,11 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{%- endif -%}
{%- endif -%}
- {# Comments #}
+ {#- Comments -#}
+ {#- Ensure only one comment system is enabled -#}
+ {% if enabled_systems > 1 %}
+ {{ throw(message="ERROR: Multiple comment systems have been enabled for the same page. Check your config.toml and individual page settings to ensure only one comment system is activated at a time.") }}
+ {% endif %}
{% if comment_system %}
{% include "partials/comments.html" %}
{% endif %}
diff --git a/templates/partials/extra_features.html b/templates/partials/extra_features.html
index ad0080d..46a10df 100644
--- a/templates/partials/extra_features.html
+++ b/templates/partials/extra_features.html
@@ -1,8 +1,9 @@
+{%- set page_or_section = page | default(value=section) -%}
{# Quick navigation buttons #}
-{% if macros_settings::evaluate_setting_priority(setting="quick_navigation_buttons", page=page, default_global_value=false) == "true" %}
+{% if macros_settings::evaluate_setting_priority(setting="quick_navigation_buttons", page=page_or_section, default_global_value=false) == "true" %}