AFDocs: Improve docs accessibility for agents

plugins.yml

@@ -68,7 +68,12 @@ plugins:
 
     - llmstxt:
         preprocess: llmstxt_preprocess.py
-
+        markdown_description: >-
+              > User documentation for Ibexa DXP covers content management, product catalog, commerce, and site administration for editors and business users.
+        # Pin links in the generated Markdown (and llms.txt) to this branch's
+        # version instead of site_url's en/latest, without affecting the HTML
+        # site's canonical URLs. Update when branching a new version.
+        base_url: https://doc.ibexa.co/projects/userguide/en/5.0/
         autoclean: false
         full_output: llms-full.txt
         sections:

theme/main.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% set md_href = page.file.dest_uri | replace('.html', '.md') if page else '' %}
   {% block htmltitle %}
     {%- if page and page.meta and page.meta.title -%}
       <title>{{ page.meta.title }}</title>
@@ -20,7 +21,6 @@
     <link rel="llms" href="{{ 'llms-full.txt' | url }}" title="LLM-friendly full content">
 
     {% if page and not page.meta.exclude_from_llmstxt %}
-      {% set md_href = page.file.dest_uri | replace('.html', '.md') %}
       <link rel="alternate" type="text/markdown" href="{{ md_href | url }}" title="Markdown Version">
     {% endif %}
 
@@ -30,7 +30,10 @@
 
     {% block site_nav %}
     {% if nav %}
-      <div class="main_nav">
+      {# The single <nav> landmark wrapping the whole sidebar. Keep it the only <nav> in this
+         subtree: nested <nav> tags break the HTML->Markdown converters used by AI agents
+         (e.g. behind RTD's "Accept: text/markdown"), leaking nav items into the output. #}
+      <nav class="main_nav" aria-label="Site navigation">
         <div class="main_nav_content">
           <div class="site-header" id="site-name">
             <a href="/projects/userguide/">{{ config.site_name }}</a>
@@ -43,7 +46,7 @@
             </div>
           </div>
         </div>
-      </div>
+      </nav>
     {% endif %}
     {% if page.toc %}
       <div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
@@ -58,6 +61,11 @@
 
 
     {% block content %}
+        <!-- Discovery directive for AI agents; visually hidden -->
+        <div style="position:absolute;width:1px;height:1px;clip:rect(0 0 0 0);overflow:hidden" aria-hidden="true">
+          For AI agents: the complete documentation index is available at <a href="{{ 'llms.txt' | url }}">llms.txt</a>
+          {% if page and not page.meta.exclude_from_llmstxt %}This page is also <a href="{{ md_href | url }}">available as Markdown</a>{% endif %}.
+        </div>
         {% set ns = namespace(bootstrap_extra_css='') %}
         {% for md_file in config.extra.append_bootstrap if 'docs' + md_file in page.edit_url %}
           {% set ns.bootstrap_extra_css = ' bootstrap-iso' %}

theme/partials/nav-item.html

@@ -9,7 +9,8 @@
     <label class="md-nav__link level-{{ level }}" for="{{ path }}">
       {{ nav_item.title }} <span class="pill pill--new" hidden>New</span>
     </label>
-    <nav class="md-nav" aria-label="{{ nav_item.title }}" data-md-level="{{ level }}">
+    {# div instead of nav: nested <nav> tags break HTML->Markdown converters, see nav.html #}
+    <div class="md-nav" aria-label="{{ nav_item.title }}" data-md-level="{{ level }}">
       <label class="md-nav__link-title md-nav__link level-{{ level }}" for="{{ path }}">
         {{ nav_item.title }}
       </label>
@@ -21,7 +22,7 @@
           {% include "partials/nav-item.html"  %}
         {% endfor %}
       </ul>
-    </nav>
+    </div>
   </li>
 {% elif nav_item == page %}
   <li class="{{ class }}">
@@ -40,6 +41,9 @@
       {% if nav_item.meta.month_change %}<span class="pill pill--new">New</span>{% endif %}
     </a>
     {% if toc | first is defined %}
+      {# toc_inside_nav: render the TOC with a <div> wrapper because it sits inside the
+         sidebar <nav> here; a nested <nav> would break HTML->Markdown converters, see nav.html #}
+      {% set toc_inside_nav = true %}
       {% include "partials/toc.html" %}
     {% endif %}
   </li>

theme/partials/nav.html

@@ -1,9 +1,12 @@
-<nav class="md-nav md-nav--primary" data-md-level="0">
+{# div instead of nav: the whole sidebar is wrapped in a single <nav> in main.html.
+   Nested <nav> tags break the HTML->Markdown converters used by AI agents (e.g. the one
+   behind RTD's "Accept: text/markdown"), which skip <nav> only until the first closing tag. #}
+<div class="md-nav md-nav--primary" data-md-level="0">
   <ul class="md-nav__list" data-md-scrollfix>
     {% for nav_item in nav %}
       {% set path = "nav-" + loop.index | string %}
       {% set level = 1 %}
       {% include "partials/nav-item.html" %}
     {% endfor %}
   </ul>
-</nav>
+</div>

theme/partials/toc.html

@@ -1,5 +1,8 @@
 {% import "partials/language.html" as lang with context %}
-<nav class="md-nav md-nav--secondary" aria-label="{{ lang.t('toc.title') }}">
+{# toc_wrapper_tag: <nav> when standalone; <div> when embedded inside the sidebar <nav>
+   (toc_inside_nav set by nav-item.html) — nested <nav> tags break HTML->Markdown converters #}
+{% set toc_wrapper_tag = 'div' if toc_inside_nav else 'nav' %}
+<{{ toc_wrapper_tag }} class="md-nav md-nav--secondary" aria-label="{{ lang.t('toc.title') }}">
   {% set toc = page.toc %}
   {% if toc | first is defined and "\x3ch1 id=" in page.content %}
     {% set toc = (toc | first).children %}
@@ -18,7 +21,7 @@
             {{ toc_item.title }}
           </a>
           {% if toc_item.children %}
-              <nav class="md-nav">
+              <div class="md-nav">
                 <ul class="md-nav__list">
                   {% for toc_item in toc_item.children %}
                     <li class="md-nav__item level-2">
@@ -28,10 +31,10 @@
                     </li>
                   {% endfor %}
                 </ul>
-              </nav>
+              </div>
           {% endif %}
         </li>
       {% endfor %}
     </ul>
   {% endif %}
-</nav>
+</{{ toc_wrapper_tag }}>