docs: generate per-problem docs pages

Co-Authored-By: Claude <noreply@anthropic.com>

Author: wislertt

.dev/active/01-docs-seo/context.md

@@ -0,0 +1,94 @@
+# Context: Docs Site SEO — leetcode-py
+
+Companion to a future `tasks.md` (checklist). This file holds everything an agent needs to plan SEO work: verified live findings, known bug classes, transferable decisions from the bakefile repo's completed SEO pass, and the opportunities specific to this repo. Dates are absolute. Verify anything marked "verify" against the live site before acting — this reflects 2026-08-24 state.
+
+## Project facts
+
+- Repo: `github.com/wislertt/leetcode-py`, main branch `main`.
+- Product: Python package that generates LeetCode practice environments (problem README, typed solution stub, parametrized pytest suite with 10+ cases, helpers, playground notebook) from JSON templates.
+- PyPI package name: `leetcode-py-sdk` (NOT `leetcode-py`). CLI: `lcpy`.
+- Scale: 307 problems under `leetcode/`, six collections (Grind 75, Grind, Blind 75, NeetCode 150, NeetCode 250, AlgoMaster 75).
+- Author: Wisaroot Lertthaweedech (`wisl.dev`). Same author as bakefile (`bakefile.wisl.dev`).
+- Docs: Mintlify site at `https://leetcode-py.wisl.dev` (custom domain; default deployment host `leetcode-py.mintlify.app`).
+
+## Docs stack and conventions
+
+- Mintlify, `docs/docs.json` at root of `docs/`. Theme `mint`. Site name `leetcode-py` (rendered title suffix is ` - leetcode-py`, 14 chars, so frontmatter titles must stay ≤~46 chars).
+- `docs/skill.md` is hand-written, served raw at `/skill.md`, overrides Mintlify's auto-generated one. Do not delete, no MDX-only components in it.
+- `markdown.instructions` in docs.json is injected into `llms.txt`, `llms-full.txt`, and Markdown page exports.
+- **Catalog pages are GENERATED** by `scripts/gen_catalog.py` (`docs/catalog/*.mdx` carry "GENERATED — do not edit" headers). Any change to catalog content = edit the generator, not the mdx.
+- Docs verification command: `bake docs-check` (runs `mintlify broken-links`). `bake docs` runs the dev server. Both defined in `bakefile.py`.
+- Examples policy: docs examples are backed by tests, copy verbatim from tested sources.
+
+## Verified live state (2026-08-24)
+
+Checked directly against production:
+
+- `robots.txt`: Mintlify default, clean. AI bots allowed, `Content-Signal: ai-train=yes, search=yes, ai-input=yes`. Do not replace.
+- `sitemap.xml`: auto-generated, 21 pages, fresh `lastmod`.
+- `llms.txt`: HTTP 200.
+- Canonical: set globally (`https://leetcode-py.wisl.dev`).
+- Organization schema with `sameAs` (GitHub, PyPI, wisl.dev).
+- PyPI `[project.urls]` links to docs site (dofollow backlink).
+- README links deeply into docs pages (collections, why-page, CLI guide).
+
+## Known bugs (same class as bakefile, verified live 2026-08-24)
+
+1. **Duplicated title tag.** Homepage renders `<title>leetcode-py - leetcode-py</title>` (page title + site name identical). Fix: give `docs/index.mdx` a keyword title, e.g. "LeetCode practice environments in Python" or similar; the suffix carries the brand.
+2. **og:image resolves to wrong host.** Meta emits `https://leetcode-py.mintlify.app/img/brand/og-card-light.png` (default deployment host) because `seo.metatags.og:image` in docs.json is a relative path. Fix: absolute URL `https://leetcode-py.wisl.dev/img/brand/og-card-light.png`. Verify the custom domain serves `/img/brand/*` (bakefile's did).
+3. **Product-label titles.** "Installation", "Quickstart", "Catalog", "Troubleshooting", "lcpy", "bakefile" (contributing) are labels, not search queries. Same fix pattern as bakefile: query-shaped titles + `sidebarTitle` for anything long.
+
+## Measurement status (head start — mostly done)
+
+- GSC **Domain property `wisl.dev` verified 2026-08-24** via DNS TXT at Spaceship registrar. A Domain property covers ALL subdomains, so `leetcode-py.wisl.dev` is already verified. No new verification needed.
+- Bing Webmaster imported from GSC same day (covers Bing + DuckDuckGo + Yahoo).
+- **Pending:** submit `https://leetcode-py.wisl.dev/sitemap.xml` in GSC (Sitemaps page) and confirm Bing copied it via import.
+- **Pending:** GSC baseline (~2 weeks after sitemap submit): record indexed pages, impressions, queries.
+
+## The big opportunity: 307 problem long-tail pages
+
+This repo has an asset bakefile does not: 307 problems whose names are high-volume search queries ("two sum python", "longest substring without repeating characters python solution"). Current state:
+
+- Catalog pages (`docs/catalog/blind-75.mdx` etc.) list problems but link them **offsite to GitHub** (`github.com/.../leetcode/two_sum/README.md`). All that content lives on github.com, not the docs domain. SEO value leaks offsite.
+- `leetcode/<problem>/README.md` per problem exists in-repo with rich content.
+
+Decision space (for the planning agent, not settled):
+
+- Generate per-problem docs pages from the same JSON/templates (mirror `gen_catalog.py` approach). 307 pages of real content, each targeting "[problem name] python". Mintlify scales fine; nav would need a hidden or collapsed section (`seo.indexing: "all"` exists for pages outside navigation).
+- Collection names are themselves high-volume keywords ("blind 75", "neetcode 150", "grind 75"). Those pages already exist — they mostly need title/description/intro strengthening, not creation.
+- Risks to weigh: thin-content pages if problem pages are just stubs, maintenance coupling to problem JSON.
+
+## Transferable decisions from the bakefile SEO pass (2026-08-24, same author, same Mintlify setup)
+
+Applied and verified on bakefile.wisl.dev — reuse the patterns:
+
+- Homepage/landing `title` frontmatter = keywords ("Python task runner, Makefile alternative"), site-name suffix carries brand. Never put the brand word in the title when the suffix already appends it.
+- `sidebarTitle` frontmatter decouples long SEO titles from sidebar labels. Mintlify supports it natively.
+- `og:image` must be absolute; relative resolves against the mintlify.app host.
+- Query-shaped H2s on comparison pages ("Make vs bakefile") match "X vs Y" queries. FAQ sections only with genuinely matching Q&A content.
+- Troubleshooting: split into per-error pages with the exact error string as title, hub page links all with error strings as anchor text. Behavioral notes stay on the hub.
+- Internal linking: no orphan pages (footer/sidebar links don't count — content links only), first-mention descriptive anchors, both directions between related pages.
+- Titles: unique, 50–60 chars rendered (including the ` - leetcode-py` suffix).
+- Verification: `bake docs-check` after every docs edit; `curl -s <url> | grep '<title>'` for rendered-title checks after deploy.
+
+## Off-repo SEO context (separate track, informational)
+
+- No blog on the docs site (author decision). Articles will live on wisl.dev (planned Astro blog) linking into both docs sites. Cross-posting to Medium/dev.to only with canonical → wisl.dev.
+- Backlinks create authority: awesome-list PRs, launch posts, GitHub topics, SO answers.
+- Both docs sites are subdomains of wisl.dev; the GSC Domain property covers them all.
+
+## Verification commands
+
+```bash
+bake docs-check                                              # broken links
+curl -s https://leetcode-py.wisl.dev/ | grep '<title>'      # rendered title
+curl -s https://leetcode-py.wisl.dev/ | grep 'og:image'     # og image host
+curl -s https://leetcode-py.wisl.dev/sitemap.xml | grep -c '<loc>'  # page count
+```
+
+## Non-goals (decided, do not relitigate)
+
+- No blog section on the docs site.
+- No custom `robots.txt` / `sitemap.xml` (Mintlify defaults correct).
+- No structured-data changes beyond Mintlify's automatic JSON-LD + existing organization block.
+- Not moving docs off the subdomain.

.dev/active/01-docs-seo/tasks.md

@@ -0,0 +1,77 @@
+# Tasks: Docs Site SEO — leetcode-py
+
+Companion to `context.md` (facts, rationale, verification commands). Work phases in order. Decisions locked 2026-08-24:
+
+- All 307 problem pages, 100% generated, no hand-written prose per problem
+- Problem pages out of nav, `seo.indexing: "all"` in docs.json
+- Problem page URLs: `/problems/<kebab-slug>/`
+- Collection head terms ("blind 75") = strengthen only, not chase
+- Non-goals in `context.md` stand
+
+## Phase 0 — Measurement setup (do first)
+
+- [x] Submit `https://leetcode-py.wisl.dev/sitemap.xml` in GSC (Sitemaps page, Domain property `wisl.dev`) — done 2026-08-24
+- [x] Confirm Bing Webmaster copied sitemap via GSC import — done 2026-08-24
+- GSC state 2026-08-24: sitemap Success (21 URLs), 0 indexed, homepage "Crawled - currently not indexed" (canonical correct, crawl clean). Clicked "Request indexing" on homepage (priority crawl queue). Baseline numbers on 2026-09-07 should reflect this
+- [ ] Record GSC baseline snapshot on **2026-09-07** (~2 weeks): indexed pages, impressions, queries (where to record: append to this file, section at bottom)
+
+## Phase 1 — Bug fixes (bounded)
+
+- [x] `docs/index.mdx`: keyword title, ≤46 chars, no brand word (suffix adds it). Done 2026-08-24: "LeetCode Practice Environments in Python". Post-deploy: verify rendered `<title>` no longer duplicates
+- [x] `docs/docs.json`: `seo.metatags.og:image` → absolute. Done 2026-08-24. `/img/brand/og-card-light.png` verified serving on custom domain (HTTP 200) before switching
+- [x] Query-shaped titles + `sidebarTitle` for label pages. Done 2026-08-24 (catalog/index moved to Phase 3, generated file):
+    - `getting-started/installation` → "Install the lcpy CLI via pip or uv"
+    - `getting-started/quickstart` → "lcpy Quickstart: First Problem in 5 Commands"
+    - `getting-started/why-leetcode-py` → "LeetCode Practice Environment vs a Bare Editor"
+    - `troubleshooting/index` → "Fixing lcpy Setup and Generation Errors"
+    - `cli/lcpy` → "lcpy CLI: Generate and List Problems"
+    - `cli/collections` → "Blind 75, Grind 75, NeetCode and Others"
+    - `contributing/problem-creation` → "Add a New LeetCode Problem End to End"
+    - `contributing/bakefile` → "Contributor Reference: bakefile Tasks"
+- [x] `bake docs-check` passed 2026-08-24 (no broken links)
+- [ ] Post-deploy `curl` checks: homepage title, og:image host on all pages
+
+## Phase 2 — Tooling niche (repo already ranks #4-10 for these queries)
+
+- [x] Retitle/strengthen `docs/practice/testing.mdx`. Done 2026-08-24: "LeetCode Python Test Cases with pytest" (38 chars, renders 52), sidebarTitle Testing, query-shaped description + intro split pointing to the local page
+- [x] New guide page `docs/practice/test-locally.mdx` (in nav, Practice group, after problem-anatomy): "Test LeetCode Solutions Locally with pytest" (43 chars, renders 57), sidebarTitle "Test locally". All output blocks captured from a real `lcpy gen -n 1` run in a temp dir (red 15 failed/3 passed, green 18 passed, `-k` 1 passed/17 deselected, root-run all-problems)
+- [x] Interlinks: test-locally <-> testing, -> problem-anatomy, -> cli/lcpy, -> cli/collections, -> catalog; inbound links from quickstart step 3, cli/lcpy, why-leetcode-py "The loop"
+- [x] `bake docs-check` passed 2026-08-24. Post-deploy title checks pending (see Phase 5)
+
+## Phase 3 — Collection page strengthening (edit `scripts/gen_catalog.py`, never the mdx)
+
+- [x] Query-shaped frontmatter per collection. Done 2026-08-24. Titles (all ≤46, unique, generator asserts both; `sidebarTitle` carries the old nav label):
+    - grind-75 "Grind 75 in Python with Tested Solutions", blind-75 / neetcode-150 / neetcode-250 / neetcode / algo-master-75 same pattern
+    - grind: "Grind Collection in Python: Tested Solutions"
+    - catalog/index: "LeetCode Problem Catalog: All Collections" / sidebarTitle Catalog
+    - catalog/all: "All LeetCode Problems in Python with Tests" / sidebarTitle All Problems
+    - Descriptions rewritten query-shaped: "All {n} problems in the {list} list: each generates a tested Python practice environment..."
+- [x] Two-sentence keyword intro per collection in `COLLECTION_INTRO` (what the list is + tested environments; `lcpy gen -t <tag>` block stays directly below). neetcode-250 intro notes coverage still growing
+- [x] `catalog/neetcode.mdx` stays out of nav (hidden-page pattern untouched; docs.json nav unchanged)
+- [x] Regenerated 9 pages, `bake docs-check` passed, `gen_catalog.py --check` no drift, ruff + ty clean. Post-deploy title checks pending (Phase 5)
+
+## Phase 4 — Problem pages (new generator, biggest chunk)
+
+- [x] New `scripts/gen_problems.py` — done 2026-08-25. PoC on two_sum first, then all 310 (catalog grew from 307):
+    - Slug: kebab-case (`two_sum` → `/problems/two-sum/`)
+    - Title: tiered formula ("X Python Solution with Tests" → "X Python Solution" → bare name → word-boundary truncate), uniqueness + ≤46 asserted
+    - Descriptions standalone (no title repeat), ≤120 chars asserted
+    - Body: intro + `lcpy gen` CTA (both `-n` and `-s`, snake_case name) / Problem (statement, examples, constraints, follow-up) / Solution verbatim / Complexity table / Tags → catalog links
+    - Executed pytest output dropped (user decision: not useful info). Case count lives in intro CTA sentence; CI backs the "passes" claim; generator runs no pytest = fast + fully deterministic
+    - `mdx_escape` on all JSON prose (`<` `{` `}` outside fences/inline code); `validate_mdx` post-render assert catches future breakers at gen time
+    - Data fix: walls_and_gates example had unbalanced nested fences (5 markers) + stray trailing backtick — fixed in JSON + README
+- [x] `docs/docs.json`: `seo.indexing: "all"` added 2026-08-25
+- [x] `gen_catalog.py`: Problem column → `/problems/<slug>/`; GitHub solution.py stays as the one secondary link per row
+- [x] Bakefile: `bake docs-problems` task added next to `docs-catalog`
+- [x] Regenerated everything. Checks passed 2026-08-25: `mintlify broken-links` clean, both `--check` modes no drift, all 310 problems linked from catalog/all. Post-deploy: llms.txt < 100k, sitemap ~331 URLs (Phase 5)
+- Note: `bake check-consistency` force-regenerates leetcode/ from templates and clobbered implemented solutions (recovered via git restore). Never run it casually; JSON+README edits must be applied to both manually
+
+## Phase 5 — Post-deploy verification
+
+- [ ] Immediately after deploy: `curl` rendered titles on ~5 sample problem pages, og:image host, sitemap count
+- [ ] GSC checkpoint **2026-09-21** (week 4, monitor only, no gate): index coverage rate, impressions by query, "Crawled - not indexed" volume. If problem pages show mass canonical-loss signals (inspect URL tool pointing at github.com) or soft-404, fix template and regenerate
+- [ ] Append findings + numbers to this file
+
+## GSC snapshots
+
+(baseline 2026-09-07 and week-4 2026-09-21 numbers go here)

bakefile.py

@@ -103,6 +103,12 @@ def docs_catalog(self):
         self.ctx.run("uv run python scripts/gen_catalog.py")
         console.success("Catalog pages regenerated into docs/catalog/")
 
+    @command("docs-problems", help="Regenerate docs/problems/ pages from JSON templates")
+    def docs_problems(self):
+        console.echo("Regenerating docs/problems/ pages...")
+        self.ctx.run("uv run python scripts/gen_problems.py")
+        console.success("Problem pages regenerated into docs/problems/")
+
     @command("check-test-cases", help="Find problems with few test cases")
     def check_test_cases(
         self,