It is unclear what extra.top does

[Jonathan Shook]

I read the theme source for this but it was still a bit abstract. It would be nice to have this documented in the top-level docs in a way that shows what the theme designer intended.

[Aaran Xu]

The 'extra.top' option is to set the navigation of the section's pages. Because the default navigation config of the Zola cannot find the previous or the next page in the nested section, the 'extra.top' is added to mark the page is the super page that has no parent pages.

You can read the related code in the file templates/macros/docs-navigation.html：

{% macro docs_navigation(page, current_section) %}
<div class="docs-navigation d-flex justify-content-between">
  {# Find lighter navigation. There are three types: #}
  {# 1. directly find the lighter if exists, #}
  {# 2. find the last page in the previous sibling section, and #}
  {# 3. find the last page in the parent section. #}
  {% if page.lighter %}
  <a href="{{ page.lighter.permalink }}">
    <div class="card my-1">
      <div class="card-body py-2">
        &larr; {{ page.lighter.title }}
      </div>
    </div>
  </a>
  {% elif not page.extra.top %}
    {% set index = get_section(path=page.ancestors | reverse | first) %}
    {% set parent = get_section(path=index.ancestors | reverse | first)%}
    {% set first_subsection = get_section(path=parent.subsections | first) %}
    {% if index == first_subsection %}
      {% if parent.pages %}
        {% set last_page = parent.pages | last %}
        <a href="{{ last_page.permalink }}">
          <div class="card my-1">
            <div class="card-body py-2">
              &larr; {{ last_page.title }}
            </div>
          </div>
        </a>
      {% endif %}
...
{% endmacro %}