Content Cluster Generator

What is a cluster?

A content cluster is one SEO topic packaged as 1 Hub (landing page) → 1 Pillar (the deep guide) → N Spokes (focused sub-topic articles), optionally translated per language. Tiles are the links/backlog shown on the hub — live tiles point to real pages, soon tiles are planned topics not yet written.

Three ways to create / grow a cluster

Action	What it makes	Use when
Generate	A whole new cluster from a topic: 1 hub + 1 pillar + 6 spokes + tiles in English, auto-translated to Hindi + Urdu.	You want AI to draft a fresh cluster from scratch.
Mine	More tiles only (the "soon" backlog) for an existing cluster, sourced from real GSC search queries + Gemini trends.	You have a cluster and want data-driven ideas for new spokes.
Seed	Hub + pillar + spokes + tiles ingested from a hand-authored folder of HTML (per the authoring guide).	A writer delivered real, human-written articles.

Generate a cluster (AI)

• Type a topic in the Topic box (e.g. magnesium).
• Click Preview (dry-run) to see the plan — nothing is saved.
• Click Generate + Persist to build it and write to the DB as a draft.
• Cluster slug = the slugified topic. Re-running the same topic overwrites (upserts) that cluster — it refreshes, it doesn't append.
• The button always makes 6 spokes. For a different count, call the API directly:

curl -X POST /api/content-cluster/generate \
  -H 'Content-Type: application/json' \
  -d '{"topic":"magnesium","spokes":12}'

Mine more tiles (backlog)

• Type the same topic as an existing cluster → click Mine Spoke Topics.
• Returns up to 12 "soon" tiles from GSC queries + Gemini trends. It adds tiles only — no pages.
• If the cluster doesn't exist yet you'll get cluster not found — seed or generate it first.

Seed hand-authored content

• Author a folder per the authoring guide — same format for every cluster.
• Shape: slug/en/index.html (hub) + *pillar*.html + spoke files; optional hi/ ur/ with identical filenames.
• Paste the folder path in the Seed from local directory box → click Seed. Idempotent — safe to re-run after edits.

Viewing a cluster

• Click any row in the Clusters table to open the detail drawer.
• Use the Language chips to filter both tiles and spokes by language (English / Hindi / Urdu / Spanish).
• Pages are grouped into Hub / Pillar / Spokes; in "All" view each item is tagged with its language.

Authoring guide (per cluster)

• Each cluster has its own authoring guide, written in Markdown and stored in the DB.
• Attach one at creation via the Authoring guide box, or add/edit it later from the cluster's detail panel (Add / Edit → Save guide).
• Use it for cluster-specific tone, audience, sources, and do/don't rules — it renders as formatted Markdown in the detail view.

Going live

Everything is created as a draft. After editorial / clinical review it's flipped draft → live and renders at medwiki.co.uk/health/topics/<slug> in Medwiki's own design.