Skip to content

Latest commit

 

History

History
292 lines (203 loc) · 12.1 KB

SEO.md

File metadata and controls

292 lines (203 loc) · 12.1 KB

ePlus OnAir SEO Architecture

Last updated: 2026-10-08

This file is the durable SEO checklist for ePlus OnAir. It records what is implemented, what is intentionally not implemented, and the reasons behind those decisions.

GitHub Pages and production indexing policy

GitHub Pages publishes generated static output from the source repository into three isolated public output repositories with custom hostnames (see ENVIRONMENTS.md):

  • Development PR → ePlus-DEV/onair-pr-previews → https://preview.radio.eplus.dev/pr-preview/pr-N/: noindex, no sitemap/canonical/JSON-LD, no GA4; PR-specific NUXT_APP_BASE_URL=/pr-preview/pr-N/.
  • staging → ePlus-DEV/onair-staging-pages → https://stg.radio.eplus.dev: noindex, no sitemap/canonical/JSON-LD, no GA4; root NUXT_APP_BASE_URL=/.
  • main → ePlus-DEV/onair-production-pages → https://radio.eplus.dev: indexable, canonical/JSON-LD, production sitemap and GA4 G-ETDY41KBBJ; root NUXT_APP_BASE_URL=/.

Never set NUXT_PUBLIC_NO_INDEX=true globally in a shared Pages workflow; set it for Staging and Development Preview only. Use branch-specific indexing and verify the generated output before publishing. Do not assume GitHub Pages publishing itself changes production DNS or TLS. See GitHub Pages guide.

Non-production noindex policy (Staging and Development Preview)

staging is staged at https://stg.radio.eplus.dev and must not be indexed. Build-time configuration for staging only:

NUXT_PUBLIC_SITE_URL=https://stg.radio.eplus.dev
NUXT_PUBLIC_NO_INDEX=true

There is no dependency on a custom deploy environment or checkout branch. Both stg.radio.eplus.dev (target Staging), preview.radio.eplus.dev (Development Preview), and the legacy new-radio.eplus.dev / radio-new.eplus.dev hostnames fail closed to noindex if supplied as NUXT_PUBLIC_SITE_URL, even if the explicit noindex flag is inadvertently missing. Preview still requires its per-PR base URL and NUXT_PUBLIC_NO_INDEX=true. On production, keep NUXT_PUBLIC_SITE_URL=https://radio.eplus.dev and do not enable NUXT_PUBLIC_NO_INDEX.

Non-production output (Staging and Development Preview):

  • <meta name="robots" content="noindex, nofollow, noarchive"> in prerendered HTML
  • No canonical or JSON-LD; Open Graph and Twitter metadata remain for share-card testing. Social cards do not enable search indexing while robots is noindex.
  • /robots.txt: Allow: / without a sitemap (generated by the Nitro robots route). Crawlers must be able to read the page-level noindex directive. Disallow: / can block that observation and leave previously discovered staging URLs indexed. For a truly private staging environment use authentication/access control on the staging host, not robots.txt alone.
  • No sitemap module or sitemap output
  • Real navigation, station pages, playback and SSR/prerender remain functional

Production main has SEO enabled, explicit canonical URLs, structured data, index, follow, sitemap, and robots.txt referencing the production sitemap. These conditions are environment-based, not unconditional source deletions, so merges from staging into main cannot silently disable production SEO.

Canonical site

  • Production origin: https://radio.eplus.dev
  • Canonical URLs are generated in app.vue from the current route path.
  • Development/Staging hosts must never replace the Production canonical origin in indexable output. Their build URLs are isolated and they emit no canonical tags.

Indexable route model

The primary indexable content hierarchy is:

/                              Home / regions
/{area}                        Region / country collection
/{area}/{country}              Country / station collection
/{area}/{country}/{station}    Station detail

Country and station catalogs are loaded during SSR/prerender from local repository JSON so crawlers receive real internal links and station metadata without requiring client JavaScript.

Global provider routes (external playback)

A separate global directory is available at /global-radio and /global-radio/apple-music, with seven Apple Music station detail pages. These pages are statically prerendered and included in the production sitemap through build/globalRadioRoutes.ts. Their canonical URLs and metadata use the existing shared useStaticPageSeo helper. Staging retains its existing noindex and no-sitemap behavior.

These provider records are not inserted into geographic world.json or internal HTMLAudio station search. Buttons open Apple Music/TuneIn pages externally; they are not playable MP3/HLS resources. Existing country/station titles, metadata, routes and JSON-LD remain unchanged.

See docs/global-radio-providers.md for provenance and QA.

Realtime data is different:

  • schedules
  • current-song/detail APIs
  • lyrics

Those remain client-only and must never block SSR/prerender.

Metadata

Global metadata:

  • canonical URL
  • robots: index, follow
  • Open Graph site identity
  • Open Graph locale
  • default social image
  • Twitter large-image card
  • image alt text
  • WebSite JSON-LD
  • Organization JSON-LD

Page metadata:

  • unique title
  • unique description
  • explicit Open Graph URL
  • page-specific image where available
  • image alt text on station/country social metadata

Browser tab title during playback

The app shell updates only the browser tab's <title> while a station is actually playing. If the realtime provider supplies a song, the tab prioritizes that title and artist (for example, ▶ Price Tag — Jessie J · Heart UK | ePlus OnAir). If no track metadata exists, it falls back to ▶ Heart UK | ePlus OnAir. The bottom player and tab share a single track extraction rule for Zing currentMedia and Webrad playlist metadata. Track state is tied to the active station URL and cleared when switching stations, preventing stale songs from appearing. This uses a reactive title template rather than mutating document.title directly.

