[alexleventer]

The ~300 flyctl command reference pages on docs.fly.io (flyctl/cmd/* in superfly/docs) have no meta description. Mintlify only emits <meta name="description"> from a page's description: frontmatter, and the generator writes title and source_url only. Search Console shows Google writing its own snippets for these pages, and the Ahrefs audit on 2026-10-13 flagged 753 indexable pages without a description across fly.io properties, 304 of them these. Fixing it here rather than in superfly/docs because the sync would overwrite hand edits on the next release.

What changed

doc/main.go now writes a description: built from each command's Short:

---
title: fly apps move
source_url: https://fly.io/docs/flyctl/apps-move/
description: "Reference for fly apps move: move an app to another organization. Usage and flags."
---

• The trailing section list matches what the page actually has: Subcommands, usage and flags. for parent commands, ... and examples. when Example is set.
• A plain capitalized first word is lowercased so it reads naturally after the colon. Acronyms (SSH, MPG), [experimental], Fly and Unmanaged stay as they are.
• Capped at 155 characters. If a description is too long, it drops the section list first, then the "Reference for" lead-in, then cuts Short at a word boundary. No current command gets past the first fallback. Lengths run from 55 to 154, median 87.
• The value is double-quoted, since every description contains : .
• description goes after source_url, so the sidebarTitle that scripts/generate_docs.sh copies onto line 3 still lands right after title.

Verifying

go test ./doc
scripts/generate_docs.sh /path/to/docs/flyctl/cmd   # then git diff in docs

doc/main_test.go is new. It covers the formatting cases and walks the real command tree, checking that every description is ≤155 characters, names its command, and round-trips through YAML.

I ran the generator against current superfly/docs main. The only changes are one added description: line on each page and one real drift line (fly mpg fork now appears in the fly mpg command list). sidebarTitle is preserved on the 35 pages that have one.

🤖 Generated with Claude Code