Files
CV_Site_Nuxt/OKF_Nuxt/decisions/seo-and-metadata.md
T
Noel Sabia 1c3503fed0
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / Lint + typecheck (pull_request) Successful in 1m6s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 7s
PR Check / Dependency audit (pull_request) Successful in 9s
PR Check / Dockerfile lint (droast) (pull_request) Successful in 5s
PR Check / AI code review (opencode) (pull_request) Successful in 1m11s
feat: pixel favicon and complete SEO metadata
- generate favicon.ico and favicon.svg from the header avatar; the sprite
  moves to app/utils/avatar.js so component and generators share one source
- register @nuxtjs/seo with site and Person schema.org data from
  site.config.mjs; canonical, robots, sitemap and llms.txt follow the routes
- title "Noel Sabia — <role>", summary_large_image, and no duplicate
  "| Noel Sabia" suffix from SEO Utils
- add a committed 1200x630 OG card generated by pnpm og-image; the dynamic
  OG renderer and skew protection stay off for the static deployment
- pin the Node version @nuxtjs/seo 6 requires and document the setup in the
  OKF bundle
2026-10-23 20:37:32 +02:00

99 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
type: Decision
title: SEO stack and site metadata
description: @nuxtjs/seo owns canonical URLs, sitemap, robots, schema.org and social tags; metadata lives in one ESM file, the OG card is a committed PNG, and the dynamic OG renderer and skew protection stay off.
tags: [decision, seo, metadata, nuxt, static]
status: stable
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-23T00:00:00Z }
verified: { by: human:noel, at: 2026-10-23T00:00:00Z }
sources:
- id: config
resource: nuxt.config.ts
title: site, schemaOrg, ogImage and skewProtection options
- id: metadata
resource: site.config.mjs
title: Single source for URL, name, role, description, locale, email, GitHub
- id: page
resource: app/pages/index.vue
title: Page title and Twitter card type
- id: generator
resource: scripts/generate-og-image.mjs
title: OG card generator
- id: package
resource: package.json
title: "@nuxtjs/seo, Node engines, og-image script"
---
# Decision
`@nuxtjs/seo` 6.0.1 is registered as one module; it brings sitemap, robots,
OG Image, schema.org, link checker, SEO Utils, site config, AI Ready and skew
protection. The site's own values live in `site.config.mjs`:
```js
export const SITE = {
url: 'https://noelsabia.dev',
name: 'Noel Sabia',
role: 'Programmer, AI Assisted Coder, Arch user',
description: '…',
locale: 'en',
email: 'noel@noelsabia.dev',
github: 'https://github.com/NoelSabia',
}
```
`nuxt.config.ts` maps that into `site` (URL, name, description, locale) and
`schemaOrg.identity` (`Person`, with `jobTitle`, `email`, `sameAs: [GitHub]`).
`app/pages/index.vue` sets the title to `<name> — <role>` and
`twitter:card: summary_large_image`; `useHead({ titleTemplate: '%s' })` stops
SEO Utils from appending `| Noel Sabia` to the title it already contains.
# Why a static OG card
`public/og-image.png` (1200×630) is generated from the same pixel avatar as the
favicon, plus the name and role. It is committed. `ogImage: false` disables the
dynamic module, so no Takumi/Satori renderer, native binary or runtime image
route is added; SEO Utils still emits `og:image`, `twitter:image`, their
`width`/`height`/`type` tags, and the alt text from `og-image.alt.txt`.
Regenerate with `pnpm og-image`. That script needs `woff2_decompress` and
`rsvg-convert` on the machine because librsvg cannot read the self-hosted woff2
files; the output is committed, so builds and deploys need neither tool.
# Other settings
| Option | Value | Reason |
|---|---|---|
| `skewProtection` | `false` | The site ships as static files inside the gateway image; there are no old chunks to keep and the CI starts from a clean checkout, so the cache would be empty. Avoids an extra service worker. |
| `engines.node` | `^22.22.3 \|\| ^24.15.0 \|\| >=26.0.0` | `@nuxtjs/seo` 6 refuses to boot on older Node. Docker uses `node:26-slim`; CI uses `node:22-bookworm`, which tracks the latest 22.x. |
Robots, sitemap and AI Ready keep their defaults: `robots.txt` allows all
crawlers and appends `Sitemap: https://noelsabia.dev/sitemap.xml`;
`sitemap.xml` is generated from the routes (only `/` today); `/llms.txt`,
`/llms-full.txt` and Markdown versions of pages are produced by AI Ready.
# Consequences
* `site.url` is the canonical origin. Every environment serves the production
URLs; a staging deploy must set `NUXT_SITE_ENV=staging` so robots and the
`X-Robots-Tag` header block indexing.
* Adding a page needs no SEO config: canonical, OG basics and sitemap entry
follow the route. Give it a title with `useSeoMeta` and the default
`| Noel Sabia` suffix returns unless it sets `titleTemplate` too.
* `nuxt generate` writes `robots.txt`, `sitemap.xml`, `llms.txt`, the Markdown
pages and the static OG card into `.output/public`.
# Not verified
* How the card looks in a real LinkedIn, X or WhatsApp preview; the PNG was
checked locally at full size.
* Crawling in Google Search Console — the domain is not live yet.
# Revisit when
* There are several pages and one shared card is no longer enough: enable
Takumi with `npx nuxt-og-image enable takumi` and replace `ogImage: false`
with a template.
* German is actually translated: add `@nuxtjs/i18n` instead of listing `de` in
`defaultLocale`, which must stay a single language tag.