← All projects

Education / SEOActive

Learn Marathi

A static Marathi learning site that turns a real Flutter app's curriculum into indexable pages readers love and search engines trust — every word traced to source, every page above the thin-content bar, every download button honest about the app not being launched yet.

Pages

200 built

Words

1,041+ live

Units

26 → 26 pages

QA gate

prebuild, blocking

A language app with its curriculum locked inside the app is invisible to the people searching for exactly what it teaches. This project started from that gap: the Bol Marathi Flutter app holds 26 units, 156 lessons, and 1,002 trilingual words — and none of it could be found, linked, or previewed on the web. The website fixes that without becoming a content farm: a sync pipeline carries the curriculum into a static Astro site, a dataset engine turns it into pages that each serve one search intent, and a validation gate refuses to publish anything thin, duplicated, or unresolvable.

Two ways to read this page

• Understand the system: The spark ? The struggle ? The decisions ? How it works ? Where it stands ? Reflection.
• Build your own: Constraints ? Architecture ? The size-gate rule ? Try the pages ? The tutorial series ? Exercises at the end.

The spark

The app teaches Marathi from Hindi — greetings, food, travel, verbs, grammar, culture — in structured units a learner could browse like a course. But app-store listings don’t teach, and a marketing page with three screenshots doesn’t answer “how do you say good morning in Marathi?” So the requirement became: publish the real curriculum as real web pages, one search intent per page, with a visible path from every page into the app. Not a blog about Marathi. The curriculum itself, addressable.

The struggle

A thousand words that must never become a thousand pages. The vocabulary snapshot holds 1,002 entries. The naive move — one page per word — is exactly how sites earn thin-content penalties: hundreds of near-empty pages with one example each. The project refused. Per-word pages were rejected outright; words ship inside clusters and topic pages that clear a size gate (~15 entries) and a validator threshold (≥10 resolved words). One entry is data. Ten is a page.

Six scattered email links and a store button for an app that isn’t launched. The early site had mailto links in buttons, panels, footers, and a personal address in the source — plus store-badge instincts for an app with no listing. Every one of those is a small lie told to a future user. The fix consolidated contact into one shared waitlist form with a configured endpoint, and gated every app promise behind src/data/app.ts: comingSoon: true renders honest waitlist copy everywhere, and only setting a real store URL flips the labels. Trust is a build artifact here.

156 lessons that would drown any index. Six lesson rows across six sections in each of 26 units is 156 addressable lessons — each too thin alone, overwhelming together. They ship as 26 unit pages instead, each bundling its grammar, culture, speaking, listening, bridge, and sentence-builder rows with related words. Fewer pages, denser pages, no orphans.

The decisions

Five constraints did the rest of the shaping, extracted from the implementation rather than aspired to: fully static output (no server, GitHub Pages project site under /learn-marathi); base-aware links with trailing slashes everywhere; curriculum never hand-copied (sync from the Flutter repo, website-only fixes in overrides.json and logged); no page below the thin-content bar; no app promise the config can’t back. Deployment stays npm run build plus a Pages workflow.

How it works

• Astro 7 (static)
• TypeScript (strict snapshots)
• Zero-dep Node sync + QA scripts
• MDX topic components
• Playwright (screenshots, quizzes)

flowchart LR
  subgraph APP["Flutter repo — canonical"]
      U["26 unit JSON files"]
      V["generated_vocab.dart — 1002 words"]
  end
  subgraph SYNC["npm run sync"]
      S["sync-learn-marathi.mjs"]
      O["overrides.json — logged"]
  end
  subgraph SITE["Astro site"]
      SN["units + vocab + meta.json snapshots"]
      DS["seo JSON datasets — 5 families"]
      R["seo.ts resolvers — throw on drift"]
      P["getStaticPaths → 200 pages"]
  end
  U --> S
  V --> S
  O --> S
  S --> SN
  SN --> R
  DS --> R
  R --> P

The file to understand first is tools/sync-learn-marathi.mjs: zero npm dependencies, plain Node. It reads the 26 unit files (requiring every top-level key and exactly 6 rows per section), parses the Dart vocabulary with a regex, applies the logged override layer, and writes three committed snapshots — units.json, vocab.json, meta.json — with counts in meta.json (26 units, 156 lessons, 1,002 words, synced 2026-09-20). The file to understand second is src/lib/seo.ts: typed dataset loading plus resolvers (wordsFor, speakingFor, grammarNotesFor, bridgesForPage) that throw at build time on bad references, and relatedFor, a deterministic capped internal-linking engine — declared links first, then cross-family topic matches, curriculum unit links, one same-family sibling. No random article lists anywhere.

In action

Screenshots and video captured from a live local run against the real synced curriculum (verified 2026-10-07). Every frame read before shipping; no skeletons, no placeholders.

In action

Where it stands

Reflection

What worked. The size gate survived contact with real content pressure — Shopping and Colors merged without drama because the number made the call, not taste. Resolvers-that-throw turned drift from a slow rot into a loud build failure, which is the only kind of content bug you actually fix.

What didn’t. The early funnel told small lies (scattered mailtos, store-badge instincts) until one config file made honesty the default. And per-word pages were tempting right up until the threshold math showed what 1,002 near-empty pages would cost.

What surprised me. How little of a 200-page SEO project is SEO: most of the work is pipeline plumbing, threshold choices, and link hygiene. The rankings follow the structure; the structure is just counting.

What I’d change. Nothing structural — the next work is evidence, not architecture: native review, measured search performance, then clips and word-pages only when their entry conditions are met.

Build your own

Reproduce: clone, point BOL_MARATHI_ROOT at the app repo, run npm run sync, then npm run content:qa and npm run build. Modify: add one dataset page that clears the thresholds and watch the manifest, sitemap, and related links absorb it. Extend: mirror one more page pair into /hi/ with hreflang both ways. Re-design: replace the size gate with per-word pages for one category and feel, concretely, what thin content costs. The six-part tutorial series reconstructs this project layer by layer — start with Part 1: problem and architecture.