Migrate frontmatter og:description to description on non-legacy pages
- Dominant language
- MDX
- Stars
- 90
- Forks
- 382
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 35
Description
Follow-up from #2237.
## Problem
**97% of `llms.txt` entries have no description.** 8 of 264 entries carry one; the rest are bare title + link. An AI assistant reading the index gets titles only, with no signal about what any page covers — which makes it fetch the wrong pages, or too many.
## Root cause
Mintlify's `llms.txt` generator reads only `description:` and **ignores `og:description:`**.
Per Mintlify's SEO reference, `og:description` sets the OpenGraph tag only and "falls back to `description`" — it is purely additive and does not set the page meta description.
Confirmed empirically in this repo: `home/ramps.mdx` has **both** fields, and its `llms.txt` entry uses the `description:` value, not the `og:description:` one.
So 125 non-legacy pages already have perfectly good description text that is being silently dropped.
## Current state
In-nav pages, excluding `_deprecated/`:
| Frontmatter | Count |
|---|---|
| `description:` | 8 |
| `og:description:` only | 171 (125 non-legacy / 46 legacy) |
| neither | 102 non-legacy |
## Policy to adopt
- **Non-legacy pages → `description:`**
- **`legacy/**` pages → keep `og:description:`**
The legacy split is deliberate, not an oversight: legacy L1 documentation should stay description-less in `llms.txt` so LLMs don't surface it as current guidance.
**This supersedes the previous "always use `og:description:`" convention**, which predated the llms.txt work.
## Work
1. **The 7 `build-on-celo/` pages with no description at all** (highest traffic, needs new copy):
- `build-on-celo/quickstart`
- `build-on-celo/cel2-architecture`
- `build-on-celo/build-with-ai/overview`
- `build-on-celo/build-with-ai/x402`
- `build-on-celo/build-with-ai/8004`
- `build-on-celo/build-with-ai/mpp`
- `build-on-celo/build-with-ai/mcp/celo-mcp`
2. **The 125 non-legacy renames** — mechanical `og:description:` → `description:`.
3. **Remaining zero-description clusters** — all 16 `specs/*`, `infra-partners/operators|notices/archive/*`, `tooling/libraries-sdks/cli/*`, `tooling/indexers/*`, plus `home/index`, `home/history`, `home/exchanges`, `home/gas-fees`, `contribute-to-celo/index`.
Minor fix to pick up along the way: `build-on-celo/index.mdx` has a double space in `og:description: A guide for building on Celo.`
## Verifying
```bash
# count entries carrying a description
curl -s https://docs.celo.org/llms.txt | grep -c '\.md): '
# currently 8; should reach ~160 after step 2, ~215 after step 3
```
Contributor guide
Research direction
Start by inspecting the listed build-on-celo pages and the non-legacy frontmatter entries, excluding legacy/**. Rename eligible og:description fields to description, add copy for the seven named pages, handle the remaining zero-description clusters, and fix the double space in build-on-celo/index.mdx. Verify with the provided curl and grep command; the description count should rise to about 215.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100