---
name: media-seo-publishing
description: Model media, SEO, and publishing workflows for website projects on this starter. Covers file fields, image validation/filtering, alt texts, social metadata, publication windows, and SSR/cache implications.
---

# media-seo-publishing

## When to use this skill

Use this skill when:

- Designing media-heavy website content models
- Adding image/file fields and image filters
- Modeling SEO fields for pages or reusable content
- Defining publication windows and how they interact with runtime and SSR
- Building authoring workflows around images, metadata, and release control

## Goal

The goal is to make media, SEO, and publishing part of the actual solution design instead of leaving them as late add-ons.

For real website projects, these concerns affect:

- collection schema
- admin ergonomics
- frontend rendering
- SSR/cache validity
- editorial quality

## Source of truth

Use these sources when implementing or reviewing these areas:

- `tibi-server/docs/08-file-upload-images.md`
- `api/collections/medialib.yml`
- `api/collections/content.yml`
- `tibi-admin-nova/docs/collection-config.md`
- `api/hooks/config.js`
- `api/hooks/lib/ssr-server.js`

## Media modeling

Use file fields deliberately.

Typical choices:

- `file` for a single image or asset
- `file[]` for galleries or multi-asset attachments
- foreign references to a media collection when assets need their own lifecycle or reuse

Choose between inline file fields and dedicated media references based on reuse and editorial workflow, not just convenience.

## File validation rules

For serious website builds, do not leave file fields unconstrained.

Define validators where appropriate:

- accepted mime types
- max file size
- min/max image dimensions
- whether mixed media is allowed

This should reflect actual content needs. Hero images, logos, documents, and gallery media often need different constraints.

## Image filters

If the project serves resized or transformed assets, define image filters intentionally.

Use filters for:

- thumbnails
- card images
- hero images
- OpenGraph/social images when relevant

Do not leave every consuming component to invent its own ad hoc asset sizes.

## Alt texts and captions

Accessibility and SEO-relevant image metadata should be explicit in the model.

Recommended approach:

- store alt text explicitly
- keep captions separate from alt text
- use localized fields if the site is multilingual
- optionally use AI assistance only as a suggestion flow

Do not treat filenames as acceptable alt text.

## SEO modeling

Page-like collections should usually model SEO explicitly.

Typical fields:

- `meta.title`
- `meta.description`
- social/share image
- optional canonical information if required
- optional index/follow controls for advanced projects

SEO fields should be easy to find in Nova, usually via sidebar groups or clearly named sections.

## Publishing model

If the site uses publication timing, define it intentionally.

Typical concerns:

- draft versus active state
- publication window (`from` / `to`)
- visibility of unpublished content in public reads
- SSR cache validity for time-sensitive content

Publishing is not just a boolean. If publication windows exist, they must influence runtime and cache behavior.

## SSR implications

Media, SEO, and publishing affect SSR directly.

Examples:

- page meta tags must exist in SSR HTML when relevant
- navigation or content with publication windows must invalidate cached HTML correctly
- image-driven blocks must render stable URLs/markup in SSR

If publication timing can make cached HTML stale, the relevant collections must be accounted for in SSR publish-check logic.

## Admin ergonomics

Use current Nova features to make media/SEO workflows usable:

- sidebar groups for SEO/publication fields
- `viewHint.media` for media-focused collections
- previews for image-bearing entities
- layout grouping so editors do not scroll through one long file/SEO form

Media and SEO fields are often technically present but operationally poor if the admin layout is ignored.

## Recommended modeling patterns

### Marketing page

Recommended shape:

- main content blocks
- explicit SEO object or fields
- hero/share image strategy
- publication controls in sidebar

### Media library entry

Recommended shape:

- file field
- title/name
- alt text / caption
- optional copyright/source
- image-focused admin view

### Reusable teaser or card entity

Recommended shape:

- image reference or file
- short label/title
- teaser text
- consistent image filter usage in frontend components

## Anti-patterns

- No file validators on public/editor-uploaded images
- No explicit alt field
- Mixing captions and alt text into one field
- Hardcoding image sizes only in frontend CSS/components
- Treating publication as frontend-only logic
- Forgetting that publish windows can invalidate SSR HTML

## Verification checklist

After changing media/SEO/publishing behavior, verify all of these:

1. Upload validation matches the intended asset type.
2. Image filters are named and used consistently.
3. Alt/caption/SEO fields are explicit and editor-friendly.
4. Publication state affects public output correctly.
5. SSR HTML still reflects the intended published state.
6. `yarn validate` stays clean.

## What an LLM should inspect first

When asked to work on media, SEO, or publishing on this starter, inspect in this order:

1. `tibi-server/docs/08-file-upload-images.md`
2. the relevant collection YAML
3. admin layout and previews for those fields
4. frontend components consuming the media/SEO data
5. SSR publish-check and invalidation logic if timing matters

This prevents “just add an image field” changes that break runtime, editorial UX, or caching.