Valentin Gagarin <valentin@gagarin.work> writes:

> diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
> new file mode 100644
> index 0000000..cd493f8
> --- /dev/null
> +++ b/Documentation/_includes/sitemap.html
> @@ -0,0 +1,55 @@
> +{% comment %}
> +SPDX-License-Identifier: GPL-3.0-or-later
> +SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
> +
> +Render a nested sitemap rooted at a given URL prefix.  Hierarchy is
> +derived from URL structure: a page is a direct child of prefix P iff
> +its URL starts with P, is not P itself, and contains no further path
> +segments below P.
> +{% endcomment %}
> +
> +{%- assign default_root = "/" -%}
> +{% comment %}
> +`prefix` is the URL of the section to list children of.  It must end with "/",
> +which we assume if it is constructed by a directory and contains an index file.
> +{% endcomment %}
> +{%- assign prefix = include.prefix | default: default_root -%}
> +{%- capture inner -%}
> +  {%- assign candidates = site.html_pages
> +        | where_exp: "p", "p.url contains prefix"
> +        | where_exp: "p", "p.url != prefix" -%}

I overlooked this last time — what if "prefix" is e.g. a suffix of
"p.url"?  Would the false positive be a problem?

> +  {%- comment %}
> +  Ordered pages first, ascending.  The rest after, in URL order, so output is deterministic.
> +  {%- endcomment %}
> +  {%- assign ordered = candidates | where_exp: "p", "p.nav_order" | sort: "nav_order" -%}
> +  {%- assign unordered = candidates | where_exp: "p", "p.nav_order == nil" | sort: "url" -%}
> +  {%- assign sorted = ordered | concat: unordered -%}
> +  {%- for p in sorted -%}
> +    {%- comment %}
> +    `assign` is page-global.  A recursive include below may have overwritten `prefix`.
> +    {%- endcomment %}

Thank you for fighting this uninspiring language on our behalf. :)

> +    {%- assign prefix = include.prefix | default: default_root -%}
> +    {%- assign suffix = p.url | remove_first: prefix -%}
> +    {%- assign without_slashes = suffix | replace: "/", "" -%}
> +    {%- assign slashes = suffix.size | minus: without_slashes.size -%}
> +    {%- assign is_index = false -%}
> +    {%- if p.name == "index.adoc" -%}{%- assign is_index = true -%}{%- endif -%}
> +    {%- assign is_page = false -%}
> +    {%- if is_index == false and slashes == 0 -%}{%- assign is_page = true -%}{%- endif -%}
> +    {%- assign is_section = false -%}
> +    {%- if is_index and slashes == 1 -%}{%- assign is_section = true -%}{%- endif -%}
> +    {%- if is_page or is_section %}
> +    <li>
> +      <a href="{{ p.url | relative_url }}">{{ p.title }}</a>{% if p.description %} — {{ p.description }}{% endif %}

Description rendering here still doesn't work, but I see the next patch
removes the description part here.  That should be part of this patch
instead so we don't add functionality and then immediately remove it.  I
can make that shift when applying if there are no other changes needed
(which depends on the answer to my question above).