Pause/stop/failed playback return to the current route's normal title, even after navigating while listening. During SSR/static prerender, there is no active audio session: route titles, canonical URLs, Open Graph metadata and structured data remain unchanged.

Structured data

Current JSON-LD coverage:

Route Structured data
/ WebSite, Organization, CollectionPage / ItemList
/{area} BreadcrumbList, CollectionPage / ItemList
/{area}/{country} BreadcrumbList, CollectionPage / ItemList
/{area}/{country}/{station} BreadcrumbList, RadioStation

Do not mark realtime schedule/song/lyric data as static structured data unless it can be rendered reliably and truthfully at crawl time.

Sitemap

@nuxtjs/sitemap receives all radio routes from build/radioRoutes.ts.

Route discovery only treats a public/radio/<area>/ directory as an area when it contains country JSON catalogs. Asset-only folders must never become sitemap/prerender routes.

The sitemap is kept as plain XML without an XSLT stylesheet (sitemap.xsl: false). Chromium is removing XSLT support (expected in stable Chrome 158), so the former styled table view would display a deprecation warning and eventually stop working. Disabling the stylesheet removes the browser dependency while leaving all valid <loc> entries in XML for search engines; browsers will display raw XML instead of the styled table. An XML sitemap is for crawlers, not a replacement for an HTML site directory.

Because i18n uses strategy: "no_prefix", sitemap.autoI18n is explicitly false; do not advertise alternate language URLs until real localized URL paths are introduced. Production continues to expose the sitemap and reference it in robots.txt. Neither Staging nor Development Preview generates a sitemap.

The sitemap intentionally does not emit lastmod yet.

Filesystem mtimes from CI/deployment checkouts are not reliable content-modification timestamps; using them would effectively tell crawlers that every page changed on every deployment. Add lastmod only when the catalog has a durable update timestamp or the build has a trustworthy per-file history source.

Robots and agent discovery

Public files:

  • /robots.txt
  • /sitemap.xml
  • /llms.txt
  • /agents.md

/api/ is disallowed in robots because it is not intended as indexable site content.

404 behavior

Unknown region/country/station URLs must not silently render an empty page with HTTP 200.

Current rules:

  • unknown area → 404
  • missing country catalog → 404
  • missing station in a valid catalog → 404

Avoid soft-404 regressions.

Internal linking

Area pages expose country links during SSR.

Country pages expose station links during SSR.

Station detail pages also expose the country station collection so crawlers and users can navigate laterally.

Do not move country/station discovery back behind onMounted() or client-only fetches.

Multilingual SEO limitation

The UI supports multiple languages, but Nuxt i18n currently uses:

strategy: "no_prefix"

That means all languages share the same canonical URL.

Because there is no distinct URL per locale, ePlus OnAir does not currently have true multilingual SEO/hreflang coverage.

Do not generate multiple hreflang entries that all point to the same URL merely to satisfy a checklist. Proper multilingual SEO requires a route migration such as:

  • prefix_except_default, or
  • prefix_and_default

That change affects canonical URLs, sitemap entries, internal links, redirects and historical indexing, so it must be handled as a dedicated migration.

Static navigation pages

The public site includes:

  • /about
  • /statistics
  • /contact
  • /privacy-policy
  • /terms-of-use

These routes are explicit prerender targets and sitemap entries, and Header/Footer navigation must only expose them while matching page files exist.

All supported locales provide their static-page copy under site_pages.

The Statistics page reads a build-time snapshot from build/radioStats.ts, which counts the repository's current country catalogs and station entries. Do not hard-code these totals or present them as guaranteed-online streams/audience counts.

Search-result enhancement decisions

Not currently added:

  • SearchAction JSON-LD

Reason: the site search is an in-page modal and there is no stable public search-result URL template. Do not advertise a SearchAction until such a route exists.

Validation

At minimum:

npm test
npm run generate

Important SEO regression test:

tests/seo-page-foundation.test.mjs
tests/seo-structured-data.test.mjs

Manual production checks after deployment:

  • page source contains expected canonical/title/description
  • country page source contains station links without executing JS
  • invalid area/country/station URL returns 404
  • /sitemap.xml contains the expected canonical routes
  • /robots.txt references the production sitemap
  • JSON-LD parses correctly
  • social preview image resolves publicly
  • no preview or staging hostname leaks into Production canonical or Open Graph URLs

Rule for future AI/contributors

SEO work should prioritize, in order:

  1. correct HTTP/indexability behavior;
  2. server-rendered discoverable content/internal links;
  3. canonical and duplicate-control;
  4. structured data;
  5. social metadata;
  6. crawler convenience files.

Do not treat keyword stuffing or adding arbitrary meta tags as an SEO fix.

Personal library

/library is prerendered for static navigation, with noindex, follow on production and the staging noindex policy on staging. Its device-local lists are client-only. It is not part of the sitemap URL list.

Environment-specific site title (2026-11-06)

The browser-tab title suffix/site name uses NUXT_PUBLIC_SITE_NAME from each GitHub Environment. Defaults are ePlus OnAir for Production, ePlus OnAir — Staging for stg.radio.eplus.dev, and ePlus OnAir — Preview for the PR Preview host. The Preview build receives only the validated public title from its trusted preview Environment config job. Route-specific SEO descriptions, title bodies, canonical tags and GA4 remain governed by their existing code and Production settings; do not rewrite them to label environments.