✨ feat: enhance project setup and architecture documentation
- Updated `tibi-project-setup` skill to clarify project initialization goals and steps. - Improved `tibi-ssr-caching` skill to detail SSR architecture, responsibilities, and caching mechanisms. - Introduced `website-solution-architecture` skill for translating website requirements into coherent solutions. - Refined `AGENTS.md` to provide a structured roadmap for project development phases. - Added `ADMIN_ASSET_VERSION` to `api/config.yml.env` for asset versioning. - Updated SSR request flow and cache invalidation logic in `api/hooks/ssr/AGENTS.md`. - Removed obsolete `esbuild.config.admin.js` and integrated asset versioning into the main `esbuild.config.js`. - Adjusted `api/collections/content.yml` to utilize asset versioning for admin scripts.
This commit is contained in:
@@ -0,0 +1,202 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user