docs: use description frontmatter so pages reach llms.txt - #2242
Merged
Conversation
GigaHierz
requested review from
karlb and
seolaoh
and removed request for
a team
August 12, 2026 15:04
Contributor
|
needs a rebase |
palango
approved these changes
Aug 13, 2026
Mintlify builds llms.txt summaries from the `description` frontmatter key only. This repo had been using `og:description` almost everywhere, which feeds the Open Graph tag and nothing else, so 269 of the 277 entries in llms.txt were bare title + URL links with no summary. For the 272 pages in docs.json navigation: - Non-legacy pages on `og:description` are renamed to `description`, text preserved verbatim (106 pages). - Non-legacy pages with no description at all get one written from the page content (94 pages). - `legacy/**` keeps `og:description` — deprecated L1 documentation should stay description-less in llms.txt so it isn't surfaced as current guidance. The 15 legacy pages that had neither key get `og:description`. - `home/ramps.mdx` carried both keys; the redundant `og:description` is dropped. 31 pages repeated their description verbatim as the first line of the body. Mintlify renders `description` as a subtitle under the title, so that line is removed to avoid showing the same sentence twice — along with the `---` rule that followed it on 16 of them. The four `tooling/contracts/*` pages are generated, so their frontmatter is changed in the `PAGE_HEADER_*` constants in `scripts/update_contracts.py`; the same change is applied to the `.mdx` files so regenerating is a no-op. `tooling/indexers/goldrush.mdx` had no frontmatter at all and now has `title` and `description`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
GigaHierz
force-pushed
the
GigaHierz/fix-llms-txt-descriptions
branch
from
August 13, 2026 10:54
e82e9c0 to
0e24a70
Compare
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.
Problem
https://docs.celo.org/llms.txtlists 277 pages, but only 8 carry a summary — the rest are bare- [Title](url.md)links.Mintlify builds those summaries from the
descriptionfrontmatter key only. This repo had been usingog:descriptionalmost everywhere, which feeds the Open Graph meta tag and nothing else. The result: LLMs consuming Celo's docs get a link list with no signal about what any page contains.Change
Scope is the 272 pages in
docs.jsonnavigation._deprecated/is not in navigation and does not appear in llms.txt, so it is untouched.og:description→description, text preserved verbatimdescriptionwritten from page contentog:descriptionwrittenog:descriptiondropped from a page carrying both (home/ramps.mdx)legacy/**deliberately stays onog:description: deprecated Celo L1 documentation should remain description-less in llms.txt so it isn't surfaced as current guidance.Notes for reviewers
descriptionas a subtitle under the title, so the sentence would have appeared twice. Those lines are removed, along with the---rule that followed them on 16 pages. No other body content changed — the diff has zero removed lines that aren't a frontmatter key or one of these duplicated sentences.tooling/contracts/{core,l1,fee-currencies,stablecoin}-contracts.mdxcarryDO NOT EDIT THIS FILE MANUALLY. Their frontmatter is changed in thePAGE_HEADER_*constants inscripts/update_contracts.py, with the identical change applied to the.mdxfiles so re-running the generator is a no-op.tooling/indexers/goldrush.mdxhad no frontmatter at all; it now hastitleanddescription. Its existing## GoldRush (powered by Covalent)heading is left in place, matching howcodex.mdxis structured.Verification
descriptionand noog:description; every legacy page hasog:descriptionand nodescription..mdxfiles.npx mintlify broken-links→success no broken links found.npx mint devrenders 200 on spot-checks (/home/wallets,/specs/token-duality,/home/protocol/epoch-rewards/community-fund,/tooling/indexers/goldrush,/legacy/overview), with the deduped pages showing the sentence once.After deploy,
llms.txtshould go from 8 summarized entries to ~215, with the 62legacy/entries still bare.🤖 Generated with Claude Code