# Spec v8 — SEO hardening & security headers (response to the 2026-10-29 site audit) Status: **implemented 2026-10-29 (repo side)** — Stages 1–3 built and verified locally: route pages + real 404 (nginx 1.31 end-to-end test), security headers in Report-Only form + gzip, heading hierarchy + diagram rendering + og dimensions. Automated checks green (`build`, `validate:content`, `lint`, `nginx -t`). Open: owner browser walkthrough (project rule 5), the CSP console observation before enforcement (D5), and the Stage 4 / D3 decisions (§6). Source: `docs/feedback/site-audit-2026-10-29-en.md` (audit of https://cv.vugado.com/, 29 Oct 2026). This spec records the audit's findings verified against the repository, the proposed fix for each, and the options for everything the audit leaves to owner judgement. ## 1. Audit findings verified against the repository Every confirmed finding is real in this codebase. Evidence: |Audit item|Repo evidence|Confirmed| |---|---|---| |4.1 Same title/description on all pages; canonical + og:url → homepage|`index.html` is the only HTML document: one title/description, `canonical` → `%SITE_URL%/` (`index.html:15`), `og:url` → `%SITE_URL%/` (`:24`); no per-route metadata anywhere. `scripts/generate-sitemap.ts` lists 9 URLs — the sitemap contradicts the canonicals|Yes| |4.2 Unknown URL returns 200 + empty main (soft 404)|`nginx.conf` `location / { try_files $uri $uri/ /index.html; }` → 200 for any unknown path; `src/App.tsx` has no `path="*"` route → Layout with an empty `
`|Yes| |4.3 Missing CSP / HSTS / X-Frame-Options / nosniff / Referrer-Policy / Permissions-Policy|No security header appears in `nginx.conf`|Yes| |4.4 Content exists only after JavaScript|`index.html:88` — `
`; all text is client-rendered|Yes| |4.5 Language invisible to crawlers; no hreflang; og:locale stays `en_US`|`src/hooks/useLanguage.tsx` — language is localStorage only (`portfolio-lang`), URL never changes; `index.html:25` fixed `og:locale`|Yes| |4.6 JS/CSS uncompressed while HTML is compressed|`nginx.conf` declares no `gzip_types` → nginx's default compresses `text/html` only|Yes| |4.7 No H1 on About / Experience / Projects / Contact / Philosophy / How it works|The only H1 is `Hero.tsx:50`; `SectionHeading.tsx:16` renders `

` and is the top heading on every standalone page|Yes| |4.7 Project detail skips H2 (H1 → H3)|`ProjectDetailPage.tsx:70` h1 → `:105,:125,:137,:152` h3; section titles `:179` h4|Yes| |4.7 Raw Markdown code fences on IoT-DWS|`src/i18n/locales/vi/content/projects.json:24,:54` — ```` ```text ```` ASCII diagrams in `iot-dws-integration.sections.architecture` and `awb-detection.sections.pipeline`. The EN document lacks these fields → the per-field VI fallback renders the fences in **both** languages. `ProjectDetailPage.tsx:183` renders every section as `

` regardless of its type|Yes| |4.7 "Internal text/diagram labels" on the public page|`ProjectDetailPage.tsx:184` renders `{section.type}` — the internal `text`/`diagram` type chip is printed on every section card in view mode. The structure document already declares `"type": "diagram"` (`src/data/projects.json:28,:62`) but no rendering path exists for it|Yes| |4.7 og:image declares 1200×1600; file is 500×667|`index.html:28-29`; `public/profile-photo.webp` measures 500×667 (VP8X header, verified 2026-10-29)|Yes| |§5 sitemap lastmod = build date, not content change date|`scripts/generate-sitemap.ts:26` `new Date()`|Yes| Also checked against the audit's §4.6 note ("editor code must not inflate the initial download"): already satisfied — pages and `EditModeShell` are lazy chunks (`App.tsx`). No work needed. Not confirmed as defects (audit §5, general recommendations): content/copy review, device visual testing, accessibility walkthrough, Search Console — owner-side activities, listed in §7. ## 2. Stage 1 — per-route HTML + genuine 404 (fixes 4.1, 4.2; partial 4.4) One mechanism solves both findings: the build emits a real file per route, each carrying its own metadata. **Decision D1 (proposed):** build-time route generation from the existing data layer, not SSR and not a client-side meta library. The per-route manifests (`src/data/pages/*.json`) already declare which entity fields and UI groups each page renders — the generator reuses them, so per-route metadata is a JSON concern, never a component concern. ### 2.1 Implementation details - New `scripts/generate-route-pages.ts` (`pnpm generate:routes`, wired into `pnpm build` after `vite build`, before `pnpm sitemap`): - Reads `dist/index.html` as the head template and the site identity the same way `generate-sitemap.ts` does (guard: `SITE_URL` must appear in the built head). - For every route in `navPaths` plus every `/projects/{id}` from the project data: writes `dist//index.html` with — - `canonical` + `og:url` + `og:title` + `og:description` + `twitter:*` + `description` specific to that route; - localized strings from the dictionaries: static pages read a **new `ui/meta.json` group** keyed by `PageId` (`{ title, description }` per language); project pages reuse the existing content records (`title` + `summary`) — no new keys; - the body stays the empty `#root` + `