AFDocs: Improve docs accessibility for agents by mnocon · Pull Request #3297 · ibexa/documentation-developer

mnocon · 2026-07-17T16:19:23Z

Target: 5.0, 6.0

Companion PR: ibexa/documentation-user#415

This PR improves how AI Agents can read our documentation.

Things done:

Follow Agent-Friendly Documentation spec

AFDocs is a specification for creating docs accessible by AI agents.

The current score (after #3161) is:

Agent-Friendly Docs Scorecard
==============================

https://doc.ibexa.co · 7/21/2026, 1:14:04 PM

  Overall Score: 78 / 100 (C)

  Category Scores:
    Content Discoverability               64 / 100 (D)
    Markdown Availability                 64 / 100 (D)
    Page Size and Truncation Risk         82 / 100 (B)
    Content Structure                    100 / 100 (A+)
    URL Stability and Redirects          100 / 100 (A+)
    Observability and Content Health      90 / 100 (A)
    Authentication and Access            100 / 100 (A+)

  Interaction Diagnostics:
    [!] Your site serves markdown at .md URLs, but agents have no way to discover this
        Your site serves markdown at .md URLs, but agents have no way to discover this. No agent-facing directive points to your llms.txt, and the server does not support content negotiation. Most agents will default to the HTML path and never benefit from your markdown support.

        Fix: Add a directive near the top of each docs page pointing to your llms.txt, and implement content negotiation for Accept: text/markdown. The directive is the primary discovery mechanism (it reaches all agents); content negotiation provides a fast path for agents that request markdown by default.

    [!] 13 pages exceed agent truncation limits on the HTML path, and there is no discoverable markdown path for agents to get smaller representations
        13 pages exceed agent truncation limits on the HTML path, and there is no discoverable markdown path for agents to get smaller representations. Agents will silently receive truncated content on these pages.

        Fix: Either reduce HTML page sizes (break large pages, reduce inline CSS/JS), or provide markdown versions and ensure agents can discover them via content negotiation or an llms.txt directive.

  Check Results:

    Content Discoverability
      PASS  llms-txt-exists                llms.txt found at https://doc.ibexa.co/llms.txt
      WARN  llms-txt-valid                 llms.txt contains parseable links but doesn't fully follow the proposed structure: https://doc.ibexa.co/llms.txt: No blockquote summary found
            Fix: Your llms.txt contains parseable links but doesn't follow the standard structure. Add an H1 title as the first line and a blockquote summary (lines starting with >) to improve agent parsing.
      WARN  llms-txt-size                  llms.txt is 90,326 characters (between 50,000 and 100,000; consider splitting)
            Fix: Your llms.txt is 90,326 characters, which may be truncated on some agent platforms. If it grows further, split into nested llms.txt files with a root index under 50,000 characters.
      PASS  llms-txt-links-resolve         All 50 same-origin sampled links resolve (812 total links)
      PASS  llms-txt-links-markdown        50/50 same-origin sampled links point to markdown content (100%)
      FAIL  llms-txt-directive-html        No llms.txt directive found in HTML of any of 50 sampled pages
            Fix: No agent-facing directive pointing to llms.txt was detected in the HTML of any tested page. Add a visually-hidden element near the top of each page (e.g., a div with CSS clip-rect) containing a link to your llms.txt. If your site serves markdown versions of pages, mention that in the directive too so agents know to request it.
      FAIL  llms-txt-directive-md          No llms.txt directive found in markdown of any of 50 sampled pages
            Fix: No llms.txt directive was detected in the markdown of any tested page. Add a blockquote near the top of each markdown page (e.g., "> For the complete documentation index, see [llms.txt](/llms.txt)").

    Markdown Availability
      PASS  markdown-url-support           50/50 sampled pages support .md URLs (100%)
      FAIL  content-negotiation            Server ignores Accept: text/markdown header (0/50 sampled pages return markdown)
            Fix: Your server ignores Accept: text/markdown and returns HTML. Some agents (Claude Code, Cursor, OpenCode) request markdown this way. Configure your server to honor content negotiation.

    Page Size and Truncation Risk
      PASS  rendering-strategy             All 50 sampled pages contain server-rendered content
      PASS  page-size-markdown             All 50 pages under 50K chars (median 3K, max 38K)
      FAIL  page-size-html                 13 of 50 sampled pages convert to over 100K chars (max 377K HTML → 167K markdown (68% boilerplate))
            Fix: 13 of 50 pages convert to over 100K characters of markdown. Break large pages into smaller units, reduce navigation boilerplate, or provide markdown versions that bypass the HTML conversion overhead.
      PASS  content-start-position         Content starts within first 10% on all 50 sampled pages (median 0%)

    Content Structure
      PASS  tabbed-content-serialization   2 tab group(s) across 2 of 50 sampled pages; all serialize under 50K chars
      SKIP  section-header-quality         2 page(s) with tabs found, but no section headers inside tab panels to evaluate
      PASS  markdown-code-fence-validity   All 215 code fences properly closed across 51 pages

    URL Stability and Redirects
      PASS  http-status-codes              All 50 sampled pages return proper error codes for bad URLs
      PASS  redirect-behavior              No redirects detected across 50 sampled pages

    Observability and Content Health
      PASS  llms-txt-coverage              llms.txt covers 95% of 853 sitemap doc pages
      FAIL  markdown-content-parity        6 of 50 pages have substantive content differences between markdown and HTML (avg 10% missing)
            Fix: 6 pages have substantive content differences between markdown and HTML (avg 10% missing). If unintentional, agents are getting outdated content; regenerate markdown from source or fix the build pipeline. If intentional (audience segmentation), add data-markdown-ignore to human-only HTML elements, or adjust thresholds with --parity-pass-threshold/--parity-warn-threshold.
      PASS  cache-header-hygiene           All 51 endpoints have appropriate cache headers

    Authentication and Access
      PASS  auth-gate-detection            All 50 sampled pages are publicly accessible
      SKIP  auth-alternative-access        All docs pages are publicly accessible; no alternative access paths needed

This PR aims to improve the first three criteria:

Content Discoverability 64 / 100 (D)
Markdown Availability 64 / 100 (D)
Page Size and Truncation Risk 82 / 100 (B)

ReadTheDocs Markdown conversion

When a request with Accept: text/markdown is made, ReadTheDocs serves the Markdown version of the page:
https://docs.readthedocs.com/platform/latest/reference/markdown-for-agents.html

This Markdown conversion is done independently from what we do to serve our Markdown, and there are limited ways we can influence it.

But, importantly, there are issues with that conversion that we need to fix/work around.

EOL version warning

Sending a request with curl -H "Accept: text/markdown" https://doc.ibexa.co/en/5.0/administration/back_office/back_office_elements/add_dropdowns/ has the following in the page content:

This documentation is for a version that has reached its End Of Life. Such versions are no longer supported and don't receive security updates. Consider updating to a newer version.

This is of course very bad, and in this PR the solution is reworked to add the EOL warning only when building for specific branches.
Otherwise, AI Agents might think that 5.0 is EOL already.

Current state: add the warning and hide it when not needed by using JS
This PR: do not add the warning unless the branch is marked as EOL.

The EOL version change has to be backported to 4.6 as well

Hiding the TOC in the Markdown

See https://github.com/ibexa/documentation-developer/pull/3297/changes#r3622091055

After the changes

It's hard to get an exact score before this is merged, but it looks much better:

Running checks on ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/...

Agent-Friendly Docs Scorecard
==============================

https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/ · 7/17/2026, 10:19:54 PM

  Overall Score: 88 / 100 (B)

  Category Scores:
    Content Discoverability               84 / 100 (B)
    Markdown Availability                 64 / 100 (D)
    Page Size and Truncation Risk         87 / 100 (B)
    Content Structure                    100 / 100 (A+)
    URL Stability and Redirects          100 / 100 (A+)
    Observability and Content Health      90 / 100 (A)
    Authentication and Access            100 / 100 (A+)

  Interaction Diagnostics:
    [!] Your site serves markdown at .md URLs, but agents have no way to discover this
        Your site serves markdown at .md URLs, but agents have no way to discover this. No agent-facing directive points to your llms.txt, and the server does not support content negotiation. Most agents will default to the HTML path and never benefit from your markdown support.

        Fix: Add a directive near the top of each docs page pointing to your llms.txt, and implement content negotiation for Accept: text/markdown. The directive is the primary discovery mechanism (it reaches all agents); content negotiation provides a fast path for agents that request markdown by default.

  Check Results:

    Content Discoverability
      PASS  llms-txt-exists                llms.txt found at 2 locations; using https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/llms.txt as canonical
      WARN  llms-txt-valid                 llms.txt contains parseable links but doesn't fully follow the proposed structure: https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/llms.txt: No blockquote summary found
            Fix: Your llms.txt contains parseable links but doesn't follow the standard structure. Add an H1 title as the first line and a blockquote summary (lines starting with >) to improve agent parsing.
      WARN  llms-txt-size                  llms.txt is 87,908 characters (between 50,000 and 100,000; consider splitting)
            Fix: Your llms.txt is 87,908 characters, which may be truncated on some agent platforms. If it grows further, split into nested llms.txt files with a root index under 50,000 characters.
      SKIP  llms-txt-links-resolve         llms.txt contains 811 links, but none are under /en/3297
      SKIP  llms-txt-links-markdown        llms.txt contains 811 links, but none are under /en/3297
      WARN  llms-txt-directive-html        llms.txt directive found in HTML of 11 of 12 pages (1 missing)
            Fix: An llms.txt directive was found in the HTML of some pages but is missing from others, or is buried deep in the page. Ensure the directive appears near the top of every documentation page.
      PASS  llms-txt-directive-md          llms.txt directive found in markdown of all 12 pages, near the top of content

    Markdown Availability
      PASS  markdown-url-support           12/12 pages support .md URLs (100%)
      FAIL  content-negotiation            Server ignores Accept: text/markdown header (0/12 pages return markdown)
            Fix: Your server ignores Accept: text/markdown and returns HTML. Some agents (Claude Code, Cursor, OpenCode) request markdown this way. Configure your server to honor content negotiation.

    Page Size and Truncation Risk
      PASS  rendering-strategy             All 12 pages contain server-rendered content
      PASS  page-size-markdown             All 12 pages under 50K chars (median 2K, max 11K)
      WARN  page-size-html                 12 of 12 pages convert to 50K–100K chars (max 298K HTML → 91K markdown (70% boilerplate))
            Fix: 12 of 12 pages convert to 50K-100K characters of markdown. Review pages for reducible boilerplate (navigation, serialized tabbed content). Consider providing markdown versions as a smaller alternative path for agents.
      PASS  content-start-position         Content starts within first 10% on all 12 pages (median 0%)

    Content Structure
      PASS  tabbed-content-serialization   No tabbed content detected across 12 pages
      PASS  section-header-quality         No tabbed content found; header quality check not applicable
      PASS  markdown-code-fence-validity   All 0 code fences properly closed across 14 pages

    URL Stability and Redirects
      PASS  http-status-codes              All 12 pages return proper error codes for bad URLs
      PASS  redirect-behavior              No redirects detected across 12 pages

    Observability and Content Health
      SKIP  llms-txt-coverage              No page URLs found in llms.txt
      FAIL  markdown-content-parity        1 of 12 pages have substantive content differences between markdown and HTML (avg 6% missing)
            Fix: 1 pages have substantive content differences between markdown and HTML (avg 6% missing). If unintentional, agents are getting outdated content; regenerate markdown from source or fix the build pipeline. If intentional (audience segmentation), add data-markdown-ignore to human-only HTML elements, or adjust thresholds with --parity-pass-threshold/--parity-warn-threshold.
      PASS  cache-header-hygiene           All 14 endpoints have appropriate cache headers

    Authentication and Access
      PASS  auth-gate-detection            All 12 pages are publicly accessible
      SKIP  auth-alternative-access        All docs pages are publicly accessible; no alternative access paths needed

Full spec: https://agentdocsspec.com/spec/

BTW the following fail:

      FAIL  content-negotiation            Server ignores Accept: text/markdown header (0/12 pages return markdown)
            Fix: Your server ignores Accept: text/markdown and returns HTML. Some agents (Claude Code, Cursor, OpenCode) request markdown this way. Configure your server to honor content negotiation.

is a false postive: ReadTheDocs returns Markdown, but starts the response with "<!doctype html>" which is treated by the tool as HTML response.

github-actions · 2026-07-17T16:19:35Z

Preview of modified files

Preview of modified Markdown:

github-actions · 2026-07-17T16:27:26Z

Summary

Status	Count
🔍 Total	763512
🔗 Unique	15039
✅ Successful	6328
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	757184
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	0

Full Github Actions output

Temporary markers on the product_catalog page to determine which wrappers the RTD/Cloudflare HTML->Markdown converter strips. Will be removed once the experiment concludes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

HTML->Markdown converters used by AI agents (e.g. the one behind Read the Docs' 'Accept: text/markdown' content negotiation) skip <nav>/<header>/<footer> elements, but only until the first closing tag - nested <nav> elements make them leak most of the sidebar into the converted Markdown (~170 lines of nav noise per page). Restructure the sidebar so each skippable region is a single <nav> with no nested nav/header/footer inside: - main.html: the main_nav wrapper div becomes the one <nav> landmark - nav.html / nav-item.html: inner md-nav elements become <div>s - toc.html: inner group <nav>s become <div>s; the outer wrapper stays <nav> standalone but renders as <div> when embedded in the sidebar Styling and behavior are unchanged: all CSS targets classes and Material's JS targets data-md-component attributes. Also removes the temporary converter probe markup. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The llms.txt spec expects the summary right after the H1 title to be a blockquote. mkdocs-llmstxt emits markdown_description verbatim, so prefix it with '> ' to produce the expected structure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mnocon · 2026-07-21T11:22:01Z

-|`multiple`| true</br>false|Boolean. To allow users to select multiple items.|
-|`translation_domain`|true</br>false|Used for translating choices and placeholder.|
-|`custom_form`|true</br>false|For custom form must be set to true.|
+|`multiple`| true<br>false|Boolean. To allow users to select multiple items.|


</br> is replaced with <br> everywhere in this PR - </br> is not a valid tag and some HTML -> Markdown converters are failing to parse it.

Compare:

Current doc: https://doc.ibexa.co/en/5.0/administration/back_office/back_office_elements/add_dropdowns/index.md (truefalse in the output)
This PR: https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/administration/back_office/back_office_elements/add_dropdowns/index.md (true false in the output)

mnocon · 2026-07-21T11:38:12Z

 | `fieldSettings` | array | Settings of the field (depends on the field type) |
 | `parameters` | hash | Options passed to `ibexa_render_field()` under the `'parameters'` key |
-| `attr` | hash | The attributes to add the generate the HTML markup, passed to ibexa_render_field()` under the `'attr'` key. <br> Contains at least a class entry, containing <fieldtypeidentifier>-field |
+| `attr` | hash | The attributes to add the generate the HTML markup, passed to `ibexa_render_field()` under the `'attr'` key. <br> Contains at least a class entry, containing `<fieldtypeidentifier>-field` |


Small changes here to the formatting as well -as it was wrong.

Compare: https://doc.ibexa.co/en/latest/content_management/field_types/form_and_template/#template-variables:~:text=The%20attributes%20to%20add%20the%20generate%20the%20HTML%20markup%2C%20passed%20to%20ibexa%5Frender%5Ffield%28%29under%20the%27attr%27%60%20key%2E

and https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/content_management/field_types/form_and_template/#template-variables:~:text=The%20attributes%20to%20add%20the%20generate%20the%20HTML%20markup%2C%20passed%20to%20ibexa%5Frender%5Ffield%28%29%20under%20the%20%27attr%27%20key%2E

mnocon · 2026-07-21T11:48:06Z

+        # 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/en/5.0/


Thanks to this change, links to HTML files point to the correct version instead of latest:

Compare (current):
https://doc.ibexa.co/en/latest/api/rest_api/rest_api_usage/rest_api_usage/index.md

This PR:
https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/api/rest_api/rest_api_usage/rest_api_usage/index.md

mnocon · 2026-07-21T11:49:12Z

+        # The "> " prefix renders the description as a blockquote summary,
+        # as expected by the llms.txt spec (https://llmstxt.org)
+        markdown_description: >-
+          > Developer documentation for Ibexa DXP — architecture, APIs, templating,


The spec defines that the description must be specified as a blockquote:
https://afdocs.dev/checks/content-discoverability#how-to-fix-1 , https://llmstxt.org/#format

This PR adds that:
https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/llms.txt

mnocon · 2026-07-21T11:49:42Z

 site_url: https://doc.ibexa.co/en/latest/
 hooks:
    - hooks/edit_uri.py
+    - hooks/eol_status.py


Fixing an incorrect merge - we had a double hooks section, the latter overwrote the former without any warning.

mnocon · 2026-07-21T11:58:12Z

+    (which is present in the served page whether the visible warning applies
+    or not).
+    """
+    current_version = os.environ.get("READTHEDOCS_VERSION_NAME", "")


You can test this locally by running:

export READTHEDOCS_VERSION_NAME=3.3 ~/python/bin/python3.13 -m mkdocs build --strict open site/index.html

The "EOL version warning" should be displayed

mnocon · 2026-07-21T11:59:35Z

            </div>
          {% endif %}
-          {% include "partials/eol_warning.html" %}
+          {% if config.extra.current_version_is_eol %}


Only included when needed

mnocon · 2026-07-21T12:03:25Z

        {% endfor %}

        <div class="{{ ns.bootstrap_extra_css }}">
+          <div style="position:absolute;width:1px;height:1px;clip:rect(0 0 0 0);overflow:hidden">


When testing this (screenshot in ibexa/documentation-user#415), it turns out that the agents trim our the head section when requesting the content, and our Markdown version was not acessible.

See https://afdocs.dev/checks/content-discoverability#llms-txt-directive-html and https://afdocs.dev/checks/content-discoverability#llms-txt-directive-md in the specification for guidelines how to fix this.

It's important that the spec directly mentions this:

Avoid display: none, which some converters strip. The directive should be present in server-rendered HTML; avoid relying solely on client-side JavaScript injection, since most agents fetch pages without executing JS.

(https://agentdocsspec.com/spec/#llms-txt-directive-html)

which would be my first approach - but it's not advised.

mnocon · 2026-07-21T12:05:13Z

+def inject_page_metadata(
+    content: str, description: str = "", editions: list = (), llms_txt_url: str = "/llms.txt"
+) -> str:
+    """Insert the llms.txt pointer, page description, and an 'Editions: X, Y' line after the first h1 heading.


Implements this part of the spec:

https://afdocs.dev/checks/content-discoverability#how-to-fix-6

Result: https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/administration/back_office/back_office_elements/add_dropdowns/index.md#:~:text=%3E%20For%20the%20complete%20documentation%20index%2C%20see%20%5Bllms%2Etxt%5D%28https%3A%2F%2Fdoc%2Eibexa%2Eco%2Fen%2F5%2E0%2Fllms%2Etxt%29%2E

mnocon · 2026-07-21T12:28:28Z

      {{ 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 #}


All the nav > div changes are a result of Fable investigation into the ReadTheDocs HTML -> Markdown converter.

Currently, requesting a Markdown version of the site begins with a long TOC list:

~/Desktop/Sites/v5 main +1 !178 ?30 ❯ curl -H "Accept: text/markdown" https://doc.ibexa.co/en/5.0/administration/back_office/back_office_elements/add_dropdowns/  24.4.0 14:24:40 --- description: Add custom drop down menus to back office interface. --- <!doctype html> [Skip to content ](#add-drop-downs) [Developer Documentation](https://doc.ibexa.co/en/latest/) * Getting started New * Tutorials New * Page and Form tutorial New * Generic field type New * API New * REST API New * [REST API reference ](https://doc.ibexa.co/en/5.0/api/rest%5Fapi/rest%5Fapi%5Freference/rest%5Fapi%5Freference.html) * Extending REST API New * [REST API authentication ](https://doc.ibexa.co/en/5.0/api/rest%5Fapi/rest%5Fapi%5Fauthentication/) * GraphQL New * Event reference New * [Notification channels ](https://doc.ibexa.co/en/5.0/api/notification%5Fchannels/) * Administration New * Dashboard New * Admin panel New * Content organization New ...

Fable investigation:

Can the nav/ToC be removed? Yes — done. Probe experiments on the preview revealed the converter's actual behavior: it skips <nav>/<header>/<footer> subtrees, but only until the first closing tag — it doesn't handle nesting. Material's sidebar nests <nav> inside <nav>, so every inner </nav> ended the skip early and leaked ~170 lines of nav items. (Visibility attributes like hidden/aria-hidden/display:none are ignored entirely, and <aside>/<div> are never skipped.)

This change reworks the navigation so that there are no nested nav tags.

After the changes:

~/Desktop/Sites/v5 main +1 !178 ?30 ❯ curl -H "Accept: text/markdown" https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/administration/back_office/back_office_elements/add_dropdowns/ --- description: Add custom drop down menus to back office interface. --- <!doctype html> [Skip to content ](#add-drop-downs) For AI agents: the complete documentation index is available at [llms.txt](https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/llms.txt); this page is also available as markdown at [index.md](https://ez-systems-developer-documentation--3297.com.readthedocs.build/en/3297/administration/back%5Foffice/back%5Foffice%5Felements/add%5Fdropdowns/index.md). * Documentation > * Administration > * Back office > * Back office elements > * Add drop-downs # Add drop-downs[¶](#add-drop-downs "Permanent link") In Ibexa DXP, you can create a reusable custom drop-down and implement it anywhere in the back office. Follow the steps below to learn how to integrate this component to fit it to your project needs. ## Create `<select>` input[¶](#create-select-input "Permanent link")

The breadcrumbs are still here, but IMHO it's ok for now.

mnocon

Comments for reviewers

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

* AFDocs: Improve docs accessibility for agents * Fix * TEMP: Probe RTD markdown converter element handling Temporary markers on the product_catalog page to determine which wrappers the RTD/Cloudflare HTML->Markdown converter strips. Will be removed once the experiment concludes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * TEMP: Round 2 converter probes with link-rich content Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * AFDocs: Keep sidebar nav out of agent-facing Markdown output HTML->Markdown converters used by AI agents (e.g. the one behind Read the Docs' 'Accept: text/markdown' content negotiation) skip <nav>/<header>/<footer> elements, but only until the first closing tag - nested <nav> elements make them leak most of the sidebar into the converted Markdown (~170 lines of nav noise per page). Restructure the sidebar so each skippable region is a single <nav> with no nested nav/header/footer inside: - main.html: the main_nav wrapper div becomes the one <nav> landmark - nav.html / nav-item.html: inner md-nav elements become <div>s - toc.html: inner group <nav>s become <div>s; the outer wrapper stays <nav> standalone but renders as <div> when embedded in the sidebar Styling and behavior are unchanged: all CSS targets classes and Material's JS targets data-md-component attributes. Also removes the temporary converter probe markup. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * AFDocs: Render llms.txt description as blockquote summary The llms.txt spec expects the summary right after the H1 title to be a blockquote. mkdocs-llmstxt emits markdown_description verbatim, so prefix it with '> ' to produce the expected structure. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Update theme/main.html Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

AFDocs: Improve docs accessibility for agents

06b218a

mnocon and others added 4 commits July 17, 2026 21:21

Fix

990a87e

TEMP: Probe RTD markdown converter element handling

99462dc

Temporary markers on the product_catalog page to determine which wrappers the RTD/Cloudflare HTML->Markdown converter strips. Will be removed once the experiment concludes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

TEMP: Round 2 converter probes with link-rich content

7c5e7b6

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mnocon mentioned this pull request Jul 21, 2026

AFDocs: Improve docs accessibility for agents ibexa/documentation-user#415

Merged

mnocon force-pushed the afdocs branch from e833a38 to d1cf3d2 Compare July 21, 2026 12:41

mnocon marked this pull request as ready for review July 21, 2026 12:42

mnocon commented Jul 21, 2026

View reviewed changes

mnocon added the Needs DOC review label Jul 21, 2026

mnocon requested a review from a team July 21, 2026 12:52

ibexa-workflow-automation-1 Bot requested review from adriendupuis, dabrt and julitafalcondusza and removed request for a team July 21, 2026 12:52

adriendupuis reviewed Jul 21, 2026

View reviewed changes

Comment thread theme/main.html Outdated

adriendupuis approved these changes Jul 21, 2026

View reviewed changes

Update theme/main.html

6797310

Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>

mnocon merged commit 8eb3d97 into 5.0 Jul 22, 2026
12 checks passed

mnocon deleted the afdocs branch July 22, 2026 08:02

Uh oh!

Conversation

mnocon commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Follow Agent-Friendly Documentation spec

ReadTheDocs Markdown conversion

EOL version warning

Hiding the TOC in the Markdown

After the changes

Uh oh!

github-actions Bot commented Jul 17, 2026

Preview of modified files

Uh oh!

github-actions Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mnocon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mnocon commented Jul 17, 2026 •

edited

Loading

github-actions Bot commented Jul 17, 2026 •

edited

Loading