Ghost + Next.js Integration

# Ghost and Next.js on the Cleavr website

This guide describes the public website's CMS integration. It does not describe the internal architecture of the Cleavr collections product.

## Published content

The website uses the Ghost Content API for published blog posts, tags and authors. The implementation is in `lib/ghost.ts` and `lib/blog-data.ts`. API configuration stays on the server. The public blog is available at https://www.cleavr.fr/en/blog.

The site uses the Next.js App Router. Route parameters and search parameters are asynchronous in the installed version. Consult the documentation shipped with the installed `next` package before changing routing, caching or metadata code.

## Metadata ownership

The website generates article metadata from the same Ghost fields that supply its visible title, author byline and publication dates. `app/[locale]/blog/[slug]/page.tsx` owns the canonical URL and language alternates. `components/blog/ArticleSchema.tsx` owns article JSON-LD.

Ghost theme code injections are not rendered into the page. They can contain duplicate schemas, competing canonical URLs or malformed script elements. Published body content passes through `proxyGhostImagesInHtml`, which removes scripts and routes Ghost-hosted media through the website's restricted media proxy.

An article's `canonical_url` field remains available for deliberate canonical overrides. It is used consistently by both page metadata and article schema. Do not add a second canonical link in a code injection.

## Languages

Supported website locales are French, English, Spanish and German. Ghost posts use language tags. Article translation mappings are read on the server from the `alternate-slug` JSON object in `codeinjection_foot`; the raw script is not rendered.

Example translation mapping:

```html
<script type="application/json" id="alternate-slug">
{"en":"english-article-slug","fr":"french-article-slug"}
</script>
```

Only real translations belong in this mapping. The article page canonicalizes fallback content to its source-language URL. Page-specific HTML alternates are authoritative; automatic middleware language Link headers are disabled because they cannot know translated article slugs.

## Listings and refresh

`lib/blog-data.ts` reads the full published catalogue using paginated API calls and a 60-second fetch cache. Search uses that server-side catalogue. `lib/blog-listing.ts` applies the same category, editorial selection and pagination rules for metadata and rendered listings. Each valid page after page one has its own canonical URL. Search-result pages are noindex, follow.

`app/sitemap.ts` revalidates after five minutes on demand and reads every Ghost API page. If an upstream refresh fails, it throws so Next.js retains the last successfully generated sitemap. Post modification dates come from Ghost. Static pages do not receive invented build-time modification dates.

## Media

`app/api/ghost/[...path]/route.ts` permits only Ghost content images and media. Arbitrary API paths are rejected. The crawler rules allow those public media paths while keeping other API routes disallowed.

## Verification

Run `npm run test:seo`, `npm run test:blog`, `npm run lint` and the production build after changes. Check rendered HTML, not only the source code: one canonical, one Article node, the correct visible author, a readable article body and consistent language alternatives. Test both a translated article and a source-language fallback.