- Add templating for outro, similar/extended from intro code

- Renames series_page_introduction_placeholders to series_template_placeholders
- Removes `post_listing_index_reversed` in favour of outro templates
- Docs!
This commit is contained in:
welpo 2024-10-26 00:05:45 +02:00 committed by ZzMzaw
parent c056b53d26
commit 434769376e
11 changed files with 461 additions and 172 deletions

View file

@ -14,140 +14,149 @@ Parameters:
- `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 get_introduction(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 = '<a href="' ~ series_section.permalink ~ '" aria_label="' ~ series_section.title ~ '">' ~ series_section.title ~ '</a>' -%}
{%- set series_pages_list = [] -%}
{%- set series_pages_number = 0 -%}
{%- set series_page_index = 0 -%}
{%- 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 series_pages_list_item = '<li>' ~ series_page.title ~ '</li>' -%}
{%- else -%}
{%- set series_pages_list_item = '<li><a href="' ~ series_page.permalink ~ '" aria_label="' ~ series_page.title ~ '">' ~ series_page.title ~ '</a></li>' -%}
{%- endif -%}
{%- set_global series_pages_list = series_pages_list | concat(with=series_pages_list_item) -%}
{%- endfor -%}
{%- set series_pages_number = series_pages_number | as_str -%}
{%- set series_page_index = series_page_index | as_str -%}
{%- 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 = '<ol reversed>' ~ series_pages_list ~ '</ol>' -%}
{%- else -%}
{%- set series_pages_ordered_list = '<ol>' ~ series_pages_list ~ '</ol>' -%}
{%- endif -%}
{%- set series_pages_unordered_list = '<ul>' ~ series_pages_list ~ '</ul>' -%}
{# Define introduction #}
{%- set series_page_introduction = series_section.extra.series_page_introduction | default(value="") -%}
{%- set series_page_introduction = series_page_introduction | replace(from="$SERIES_TITLE", to=series_title) | replace(from="$SERIES_PERMALINK", to=series_permalink) | replace(from="$SERIES_HTML_LINK", to=series_html_link) -%}
{%- set series_page_introduction = series_page_introduction | replace(from="$SERIES_PAGES_NUMBER", to=series_pages_number) | replace(from="$SERIES_PAGE_INDEX", to=series_page_index) | replace(from="$SERIES_PAGES_OLIST", to=series_pages_ordered_list) | replace(from="$SERIES_PAGES_ULIST", to=series_pages_unordered_list) -%}
{# Replace introduction custom placeholders #}
{%- if series_section.extra.series_page_introduction_placeholders is defined -%}
{%- set missing_vars = [] -%}
{%- for placeholder in series_section.extra.series_page_introduction_placeholders -%}
{%- if placeholder in series_page_introduction -%}
{# Attempt to retrieve the corresponding variable by trimming the $ sign and converting to lowercase #}
{%- set var_name = placeholder | replace(from="$", to="") | lower -%}
{%- if page.extra.series_page_introduction_variables[var_name] -%}
{%- set_global series_page_introduction = series_page_introduction | replace(from=placeholder, to=page.extra.series_page_introduction_variables[var_name]) -%}
{%- else -%}
{# Append the variable name to the list of missing variables #}
{% 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 introduction (`series_page_introduction_placeholders`) but have not been set in the `series_page_introduction_variables` of this page: " ~ missing_vars_str) }}
{%- endif -%}
{%- endif -%}
{%- if series_page_introduction | length > 0 -%}
<section class="series-page-introduction">
{{ series_page_introduction | markdown | safe }}
</section>
{%- endif -%}
{% 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 = '<a href="' ~ series_section.permalink ~ '" aria_label="' ~ series_section.title ~ '">' ~ series_section.title ~ '</a>' -%}
{# 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 = '<li>' ~ series_page.title ~ '</li>' -%}
{%- else -%}
{%- set series_pages_list_item = '<li><a href="' ~ series_page.permalink ~ '" aria_label="' ~ series_page.title ~ '">' ~ series_page.title ~ '</a></li>' -%}
{%- 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 = '<ol reversed>' ~ series_pages_list ~ '</ol>' -%}
{%- else -%}
{%- set series_pages_ordered_list = '<ol>' ~ series_pages_list ~ '</ol>' -%}
{%- endif -%}
{%- set series_pages_unordered_list = '<ul>' ~ series_pages_list ~ '</ul>' -%}
{# 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 = '<a href="' ~ prev_page.permalink ~ '" aria_label="' ~ prev_page.title ~ '">' ~ prev_page.title ~ '</a>' -%}
{%- 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 = '<a href="' ~ next_page.permalink ~ '" aria_label="' ~ next_page.title ~ '">' ~ next_page.title ~ '</a>' -%}
{%- 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='<a href="' ~ first_page.permalink ~ '">' ~ first_page.title ~ '</a>')
| 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 -%}
<section class="series-page-{{ template_type }}">
{{ template | markdown | safe }}
</section>
{%- endif -%}
{%- endif -%}
{% endmacro %}
{#
Computes the series navigation 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 get_navigation(page, series_section, series_ordered_pages, language_strings) %}
{%- if macros_settings::evaluate_setting_priority(setting="show_previous_next_series_article_links", page=page, default_global_value=false) == "true" -%}
{%- if series_ordered_pages | length > 1 -%}
{% set next_series_label = macros_translate::translate(key="next_series", default="Next (series)", language_strings=language_strings) %}
{% set prev_series_label = macros_translate::translate(key="prev_series", default="Prev (series)", language_strings=language_strings) %}
{% set is_previous = true %}
{% set is_next = false %}
{%- for series_page in series_ordered_pages -%}
{%- if series_page.relative_path == page.relative_path -%}
{%- set_global is_previous = false -%}
{%- set_global is_next = true -%}
{%- else -%}
{%- if is_previous -%}
{%- set_global prev_series_page = series_page -%}
{%- endif -%}
{%- if is_next -%}
{%- set_global next_series_page = series_page -%}
{%- set_global is_next = false-%}
{%- endif -%}
{%- endif -%}
{%- endfor -%}
{% if macros_settings::evaluate_setting_priority(setting="invert_previous_next_article_links", page=page, default_global_value=true) == "true" %}
{% if prev_series_page %}
{% set left_series_link = prev_series_page.permalink %}
{% set left_series_label = prev_series_label %}
{% set left_series_title = prev_series_page.title %}
{% endif %}
{% if next_series_page %}
{% set right_series_link = next_series_page.permalink %}
{% set right_series_label = next_series_label %}
{% set right_series_title = next_series_page.title %}
{% endif %}
{% else %}
{% if next_series_page %}
{% set left_series_link = next_series_page.permalink %}
{% set left_series_label = next_series_label %}
{% set left_series_title = next_series_page.title %}
{% endif %}
{% if prev_series_page %}
{% set right_series_link = prev_series_page.permalink %}
{% set right_series_label = prev_series_label %}
{% set right_series_title = prev_series_page.title %}
{% endif %}
{% endif %}
{% if macros_settings::evaluate_setting_priority(setting="previous_next_article_links_full_width", page=page, default_global_value=true) == "true" %}
{%- set full_width_class = "full-width" -%}
{% endif %}
<nav class="{{ full_width_class | default(value="") }} series-article-navigation">
<div>
{%- if left_series_link and left_series_label and left_series_title -%}
<a href="{{ left_series_link | safe }}" aria-label="{{ left_series_label }}" aria-describedby="left_series_title"><span class="arrow"></span>&nbsp;{{ left_series_label }}</a>
<p aria-hidden="true" id="left_series_title">{{ left_series_title | truncate(length=100, end="…") }}</p>
{%- endif -%}
</div>
<div>
{%- if right_series_link and right_series_label and right_series_title -%}
<a href="{{ right_series_link | safe }}" aria-label="{{ right_series_label }}" aria-describedby="right_series_title">{{ right_series_label }}&nbsp;<span class="arrow"></span></a>
<p aria-hidden="true" id="right_series_title">{{ right_series_title | truncate(length=100, end="…") }}</p>
{%- endif -%}
</div>
</nav>
{%- endif -%}
{%- endif -%}
{# 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 %}

View file

@ -172,7 +172,7 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{%- set formatted_date = macros_format_date::format_date(date=page.updated, short=true, language_strings=language_strings) -%}
{%- set updated_str = last_updated_str | replace(from="$DATE", to=formatted_date) -%}
</ul><ul class="meta last-updated"><li>{{ updated_str }}</li>
{# Show link to remote changes if enabled #}
{#- Show link to remote changes if enabled -#}
{% if config.extra.remote_repository_url and macros_settings::evaluate_setting_priority(setting="show_remote_changes", page=page, default_global_value=true) == "true" %}
{%- if previous_visible -%}{{ separator }}&nbsp;{%- endif -%}
<li><a href="{% include "partials/history_url.html" %}" {{ blank_target }} rel="{{ rel_attributes }}">{{ macros_translate::translate(key="see_changes", default="See changes", language_strings=language_strings) }}<small>&nbsp;<span class="arrow-corner"></span></small></a></li>
@ -180,10 +180,10 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{% endif %}
</ul>
{# 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. #}
{#- 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) -%}
@ -191,7 +191,7 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{%- 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 #}
{#- 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 -%}
@ -207,10 +207,6 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{%- endif -%}
{%- endfor -%}
{% if series_section %}
{{ macros_series_page::get_introduction(page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings)}}
{% endif %}
{% if page.extra.tldr %}
<div class="admonition note">
<div class="admonition-icon admonition-icon-note"></div>
@ -223,18 +219,48 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
</div>
{% 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 %}
<section class="body">
{# 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="<!-- toc -->", to=macros_toc::toc(page=page, header=false, language_strings=language_strings)) | safe }}
{#- Replace series_intro placeholder -#}
{%- set content_with_intro = page.content -%}
{%- if "<!-- series_intro -->" 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="<!-- series_intro -->", 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 "<!-- series_outro -->" 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="<!-- series_outro -->", 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 = '<hr><ol class="footnotes-list">' -%}
{%- if footnotes_marker in content_with_intro -%}
{%- set content_sections = processed_content | split(pat=footnotes_marker) -%}
{%- set main_content = content_sections | first -%}
{%- set footnotes_content = content_sections | slice(start=1) | join(sep=footnotes_marker) -%}
{%- set processed_content = main_content ~ series_outro_html ~ footnotes_marker ~ footnotes_content -%}
{%- else -%}
{%- set processed_content = processed_content ~ series_outro_html -%}
{%- endif -%}
{%- endif -%}
{#- Replace TOC and render final content -#}
{#- 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 -#}
{{ processed_content | replace(from="<!-- toc -->", to=macros_toc::toc(page=page, header=false, language_strings=language_strings)) | safe }}
</section>
{# 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 = "" %}
@ -250,9 +276,6 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{% endif %}
{% endfor %}
{% if series_section %}
{{ macros_series_page::get_navigation(page=page, series_section=series_section, series_ordered_pages=series_ordered_pages, language_strings=language_strings)}}
{%- 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) %}
@ -300,12 +323,12 @@ Current section extra: {% if current_section %}{{ current_section.extra | json_e
{%- endif -%}
{%- endif -%}
{# Ensure only one comment system is enabled #}
{#- 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 %}
{# Comments #}
{#- Comments -#}
{% if comment_system %}
{% include "partials/comments.html" %}
{% endif %}