celo-org / celo-org/docs

Migrate frontmatter og:description to description on non-legacy pages

Open
#2,239 0 comments 0 reactions 0 assignees View on GitHub
chore documentation follow-up help wanted priority:low size:S
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.