llms.txt follow-ups: resolved site title/description; clean listing-page companions - #535
Merged
Merged
Conversation
A website.title written with qmd markup (raw HTML inlines, shortcodes)
leaked its literal syntax into the llms.txt H1 — the assembler read the
raw project config, while the browser <title> reads the merged page
metadata where ConfigMarkdownTransform has inline-parsed the string and
ShortcodeResolveTransform has resolved it.
Fix in two halves:
- LlmsCaptureTransform stashes the flattened website.title/description
from the merged page metadata as Project artifacts; the llms.txt
assembler prefers them (falling back to raw config for e.g.
all-draft renders). Same data the <title> renders, so no new parsing
and no drift.
- website.description joins MARKDOWN_CONFIG_PATHS (it is presentation
text exactly like website.title), so its markup flattens and its
shortcodes resolve too.
Connect docs verified end-to-end: the H1 is now
'# Connect Documentation Version development' (was raw backtick/
{=html}/shortcode soup), matching the browser title byte-for-byte.
Tests: llms_txt_title_flattens_markup_and_resolves_shortcodes (e2e,
written first and observed red), website_description_scalar_becomes_
inlines (unit). Full workspace suite (12,143) + verify green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
…81o2dh)
Characterization first: L7 placeholder envelopes are raw-HTML comments,
which the llms view already drops — no envelope syntax leaked. What the
companion carried instead was the rendered listing DOM as fenced-div
soup (thumbnail wrappers with empty links, .metadata spans, .listing-*
chrome), and descriptions diverged from the L7-upgraded HTML.
Fix: LlmsCaptureTransform now recognizes a rendered listing container
(div id matching a ResolvedListing from ctx.resolved_listings) and
replaces its contents with a synthesized markdown list:
* [Title](href) (date, author): description
with page-relative links retargeted to .md companions, items in listing
order, and the id kept on a minimal wrapper (float-anchor policy).
Custom-template listings whose container id matches still synthesize;
containers with no matching resolved listing fall through to normal
cleanup.
Tests: llms_listing_page_companion_synthesizes_item_list (e2e, written
first and observed red against the div-soup output) + relativize unit
test. Full workspace suite (12,144) + verify --skip-hub-build green;
real-binary render inspected (companion is the clean list; zero chrome
in llms-full.txt; HTML keeps its full listing DOM).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
cscheid
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two follow-ups to #532, one commit each.
bd-6m1iyxl6 — llms.txt header uses the resolved site title/description
A
website.titlewritten with qmd markup (raw HTML inlines, shortcodes) leaked its literal syntax into the llms.txt H1. Root cause: the assembler read the raw project config (strings stay literal scalars there), while the browser<title>reads the merged page metadata whereConfigMarkdownTransforminline-parses blessed presentation keys andShortcodeResolveTransformresolves them.LlmsCaptureTransformstashes the flattenedwebsite.title/descriptionfrom the merged page metadata as Project artifacts; the assembler prefers them (raw-config fallback for all-draft renders). Same data the<title>renders — no new parsing, no drift.website.descriptionjoinsMARKDOWN_CONFIG_PATHS(presentation text exactly like the already-blessedwebsite.title).# Connect Documentation Version development, byte-identical to the browser title.bd-5w81o2dh — listing-page companions synthesize clean item lists
Characterization overturned the strand's hypothesis: L7 placeholder envelopes are raw-HTML comments, which the llms view already drops — nothing leaked. The real problem was the rendered listing DOM serializing as fenced-div soup (thumbnail wrappers with empty links,
.metadataspans,.listing-*chrome). NowLlmsCaptureTransformmatches a rendered listing container's id againstctx.resolved_listingsand replaces it with a synthesized list:::: {#listing-1} * [First](a.md) (2026-01-15, Alice): First desc. * [Second](b.md) (2026-02-20, Bob): Second desc. :::Page-relative links retargeted to
.mdcompanions, items in listing order, id kept on a minimal wrapper (float-anchor policy); non-matching containers fall through to normal cleanup. The HTML keeps its full listing DOM.Verification
Both fixes TDD (e2e tests written first and observed red) + unit tests (
config_markdowndescription blessing,retarget/relativizehelpers). Full workspace suite (12,144 tests), fmt, clippy,cargo xtask lint,cargo xtask verify --skip-hub-buildgreen; real-binary renders inspected for both.Remaining known gap: llms.txt H2 section headings still read raw sidebar config (bd-3ar95048, p4 — markup there is rare and unobserved in practice).
🤖 Generated with Claude Code