Merge remote-tracking branch 'origin/main' into feat/registry

# Conflicts:
#	OKF_Nuxt/log.md
This commit is contained in:
Noel Sabia committed 2026-10-24 19:13:41 +02:00
commit f3d3e196d0
36 files changed
+3376 -151

No files matched your search

+76
View File
@@ -0,0 +1,76 @@
---
type: Decision
title: Icons via Nuxt Icon
description: Every icon comes from @nuxt/icon with the Material Symbols collection installed locally; the self-hosted icon webfont, its @font-face and its CSS class are gone.
tags: [decision, ui, icons, nuxt, payload]
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: Icon module registration and options
- id: consumer
resource: app/components/AppBottomNav.vue
title: First and only icon consumer so far
- id: package
resource: package.json
title: "@nuxt/icon and @iconify-json/material-symbols"
---
# Decision
Icons come exclusively from `@nuxt/icon`. The icon set is Material Symbols,
installed as a local collection (`@iconify-json/material-symbols`), and names are
written in full inside components:
```vue
<Icon name="material-symbols:badge" aria-hidden="true" class="text-[22px]" />
```
The previously self-hosted Material Symbols webfont is deleted:
`public/fonts/material-symbols-outlined-var.woff2`, its `@font-face` in
`app/assets/css/main.css`, and the `.material-symbols-outlined` class.
# Why
* **One icon system.** The nav rendered webfont glyphs by text content while
everything else in the app is Tailwind utilities; a ligature typo silently
produced a blank box.
* **Payload.** The font was 3.9 MiB for three glyphs. The bundled icon data for
the same three is 1.23 kB.
* **Self-hosting.** The module's defaults are not local: `mode: "css"`, provider
`server`, `iconifyApiEndpoint: https://api.iconify.design` and
`fallbackToApi: true`. Without an installed collection the site would call a
third-party CDN at runtime, which is the same problem the self-hosted text
fonts were chosen to avoid.
# Configuration
| Option | Value | Effect |
|---|---|---|
| `mode` | `'svg'` | The icon is an inline `<svg>` in the SSR HTML, so it survives with JavaScript disabled. CSS mode would have fetched icon data on the client and painted after hydration. |
| `serverBundle` | `{ collections: [] }` | `'auto'` bundles every installed collection server-side; with only `material-symbols` installed that was an 8 MB `icons.mjs`. Empty means no server-side icon data at all. |
| `clientBundle` | `{ scan: true }` | Bundles only the icons named in source. The build reports `Nuxt Icon client bundle consist of 3 icons with 1.23KB(uncompressed) in size`. |
# Consequences
* Sizing is `text-[…]` on the `<svg>`: the component renders `width="1em"
height="1em"`, so font-size is the icon size.
* Adding another Material Symbols icon is a code change only — the scanner picks
the name up and the next build bundles it.
* A different icon set means `pnpm add @iconify-json/<set>` plus new names; no
other configuration changes.
* Decorative icons carry `aria-hidden="true"`, because every icon sits next to a
text label.
# Not verified
* That the bars look right at 22px on a real phone — checked in the SSR HTML and
the build output only.
# Revisit when
* A second icon set is wanted (two collections, two packages, no config change).
* Many icons push the client bundle up: the alternative is `mode: 'css'`, which
ships class names and fetches icon data once instead of inline SVG per icon.
+2
View File
@@ -12,3 +12,5 @@
* [Production image shape](production-image.md) - Multi-stage, digest-pinned, non-root runnable Node server; measured build and serve.
* [Repository and compose layout](repo-and-compose-layout.md) - The Dockerfiles live with the app; the stack is assembled in `Local_Development`.
* [Mockup layout](mockup-layout.md) - One `DESIGN.md` per screen, with the screenshot and the source embedded.
* [Icons via Nuxt Icon](icons-via-nuxt-icon.md) - Every icon comes from `@nuxt/icon` with the Material Symbols collection installed locally; the 3.9 MiB icon webfont is gone and three icons cost 1.23 kB.
* [SEO stack and site metadata](seo-and-metadata.md) - One `site.config.mjs` feeds canonical URLs, sitemap, robots, schema.org and the static OG card; the dynamic OG renderer and skew protection stay off.
+98
View File
@@ -0,0 +1,98 @@
---
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.
+5
View File
@@ -33,6 +33,11 @@ config files — the configs say what, these documents say why.
* [Repository and compose layout](decisions/repo-and-compose-layout.md) - The Dockerfiles live with the app; the stack is assembled in `Local_Development`.
* [Mockup layout](decisions/mockup-layout.md) - One `DESIGN.md` per screen, with the screenshot and the source embedded.
## UI and icons (2026-10-23)
* [Icons via Nuxt Icon](decisions/icons-via-nuxt-icon.md) - Icons come only from `@nuxt/icon` with a locally installed Material Symbols collection; inline SVG for SSR, scanned client bundle, and no icon webfont.
* [SEO stack and site metadata](decisions/seo-and-metadata.md) - `@nuxtjs/seo` with one metadata file, a `Person` identity, a committed 1200x630 OG card, and no dynamic OG renderer or skew protection.
# The one-paragraph history
The repository started as the Nuxt app shell. Docker development (dev
+20
View File
@@ -4,6 +4,26 @@
* **Creation**: [publish-image.yml](../.gitea/workflows/publish-image.yml) - a `v*` tag push builds `Dockerfile` on the arm64 runner and pushes `registry.noelsabia.dev/cv_website/nuxt` as the version, `sha-<12>`, and `latest`. Main pushes deliberately do not build: the registry holds releases, not commits. The job uses the runner's own Docker daemon (client only in the `node:22-bookworm` container), so the act_runner needs `container.docker_host: automount`; the first step fails with that cause if it is missing. Repo secrets: `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`. See [Publishing images to the own registry](decisions/registry-publishing.md).
## 2026-10-23 (PR #16 review checked, three findings applied)
* **Update**: [pr-checker.yml](../.gitea/workflows/pr-checker.yml) - the review prompt now states that `pnpm-lock.yaml` is excluded from `.pr-review-diff.patch` on purpose. The reviewer read the exclusion as an uncommitted lockfile and raised a false BLOCKER; the lockfile is in the PR and matches `package.json`.
* **Fix**: `scripts/generate-favicon.mjs` - `BACKGROUND = null` now writes alpha 0 instead of opaque black, matching the transparency the comment promises. The committed icons are unchanged (regenerated byte-identical).
* **Update**: deleted `public/_robots.txt` - unreferenced leftover from the rename; `@nuxtjs/seo` writes `robots.txt` itself.
## 2026-10-23 (Nuxt SEO configured, static OG card)
* **Decision**: Recorded [SEO stack and site metadata](decisions/seo-and-metadata.md) - `@nuxtjs/seo` 6.0.1 registered; `site` and `schemaOrg.identity` (Person) read `site.config.mjs`; canonical, sitemap, robots and social tags need no per-page setup. `ogImage: false` and `skewProtection: false` because the card is a committed PNG and the site deploys as static files.
* **Update**: `public/og-image.png` (1200x630) and `og-image.alt.txt` generated from the pixel avatar and the site metadata by `pnpm og-image` (`scripts/generate-og-image.mjs`; needs `woff2_decompress` + `rsvg-convert`, output committed). SEO Utils emits `og:image`, `twitter:image` and their dimensions/alt automatically.
* **Detail**: `app/pages/index.vue` sets the title to `Noel Sabia — <role>` and `twitter:card: summary_large_image`; `useHead({ titleTemplate: '%s' })` removes the `| Noel Sabia` suffix SEO Utils would add. `theme-color` is `#031428`.
* **Detail**: `engines.node` is `^22.22.3 || ^24.15.0 || >=26.0.0`, the floor `@nuxtjs/seo` 6 enforces. Verified `nuxt build` and `nuxt generate`: canonical is `https://noelsabia.dev/`, sitemap has one URL, robots allows crawling and names the sitemap, schema graph carries the Person node, and all SEO assets return 200.
## 2026-10-23 (generated pixel favicon)
* **Update**: `public/favicon.svg` and `public/favicon.ico` are generated from the header's pixel avatar by `pnpm favicon` (`scripts/generate-favicon.mjs`). No image library: the ICO is an uncompressed 32bpp BMP in a one-image ICO container (4.2 kB) and the SVG merges same-coloured cells into per-row runs (3.7 kB); a 256px render of both matches.
* **Update**: `app/utils/avatar.js` now holds the palette and the 32x32 sprite as the single source, imported by `AppLogo.vue` and by the generator (plain JS, so Node can import it without a loader). `app.head.link` declares the SVG first and the ICO as the `32x32` fallback.
* **Detail**: the icon keeps the header chip colour `#1b2b3f` as its background so the portrait stays readable on a dark tab bar; `BACKGROUND = null` in the generator makes it transparent.
## 2026-10-23 (icons from Nuxt Icon, icon webfont removed)
* **Decision**: Recorded [Icons via Nuxt Icon](decisions/icons-via-nuxt-icon.md) - all icons come from `@nuxt/icon` with `@iconify-json/material-symbols` installed locally, `mode: 'svg'`, `serverBundle: { collections: [] }`, `clientBundle: { scan: true }`. Deleted `public/fonts/material-symbols-outlined-var.woff2` (3.9 MiB), its `@font-face` and the `.material-symbols-outlined` class in `app/assets/css/main.css`. Build reports 3 icons, 1.23 kB; SSR HTML carries the inline `<svg>`.
* **Update**: The module's defaults would have called `api.iconify.design` at runtime (`mode: css`, `fallbackToApi: true`), which the local collection avoids; `serverBundle: 'auto'` would have bundled the whole set as an 8 MB server chunk.
## 2026-10-20 (cheaper review model, cached installs, merged checks)
* **Update**: [pr-checker.yml](../.gitea/workflows/pr-checker.yml) - the review model is now `opencode-go/claude-haiku-5-5#medium`: cheap per token and, unlike `deepseek-v4.1-flash`, it has a real `#medium` effort level (flash exposes only low/high/max). ESLint and typecheck are merged into one `checks` job with a single `pnpm install`, and the pnpm store plus the opencode binary are restored with `actions/cache@v4.1.0` (v1 cache API, so it also works on a v1-only runner). Cache keys are built from `sha256sum pnpm-lock.yaml`, the pnpm store layout (`v11`) and the opencode version in shell steps, because `hashFiles()` evaluates empty in this act runner. See [AI review setup](decisions/ai-review-setup.md) and [PR pipeline layering](decisions/pr-pipeline-layering.md).