+
+
+
elements in table cells.
+ # html.parser silently drops (invalid void-closing tag), so adjacent
+ # blocks have no separator and markdownify concatenates their backticks.
+ for td in soup.find_all(["td", "th"]):
+ children = list(td.children)
+ for i in range(len(children) - 1):
+ curr = children[i]
+ nxt = children[i + 1]
+ if getattr(curr, "name", None) == "code" and getattr(nxt, "name", None) == "code":
+ curr.insert_after(NavigableString(", "))
+
+ for element in soup.find_all("div", attrs={"class": "doc-md-description"}):
+ element.replace_with(NavigableString(element.get_text().strip()))
+
+ for element in soup.find_all("span", attrs={"class": "doc-labels"}):
+ element.decompose()
+
+ # Flatten line-numbered code blocks to a plain , keeping the
+ # language-* class (emitted thanks to pygments_lang_class) on the ,
+ # where markdownify's code_language_callback looks for it.
+ for element in soup.find_all("table", attrs={"class": "highlighttable"}):
+ code_elem = element.find("code")
+ if code_elem:
+ classes = code_elem.get("class") or ()
+ language = next((c for c in classes if c.startswith("language-")), "")
+ attr = f' class="{language}"' if language else ""
+ element.replace_with(
+ Soup(f"{html_module.escape(code_elem.get_text())} ", "html.parser")
+ )
+
+# ---------------------------------------------------------------------------
+# Inline edition badge spans (from snippet includes)
+# ---------------------------------------------------------------------------
+
+def _pill_edition(node) -> str:
+ """Return the edition name of an inline pill span, or '' if not one."""
+ if getattr(node, "name", None) != "span":
+ return ""
+ classes = node.get("class") or []
+ if "pill--inline" not in classes:
+ return ""
+ for pill_cls, edition_name in PILL_CLASS_TO_EDITION.items():
+ if pill_cls in classes:
+ return edition_name
+ return ""
+
+
+def _process_inline_pills(soup: Soup) -> None:
+ """Replace inline edition pill spans with readable text.
+
+ Consecutive pills (possibly separated by whitespace) are merged into a
+ single parenthetical, e.g. ' (Experience, Commerce)' instead of
+ ' (Experience) (Commerce)'.
+ """
+ for span in soup.find_all("span", class_="pill--inline"):
+ if span.parent is None: # already consumed as part of a previous run
+ continue
+ edition = _pill_edition(span)
+ if not edition:
+ continue
+
+ # Collect the run of pills that follow, skipping whitespace between them.
+ editions = [edition]
+ consumed = []
+ node = span.next_sibling
+ pending_whitespace = []
+ while node is not None:
+ if isinstance(node, NavigableString) and not node.strip():
+ pending_whitespace.append(node)
+ node = node.next_sibling
+ continue
+ next_edition = _pill_edition(node)
+ if not next_edition:
+ break
+ editions.append(next_edition)
+ consumed += pending_whitespace + [node]
+ pending_whitespace = []
+ node = node.next_sibling
+
+ for extra_node in consumed:
+ extra_node.extract()
+ span.replace_with(soup.new_string(f" ({', '.join(editions)})"))
+
+
+def _process_release_note_tags(soup: Soup) -> None:
+ """Append edition labels from release-note__tags divs to their preceding heading.
+
+ Release notes use a block after each
+ containing empty elements rendered via CSS.
+ This converts them to a readable parenthetical on the heading, e.g.:
+ ## Google Gemini connector v5.0.7 (Headless, Experience, LTS Update, New feature)
+ """
+ for tags_div in soup.find_all("div", class_="release-note__tags"):
+ editions = []
+ for pill_div in tags_div.find_all("div"):
+ classes = pill_div.get("class", [])
+ for pill_cls, name in PILL_CLASS_TO_EDITION.items():
+ if pill_cls in classes:
+ editions.append(name)
+ break
+
+ heading = tags_div.find_previous_sibling(["h1", "h2", "h3", "h4"])
+ if heading and editions:
+ # Insert before the permalink anchor so it's part of the heading text
+ anchor = heading.find("a", class_="headerlink")
+ label = NavigableString(f" ({', '.join(editions)})")
+ if anchor:
+ anchor.insert_before(label)
+ else:
+ heading.append(label)
+
+ tags_div.decompose()
+
+
+def _process_release_note_dates(soup: Soup) -> None:
+ """Prefix release-note dates with 'Release date: ' so the bare date line stays understandable."""
+ for date_div in soup.find_all("div", class_="release-note__date"):
+ date_text = date_div.get_text(strip=True)
+ if date_text:
+ date_div.string = f"Release date: {date_text}"
+
+
+def _process_info_tiles(soup: Soup) -> None:
+ """Simplify info-tile links to a single clean link text.
+
+ Info tiles have a 'Details' label div and a separate content div.
+ After SVG removal, markdownify produces broken multi-line link text.
+ Replace the whole content with just the meaningful text.
+ """
+ for tile in soup.find_all("a", class_="info-tile"):
+ # The label div ("Details") can be discarded
+ label = tile.find("div", class_="info-tile__details")
+ if label:
+ label.decompose()
+
+ # Flatten remaining content to plain text
+ text = tile.get_text(separator=" ", strip=True)
+ tile.clear()
+ tile.append(soup.new_string(text))
+
+
+# ---------------------------------------------------------------------------
+# Admonitions
+# ---------------------------------------------------------------------------
+
+def _process_admonitions(soup: Soup) -> None:
+ """Convert admonition divs to blockquotes with a bold 'Type: Title' heading.
+
+ Input:
+ Recommended versions
+ Body text...
+
+
+ Output:
+ Caution: Recommended versions
+ Body text...
+
+ """
+ for admonition in soup.find_all("div", class_="admonition"):
+ classes = admonition.get("class", [])
+ admonition_type = next((c for c in classes if c != "admonition"), None)
+
+ title_elem = admonition.find("p", class_="admonition-title")
+ title_text = title_elem.get_text(strip=True) if title_elem else ""
+
+ blockquote = soup.new_tag("blockquote")
+
+ # Bold title paragraph
+ title_p = soup.new_tag("p")
+ strong = soup.new_tag("strong")
+ prefix = f"{admonition_type.capitalize()}: " if admonition_type else ""
+ strong.string = f"{prefix}{title_text}"
+ title_p.append(strong)
+ blockquote.append(title_p)
+
+ # Body: all children except the title
+ for child in list(admonition.children):
+ if child == title_elem:
+ continue
+ blockquote.append(child.extract())
+
+ admonition.replace_with(blockquote)
+
+
+def _process_release_notes_filters(soup: Soup) -> None:
+ """Remove interactive release-notes filter UI elements."""
+ for container in soup.find_all("div", class_="release-notes-filters"):
+ container.decompose()
+
+
+# ---------------------------------------------------------------------------
+# Card macros
+# ---------------------------------------------------------------------------
+
+def _process_cards(soup: Soup) -> None:
+ """Convert card macro HTML structures into markdown-friendly lists with links."""
+ for cards_div in soup.find_all("div", class_=lambda c: c and c.startswith("cards ")):
+ card_wrappers = cards_div.find_all("div", class_="card-wrapper")
+
+ if not card_wrappers:
+ continue
+
+ ul = soup.new_tag("ul")
+
+ for card_wrapper in card_wrappers:
+ link = card_wrapper.find("a", class_="card")
+ if not link:
+ continue
+
+ href = link.get("href", "")
+ if href.startswith("//"):
+ href = "https:" + href
+
+ title_elem = link.find("p", class_="title")
+ description_elem = link.find("p", class_="description")
+
+ if not title_elem:
+ continue
+
+ title = title_elem.get_text(strip=True)
+ description = description_elem.get_text(strip=True) if description_elem else ""
+
+ li = soup.new_tag("li")
+ link_tag = soup.new_tag("a", href=href)
+ link_tag.string = title
+ li.append(link_tag)
+
+ if description:
+ li.append(soup.new_string(": "))
+ li.append(soup.new_string(description))
+
+ ul.append(li)
+
+ cards_div.replace_with(ul)
+
+
+# ---------------------------------------------------------------------------
+# Markdown post-processing (applied by hooks.py to the generated Markdown)
+# ---------------------------------------------------------------------------
+
+def editions_from_frontmatter(frontmatter: dict) -> list:
+ """Map ``edition``/``editions`` frontmatter values to display names."""
+
+ def _to_list(value):
+ if isinstance(value, list):
+ return value
+ if isinstance(value, str):
+ return value.split()
+ return []
+
+ all_editions = _to_list(frontmatter.get("edition")) + _to_list(frontmatter.get("editions") or [])
+ return [FRONTMATTER_EDITION_DISPLAY.get(e, e) for e in all_editions if e]
+
+
+_MACRO_RE = re.compile(r"\[\[=\s*(\w+)\s*=\]\]")
+
+
+def expand_macros(text: str, variables: dict) -> str:
+ """Expand simple ``[[= name =]]`` macro variables (mkdocs-macros syntax).
+
+ Only plain scalar variables are substituted; unknown or complex macros are
+ left untouched so callers can detect and handle them.
+ """
+
+ def _substitute(match: re.Match) -> str:
+ value = variables.get(match.group(1))
+ return str(value) if isinstance(value, (str, int, float)) else match.group(0)
+
+ return _MACRO_RE.sub(_substitute, text)
+
+
+def inject_page_metadata(content: str, description: str = "", editions: list = ()) -> str:
+ """Insert the page description and an 'Editions: X, Y' line after the first h1 heading."""
+ metadata_lines = []
+ if description:
+ metadata_lines += ["", description]
+ if editions:
+ metadata_lines += ["", "Editions: " + ", ".join(editions)]
+ if not metadata_lines:
+ return content
+
+ lines = content.split("\n")
+ for i, line in enumerate(lines):
+ if line.startswith("# "):
+ lines[i + 1:i + 1] = metadata_lines
+ return "\n".join(lines)
+
+ return "\n".join(metadata_lines).lstrip("\n") + "\n\n" + content
+
+
+#  or 
+_IMAGE_RE = re.compile(r'!\[([^\]]*)\]\(([^)\s]+)((?:\s+"[^"]*")?)\)')
+
+
+def absolutize_image_urls(content: str, base_url: str, page_dir: str) -> str:
+ """Rewrite relative image URLs in Markdown to absolute ones.
+
+ The llmstxt plugin makes link hrefs absolute but not image srcs, so the
+ ```` references generated by markdownify keep their
+ page-relative paths, which break in ``llms-full.txt``. This mirrors the
+ URL logic the plugin applies to links.
+
+ ``base_url`` is the site base URL (trailing slash), ``page_dir`` the
+ page's directory relative to the site root (e.g. ``"cdp/cdp"``).
+ """
+
+ def _absolutize(match: re.Match) -> str:
+ alt, url, title = match.groups()
+ if not url.startswith(("/", "#")) and not urlparse(url).scheme:
+ relative_base = urljoin(base_url, page_dir + "/") if page_dir else base_url
+ url = urljoin(relative_base, url)
+ return f""
+
+ return _IMAGE_RE.sub(_absolutize, content)
+
+
+_ORDERED_MARKER_RE = re.compile(r"^(\s*)(\d+)\. (.*)$")
+_FENCE_OPEN_RE = re.compile(r"^(\s*)(`{3,}|~{3,})")
+# Width of an ordered-list marker ("1. ") — mdformat normalizes markers to
+# "1. " and indents item content by exactly this much.
+_MARKER_WIDTH = 3
+
+
+def renumber_ordered_lists(content: str) -> str:
+ """Replace repeated '1.' ordered-list markers with sequential numbers.
+
+ The llmstxt plugin runs mdformat on the converted Markdown, which keeps
+ the first marker of each ordered list (the list's start number) and
+ rewrites all following markers to "1." (its default numbering style).
+ This restores sequential numbers while keeping track of nesting:
+
+ - a stack of (marker indent, counter) pairs tracks open ordered lists;
+ the counter starts at the list's first marker number, so intentional
+ start values (, or literal "2\\." paragraphs in the
+ source) are preserved,
+ - blank lines and lines indented to an item's content column (marker
+ indent + 3) are item continuation and don't interrupt numbering,
+ - a less-indented line closes the lists it's not a continuation of,
+ - fenced code blocks are passed through untouched.
+
+ Known limitations (acceptable for LLM-oriented output): markers of items
+ >= 10 are one character wider than the 3-space content indent, and lists
+ inside blockquotes keep their "1." markers.
+ """
+ lines = content.split("\n")
+ result = []
+ stack = [] # [marker_indent, counter] per open ordered list, outermost first
+ fence = None # (fence_char, fence_length) while inside a fenced code block
+
+ def close_lists(indent: int) -> None:
+ # A line not indented to the content column of an open list closes it.
+ while stack and indent < stack[-1][0] + _MARKER_WIDTH:
+ stack.pop()
+
+ for line in lines:
+ if fence is not None:
+ stripped = line.strip()
+ if stripped and set(stripped) == {fence[0]} and len(stripped) >= fence[1]:
+ fence = None
+ result.append(line)
+ continue
+
+ fence_match = _FENCE_OPEN_RE.match(line)
+ if fence_match:
+ close_lists(len(fence_match.group(1)))
+ marker = fence_match.group(2)
+ fence = (marker[0], len(marker))
+ result.append(line)
+ continue
+
+ if not line.strip():
+ # Blank lines separate loose-list items and item paragraphs; they
+ # never terminate a list on their own in mdformat output.
+ result.append(line)
+ continue
+
+ marker_match = _ORDERED_MARKER_RE.match(line)
+ if marker_match:
+ indent = len(marker_match.group(1))
+ while stack and stack[-1][0] > indent:
+ stack.pop()
+ if stack and stack[-1][0] == indent:
+ stack[-1][1] += 1
+ else:
+ # A new list keeps its first marker number as the start.
+ stack.append([indent, int(marker_match.group(2))])
+ result.append(f"{marker_match.group(1)}{stack[-1][1]}. {marker_match.group(3)}")
+ continue
+
+ close_lists(len(line) - len(line.lstrip()))
+ result.append(line)
+
+ return "\n".join(result)
diff --git a/mkdocs.yml b/mkdocs.yml
index 0dae097323..1ad95f0365 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1091,6 +1091,9 @@ markdown_extensions:
- pymdownx.highlight:
guess_lang: false
linenums: true
+ # Emit language-* classes so the Markdown conversion (llmstxt) can
+ # restore the language on fenced code blocks.
+ pygments_lang_class: true
extend_pygments_lang:
- name: php
lang: php
@@ -1107,3 +1110,6 @@ markdown_extensions:
custom_checkbox: true
- pymdownx.tilde
- pymdownx.details
+
+hooks:
+ - hooks.py
diff --git a/plugins.yml b/plugins.yml
index bb7c1d7725..d553812608 100644
--- a/plugins.yml
+++ b/plugins.yml
@@ -592,3 +592,14 @@ plugins:
'ai_actions/extend_ai_actions.md': 'ai/ai_actions/extend_ai_actions.md'
'cdp/cdp_activation/cdp_add_clientside_tracking.md': 'cdp/cdp_activation/cdp_add_tracking.md'
+
+
+ - llmstxt:
+ preprocess: llmstxt_preprocess.py
+
+ autoclean: false
+ full_output: llms-full.txt
+ sections:
+ # Built automatically when running MkDocs build based on MkDocs nav configuration, don't change
+ Ibexa DXP developer documentation:
+ - index.md
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 0000000000..5b197e276e
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,2 @@
+[pytest]
+testpaths = tests/python
diff --git a/requirements-dev.txt b/requirements-dev.txt
new file mode 100644
index 0000000000..1d592acc1d
--- /dev/null
+++ b/requirements-dev.txt
@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest==8.*
diff --git a/requirements.txt b/requirements.txt
index c271f19622..eb13f097ff 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -7,3 +7,4 @@ mkdocs-macros-plugin==1.3.7
mkdocs-redirects==1.2.2
mkdocs-autolinks-plugin==0.7.1
Jinja2==3.1.6
+mkdocs-llmstxt
diff --git a/tests/python/conftest.py b/tests/python/conftest.py
new file mode 100644
index 0000000000..b9018a2f6b
--- /dev/null
+++ b/tests/python/conftest.py
@@ -0,0 +1,5 @@
+import sys
+from pathlib import Path
+
+# Make repo-root modules (llmstxt_preprocess.py) importable.
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
diff --git a/tests/python/test_image_urls.py b/tests/python/test_image_urls.py
new file mode 100644
index 0000000000..d81118c173
--- /dev/null
+++ b/tests/python/test_image_urls.py
@@ -0,0 +1,54 @@
+from llmstxt_preprocess import absolutize_image_urls
+
+BASE = "https://doc.ibexa.co/en/latest/"
+
+
+def test_relative_src_resolved_against_page_dir():
+ content = ""
+ assert absolutize_image_urls(content, BASE, "cdp/cdp") == (
+ ""
+ )
+
+
+def test_parent_relative_src():
+ content = ""
+ assert absolutize_image_urls(content, BASE, "cdp/cdp") == (
+ ""
+ )
+
+
+def test_root_page_uses_base_url():
+ content = ""
+ assert absolutize_image_urls(content, BASE, ".") == (
+ ""
+ )
+
+
+def test_already_absolute_url_untouched():
+ content = ""
+ assert absolutize_image_urls(content, BASE, "cdp/cdp") == content
+
+
+def test_site_absolute_path_untouched():
+ # Matches the plugin's behavior for link hrefs starting with "/".
+ content = ""
+ assert absolutize_image_urls(content, BASE, "cdp/cdp") == content
+
+
+def test_title_preserved():
+ content = ''
+ assert absolutize_image_urls(content, BASE, "a/b") == (
+ ''
+ )
+
+
+def test_multiple_images_and_surrounding_text():
+ content = "Before  middle  after"
+ result = absolutize_image_urls(content, BASE, "dir")
+ assert "" in result
+ assert "" in result
+
+
+def test_regular_links_untouched():
+ content = "[A link](img/x.png) and text"
+ assert absolutize_image_urls(content, BASE, "dir") == content
diff --git a/tests/python/test_page_metadata.py b/tests/python/test_page_metadata.py
new file mode 100644
index 0000000000..5029316e42
--- /dev/null
+++ b/tests/python/test_page_metadata.py
@@ -0,0 +1,74 @@
+from llmstxt_preprocess import (
+ editions_from_frontmatter,
+ expand_macros,
+ inject_page_metadata,
+)
+
+
+def test_editions_inserted_after_first_h1():
+ content = "# Title\n\nBody text."
+ assert inject_page_metadata(content, editions=["Commerce"]) == (
+ "# Title\n\nEditions: Commerce\n\nBody text."
+ )
+
+
+def test_description_inserted_after_first_h1():
+ content = "# Title\n\nBody text."
+ assert inject_page_metadata(content, description="Configure the Storefront.") == (
+ "# Title\n\nConfigure the Storefront.\n\nBody text."
+ )
+
+
+def test_description_comes_before_editions():
+ content = "# Title\n\nBody text."
+ assert inject_page_metadata(content, description="A description.", editions=["Commerce"]) == (
+ "# Title\n\nA description.\n\nEditions: Commerce\n\nBody text."
+ )
+
+
+def test_prepended_when_no_h1():
+ content = "Body text."
+ assert inject_page_metadata(content, description="A description.", editions=["Commerce"]) == (
+ "A description.\n\nEditions: Commerce\n\nBody text."
+ )
+
+
+def test_no_metadata_leaves_content_unchanged():
+ content = "# Title\n\nBody text."
+ assert inject_page_metadata(content) == content
+ assert inject_page_metadata(content, description="", editions=[]) == content
+
+
+def test_frontmatter_edition_string():
+ assert editions_from_frontmatter({"edition": "commerce experience"}) == ["Commerce", "Experience"]
+
+
+def test_frontmatter_editions_list():
+ assert editions_from_frontmatter({"editions": ["headless", "lts-update"]}) == ["Headless", "LTS Update"]
+
+
+def test_frontmatter_edition_and_editions_merged():
+ result = editions_from_frontmatter({"edition": "commerce", "editions": ["headless"]})
+ assert result == ["Commerce", "Headless"]
+
+
+def test_unknown_edition_passes_through():
+ assert editions_from_frontmatter({"edition": "custom"}) == ["custom"]
+
+
+def test_empty_frontmatter():
+ assert editions_from_frontmatter({}) == []
+
+
+def test_expand_macros_substitutes_scalars():
+ variables = {"product_name": "Ibexa DXP", "product_name_cdp": "Ibexa CDP"}
+ assert expand_macros("Install [[= product_name_cdp =]] with [[= product_name =]].", variables) == (
+ "Install Ibexa CDP with Ibexa DXP."
+ )
+
+
+def test_expand_macros_leaves_unknown_untouched():
+ assert expand_macros("Uses [[= unknown_var =]].", {}) == "Uses [[= unknown_var =]]."
+ # Complex expressions are not simple variables — left for the caller to detect.
+ text = "See [[= include_file('x.md') =]]."
+ assert expand_macros(text, {"include_file": "nope"}) == text
diff --git a/tests/python/test_preprocess.py b/tests/python/test_preprocess.py
new file mode 100644
index 0000000000..d8ef5e96bf
--- /dev/null
+++ b/tests/python/test_preprocess.py
@@ -0,0 +1,208 @@
+import mdformat
+from bs4 import BeautifulSoup
+from mkdocs_llmstxt._internal.plugin import _converter
+
+import llmstxt_preprocess
+from llmstxt_preprocess import renumber_ordered_lists
+
+
+def to_markdown(html: str) -> str:
+ """Replicate the mkdocs-llmstxt conversion pipeline for a HTML snippet.
+
+ Uses the plugin's own MarkdownConverter instance so options (bullets,
+ heading style, code language callback) always match what ships.
+ """
+ soup = BeautifulSoup(html, "html.parser")
+ llmstxt_preprocess.preprocess(soup, "")
+ return mdformat.text(
+ _converter.convert_soup(soup),
+ options={"wrap": "no"},
+ extensions=("tables",),
+ )
+
+
+def preprocessed(html: str) -> BeautifulSoup:
+ soup = BeautifulSoup(html, "html.parser")
+ llmstxt_preprocess.preprocess(soup, "")
+ return soup
+
+
+def test_checkmark_only_cell_becomes_yes():
+ html = "Feature Included Search ✔
"
+ result = to_markdown(html)
+ assert "✔" not in result
+ assert "| Yes" in result
+
+
+def test_checkmark_mixed_with_other_nodes():
+ html = "H ✔ option
"
+ result = to_markdown(html)
+ assert "Yes `option`" in result
+
+
+def test_release_note_date_gets_prefix():
+ html = 'Connector v5.0.7
2026-04-20'
+ assert "Release date: 2026-04-20" in to_markdown(html)
+
+
+def test_release_note_tags_appended_to_heading():
+ html = (
+ 'Connector v5.0.7¶
'
+ '"
+ )
+ assert "## Connector v5.0.7 (Headless, Experience)" in to_markdown(html)
+
+
+def test_admonition_becomes_blockquote():
+ html = (
+ ''
+ 'Recommended versions
'
+ "Body text.
"
+ ""
+ )
+ result = to_markdown(html)
+ assert "> **Caution: Recommended versions**" in result
+ assert "> Body text." in result
+
+
+def test_tabbed_set_labels_become_bold_text():
+ html = (
+ ''
+ ''
+ ''
+ 'Content A
'
+ 'Content B
'
+ ""
+ )
+ result = to_markdown(html)
+ assert "**Tab A**\n\nContent A\n\n**Tab B**\n\nContent B" in result
+
+
+def test_cards_become_link_list():
+ html = (
+ '"
+ )
+ assert "- [Page title](https://example.com/page/): Page description" in to_markdown(html)
+
+
+def test_inline_pill_becomes_parenthetical():
+ html = 'Feature is available.
'
+ assert "Feature (Experience) is available." in to_markdown(html)
+
+
+def test_adjacent_inline_pills_merged():
+ # Structure from update_from_5.0: pills separated by a space in a heading.
+ html = (
+ 'Database update '
+ ' '
+ ''
+ '¶
'
+ )
+ result = to_markdown(html)
+ assert "### Database update (Experience, Commerce)" in result
+ assert ") (" not in result
+
+
+def test_three_adjacent_inline_pills_merged():
+ html = (
+ "Feature"
+ ' '
+ ' '
+ ' is available.
'
+ )
+ assert "Feature (Headless, Experience, Commerce) is available." in to_markdown(html)
+
+
+def test_ol_start_attribute_preserved():
+ # (a list interrupted by other content) keeps its numbering.
+ html = "- a
- b
note
- c
- d
"
+ result = renumber_ordered_lists(to_markdown(html))
+ assert "1. a\n2. b" in result
+ assert "3. c\n4. d" in result
+
+
+def test_escaped_literal_numbers_keep_their_value():
+ # 'N\.' paragraphs in the source render as plain text and must keep N.
+ html = "2. To expose a single catalog to all users:
"
+ assert renumber_ordered_lists(to_markdown(html)).startswith("2. To expose")
+
+
+def test_info_tile_flattened_to_link_text():
+ html = (
+ ''
+ 'Details'
+ "Meaningful text"
+ ""
+ )
+ assert "[Meaningful text](page/)" in to_markdown(html)
+
+
+def test_image_with_alt_kept_as_markdown_image():
+ assert "" in to_markdown('
')
+ # Images without a description tell an AI agent nothing — dropped.
+ assert to_markdown('').strip() == ""
+
+
+def test_headerlink_removed():
+ html = 'Title¶
'
+ assert to_markdown(html).strip() == "## Title"
+
+
+def test_headerlink_after_image_removed():
+ html = (
+ '
'
+ 'How it works'
+ '¶
'
+ )
+ result = to_markdown(html)
+ assert "" in result
+ assert "## How it works" in result
+ assert "Permanent link" not in result
+ assert "¶" not in result
+
+
+def test_image_wrapping_link_unwrapped():
+ # Lightbox-style links around images are unwrapped to a plain image.
+ html = '
Kept
'
+ result = to_markdown(html)
+ assert "" in result
+ assert "[![" not in result
+ assert "Kept" in result
+
+
+def test_line_numbered_code_block_keeps_language():
+ # Structure emitted by pymdownx.highlight with linenums + pygments_lang_class.
+ html = (
+ ''
+ '1'
+ 'apt-get install composer\n'
+ "
"
+ )
+ result = to_markdown(html)
+ assert "```bash\napt-get install composer\n```" in result
+ # Line numbers must not leak into the output.
+ assert "\n1\n" not in result
+
+
+def test_line_numbered_code_block_without_language():
+ html = (
+ ''
+ 'plain text\n
"
+ )
+ result = to_markdown(html)
+ assert "```\nplain text\n```" in result
+
+
+def test_release_notes_filters_removed():
+ html = 'Kept
'
+ result = to_markdown(html)
+ assert "Filter" not in result
+ assert "Kept" in result
diff --git a/tests/python/test_renumber.py b/tests/python/test_renumber.py
new file mode 100644
index 0000000000..12e1a403fe
--- /dev/null
+++ b/tests/python/test_renumber.py
@@ -0,0 +1,138 @@
+from llmstxt_preprocess import renumber_ordered_lists
+
+
+def test_flat_list():
+ assert renumber_ordered_lists("1. one\n1. two\n1. three") == "1. one\n2. two\n3. three"
+
+
+def test_nested_bullets_do_not_reset_numbering():
+ content = "\n".join([
+ "1. Sets a variable with the desired Varnish version",
+ "1. Copies and customizes `parameters.vcl` file:",
+ " - sets `web` container as the backend host",
+ ' - adds "all IPs" CIDR notation to `debuggers` list',
+ " - on Varnish 7, enable logging of access control list matching",
+ "1. Sets main `varnish*.vcl` file to use",
+ "1. Copies the main VCL file",
+ "1. Sets the Varnish version to use",
+ "1. Adds the Varnish container",
+ "1. Sets Varnish as the HTTP cache server",
+ "1. Restarts the DDEV cluster",
+ ])
+ result = renumber_ordered_lists(content)
+ markers = [line.split(".")[0] for line in result.split("\n") if not line.startswith(" ")]
+ assert markers == ["1", "2", "3", "4", "5", "6", "7", "8"]
+ # Nested bullets are untouched
+ assert " - sets `web` container as the backend host" in result
+
+
+def test_nested_ordered_lists():
+ content = "\n".join([
+ "1. a",
+ " 1. a1",
+ " 1. a2",
+ "1. b",
+ " 1. b1",
+ ])
+ expected = "\n".join([
+ "1. a",
+ " 1. a1",
+ " 2. a2",
+ "2. b",
+ " 1. b1",
+ ])
+ assert renumber_ordered_lists(content) == expected
+
+
+def test_loose_list_keeps_numbering_across_blank_lines():
+ content = "1. first\n\n1. second\n\n1. third"
+ assert renumber_ordered_lists(content) == "1. first\n\n2. second\n\n3. third"
+
+
+def test_continuation_paragraph_keeps_numbering():
+ content = "1. first\n\n continuation paragraph\n\n1. second"
+ assert renumber_ordered_lists(content) == "1. first\n\n continuation paragraph\n\n2. second"
+
+
+def test_fence_inside_item_keeps_numbering_and_content():
+ content = "\n".join([
+ "1. first",
+ "",
+ " ```bash",
+ " 1. not a marker",
+ " echo hi",
+ " ```",
+ "",
+ "1. second",
+ ])
+ result = renumber_ordered_lists(content)
+ assert " 1. not a marker" in result
+ assert result.endswith("2. second")
+
+
+def test_top_level_fence_resets_list():
+ content = "\n".join([
+ "1. first",
+ "1. second",
+ "",
+ "```text",
+ "1. fake",
+ "```",
+ "",
+ "1. new list",
+ ])
+ result = renumber_ordered_lists(content).split("\n")
+ assert result[0] == "1. first"
+ assert result[1] == "2. second"
+ assert result[4] == "1. fake" # fence content untouched
+ assert result[7] == "1. new list"
+
+
+def test_top_level_paragraph_resets_list():
+ content = "1. first\n1. second\n\nA paragraph.\n\n1. new list"
+ assert renumber_ordered_lists(content) == "1. first\n2. second\n\nA paragraph.\n\n1. new list"
+
+
+def test_keeps_start_number_and_is_idempotent():
+ # mdformat keeps the first marker (the list's start) and rewrites the
+ # rest to "1." — the start must survive renumbering.
+ assert renumber_ordered_lists("4. a\n1. b\n1. c") == "4. a\n5. b\n6. c"
+ assert renumber_ordered_lists("3. a\n7. b") == "3. a\n4. b"
+ content = "1. one\n1. two\n - bullet\n1. three"
+ once = renumber_ordered_lists(content)
+ assert renumber_ordered_lists(once) == once
+ assert renumber_ordered_lists("4. a\n5. b\n6. c") == "4. a\n5. b\n6. c"
+
+
+def test_intentional_paragraph_numbers_kept():
+ # Sources sometimes use escaped literal numbers ("1\.", "2\.") that end up
+ # as separate single-item lists in the converted Markdown — their numbers
+ # are intentional and must not be reset to 1.
+ content = "\n".join([
+ "1. All products available for all users:",
+ "",
+ "```yaml",
+ "catalog: ~",
+ "```",
+ "",
+ "2. To expose a single catalog:",
+ "",
+ "```yaml",
+ "catalog: custom_catalog",
+ "```",
+ "",
+ "3. Specific catalog for the defined customer group",
+ ])
+ assert renumber_ordered_lists(content) == content
+
+
+def test_escaped_number_is_not_a_marker():
+ content = "1\\. not a list"
+ assert renumber_ordered_lists(content) == content
+
+
+def test_tilde_fence_and_unclosed_fence():
+ content = "~~~\n1. fake\n~~~"
+ assert renumber_ordered_lists(content) == content
+ unclosed = "```\n1. fake\n1. still fake"
+ assert renumber_ordered_lists(unclosed) == unclosed
diff --git a/theme/assets/page-actions.js b/theme/assets/page-actions.js
new file mode 100644
index 0000000000..ea34914d80
--- /dev/null
+++ b/theme/assets/page-actions.js
@@ -0,0 +1,55 @@
+/**
+ * Page Actions JavaScript
+ * Handles functionality for page action buttons (Copy as Markdown, View as Markdown, Edit on GitHub)
+ */
+
+async function copyPageForLLM() {
+ const mdPath = document.querySelector('meta[name="markdown-path"]').content;
+
+ try {
+ const response = await fetch(mdPath);
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+ const markdownContent = await response.text();
+ await navigator.clipboard.writeText(markdownContent);
+ showButtonFeedback('success', 'Copied!');
+ } catch (error) {
+ console.error('Failed to copy content:', error);
+ window.open(mdPath, '_blank');
+ showButtonFeedback('info', 'Opened in tab');
+ }
+}
+
+function showButtonFeedback(type, message) {
+ const button = document.querySelector('button[onclick="copyPageForLLM()"]');
+ if (!button) return;
+
+ const originalHTML = button.innerHTML;
+ button.innerHTML = `${message}`;
+
+ if (type === 'success') {
+ button.classList.add('page-action-btn--success');
+ } else if (type === 'info') {
+ button.classList.add('page-action-btn--info');
+ }
+
+ setTimeout(() => {
+ button.innerHTML = originalHTML;
+ button.classList.remove('page-action-btn--success', 'page-action-btn--info');
+ }, 2000);
+}
+
+document.addEventListener('DOMContentLoaded', function() {
+ const pageActions = document.getElementById('page-actions');
+ const firstH1 = document.querySelector('.bootstrap-iso h1, h1');
+
+ if (pageActions && firstH1) {
+ // If h1 is inside a special header container (e.g. release-notes-header),
+ // insert page-actions after that container so it doesn't disrupt the header layout.
+ const headerContainer = firstH1.closest('.release-notes-header');
+ const anchor = headerContainer || firstH1;
+ anchor.insertAdjacentElement('afterend', pageActions);
+ pageActions.classList.add('page-actions--visible');
+ }
+});
diff --git a/theme/main.html b/theme/main.html
index 66ce7dc87d..cf88c5c920 100644
--- a/theme/main.html
+++ b/theme/main.html
@@ -13,6 +13,23 @@
+
+ {% if config.repo_url and page.edit_url %}
+
+
+ {% endif %}
+
+
+
+
+
+ {% if page and not page.meta.exclude_from_llmstxt %}
+ {% set md_href = page.file.dest_uri | replace('.html', '.md') %}
+
+ {% endif %}
+
+
+
{% endblock %}
{% block site_nav %}
{% if nav %}
@@ -75,7 +92,36 @@
{% endif %}
{% include "partials/eol_warning.html" %}
- {{ page.content }}
+
+
+ {{ page.content }}
+
+
+ {% if config.repo_url and page.edit_url and not page.is_homepage and not page.meta.exclude_from_llmstxt %}
+
+ {% endif %}
+
+
{% include "partials/tags.html" %}
{% endblock %}
diff --git a/theme/partials/header.html b/theme/partials/header.html
index ba5ca0931d..80a4345297 100644
--- a/theme/partials/header.html
+++ b/theme/partials/header.html
@@ -20,10 +20,5 @@
{% include ".icons/material/magnify.svg" %}
{% include "partials/search.html" %}
- {% if config.repo_url %}
-
- {% include "partials/source.html" %}
-
- {% endif %}
diff --git a/theme/partials/source.html b/theme/partials/source.html
deleted file mode 100644
index 0948754c07..0000000000
--- a/theme/partials/source.html
+++ /dev/null
@@ -1,7 +0,0 @@
-{% import "partials/language.html" as lang with context %}
-
-
- View on GitHub
-
diff --git a/update_llmstxt_config.py b/update_llmstxt_config.py
new file mode 100644
index 0000000000..b232392c38
--- /dev/null
+++ b/update_llmstxt_config.py
@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""
+Update the llmstxt plugin configuration in plugins.yml based on mkdocs.yml nav structure.
+This script converts the mkdocs navigation into a format suitable for the llmstxt plugin.
+
+Files can be excluded from the llmstxt output by adding the following to their YAML frontmatter:
+
+ exclude_from_llmstxt: true
+
+This excludes the page from both llms.txt and llms-full.txt, skips generating its Markdown
+version, and hides the page action buttons. There is no per-file control for excluding a page
+from llms.txt only (both files are derived from the same `sections` config).
+Files without this property are included by default.
+"""
+
+import re
+import yaml
+from pathlib import Path
+
+
+def read_frontmatter(file_path):
+ """
+ Parse YAML frontmatter from a markdown file.
+ Returns a dict of frontmatter values, or an empty dict if none is found.
+ Handles files that begin with HTML comments before the frontmatter block.
+ """
+ try:
+ content = Path(file_path).read_text(encoding='utf-8')
+ except (OSError, UnicodeDecodeError):
+ return {}
+
+ # Strip leading HTML comments (e.g. )
+ content = re.sub(r'\A(\s*\s*)+', '', content, flags=re.DOTALL)
+
+ if not content.startswith('---'):
+ return {}
+
+ end = content.find('\n---', 3)
+ if end == -1:
+ return {}
+
+ try:
+ return yaml.safe_load(content[3:end]) or {}
+ except yaml.YAMLError:
+ return {}
+
+
+def is_excluded(file_path, docs_dir):
+ """
+ Return True if the file has 'exclude_from_llmstxt: true' in its frontmatter.
+ file_path is relative to docs_dir (as written in mkdocs nav).
+ """
+ full_path = Path(docs_dir) / file_path
+ fm = read_frontmatter(full_path)
+ return fm.get('exclude_from_llmstxt', False) is True
+
+
+def convert_nav_to_llmstxt_sections(nav_list, docs_dir):
+ """
+ Convert mkdocs nav list to llmstxt sections format.
+ Returns a dict mapping top-level section names to flat lists of file paths.
+ Files with 'exclude_from_llmstxt: true' in their frontmatter are skipped.
+ Sections that contain no remaining files are omitted.
+ """
+ sections = {}
+
+ def extract_files(item):
+ """Recursively extract included file paths from a nav item."""
+ files = []
+ if isinstance(item, str):
+ if not item.endswith('.html') and not is_excluded(item, docs_dir):
+ files.append(item)
+ elif isinstance(item, list):
+ for subitem in item:
+ files.extend(extract_files(subitem))
+ elif isinstance(item, dict):
+ for value in item.values():
+ if isinstance(value, str):
+ if not value.endswith('.html') and not is_excluded(value, docs_dir):
+ files.append(value)
+ elif isinstance(value, list):
+ for subitem in value:
+ files.extend(extract_files(subitem))
+ return files
+
+ for item in nav_list:
+ if isinstance(item, dict):
+ for section_name, section_content in item.items():
+ files = extract_files({section_name: section_content})
+ if files:
+ sections[section_name] = files
+ elif isinstance(item, str):
+ if not item.endswith('.html') and not is_excluded(item, docs_dir):
+ sections.setdefault('Ibexa Developer Documentation', []).append(item)
+
+ return sections
+
+
+def update_plugins_yml(plugins_path, mkdocs_path):
+ """
+ Update the llmstxt plugin configuration in plugins.yml based on mkdocs.yml nav.
+ """
+ with open(plugins_path, 'r') as f:
+ plugins_data = yaml.safe_load(f)
+
+ with open(mkdocs_path, 'r') as f:
+ mkdocs_data = yaml.safe_load(f)
+
+ # docs/ directory is resolved relative to mkdocs.yml location
+ docs_dir = Path(mkdocs_path).parent / mkdocs_data.get('docs_dir', 'docs')
+
+ nav = mkdocs_data.get('nav', [])
+ new_sections = convert_nav_to_llmstxt_sections(nav, docs_dir)
+
+ plugins_list = plugins_data.get('plugins', [])
+ for plugin in plugins_list:
+ if isinstance(plugin, dict) and 'llmstxt' in plugin:
+ plugin['llmstxt']['sections'] = new_sections
+ print(f"✓ Updated llmstxt plugin configuration")
+ print(f" Total sections: {len(new_sections)}")
+ break
+ else:
+ print("✗ llmstxt plugin not found in plugins.yml")
+ return False
+
+ with open(plugins_path, 'w') as f:
+ yaml.dump(plugins_data, f, default_flow_style=False, sort_keys=False,
+ allow_unicode=True, width=120)
+
+ print(f"✓ Updated {plugins_path}")
+ return True
+
+
+if __name__ == '__main__':
+ script_dir = Path(__file__).parent
+ plugins_path = script_dir / 'plugins.yml'
+ mkdocs_path = script_dir / 'mkdocs.yml'
+
+ if not plugins_path.exists():
+ print(f"✗ plugins.yml not found at {plugins_path}")
+ exit(1)
+
+ if not mkdocs_path.exists():
+ print(f"✗ mkdocs.yml not found at {mkdocs_path}")
+ exit(1)
+
+ print("Updating llmstxt configuration...")
+ print(f"Reading from: {mkdocs_path}")
+ print(f"Updating: {plugins_path}")
+ print()
+
+ success = update_plugins_yml(plugins_path, mkdocs_path)
+ exit(0 if success else 1)
