mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-23 00:20:40 +07:00
seo: per-route HTML + genuine 404, security headers, heading hierarchy (spec-v8)
Stage 1 (audit 4.1/4.2/4.4): scripts/generate-route-pages.ts (pnpm generate:routes, chained into build before the sitemap) rewrites the built head per route — title/description/canonical/og/twitter from the new ui/meta group (the six static manifests claim it) or from the project records — adds manifest-claimed <noscript> bodies and writes dist/404.html; nginx.conf resolves each URL against its generated file (try_files $uri/index.html $uri =404 + server-level error_page) so known routes answer 200 at the exact URL and unknown URLs a real 404; App.tsx adds the lazy catch-all route + src/pages/NotFoundPage.tsx for dead links inside the SPA (ui/common notFound keys, EN+VI); generate-sitemap.ts derives lastmod from the git history of the documents backing each URL and fails the build when a sitemap URL has no generated route file. Stage 2 (audit 4.3/4.6): nginx.conf only — CSP (Report-Only, script-src carries the theme-init inline script hash, verified against the built bytes by the route generator), HSTS, nosniff, Referrer-Policy, Permissions-Policy, X-Frame-Options at server level and repeated in the two blocks that declare their own add_header; gzip_types for CSS/JS/JSON/SVG/XML with the hashed-asset immutable caching preserved. Stage 3 (audit 4.7): SectionHeading gains level='h1'|'h2' and the six standalone pages render their top heading as h1; project detail blocks move h3->h2 and section titles h4->h3; diagram/code sections render in <pre class=project-diagram>, the Markdown fences are stripped from the two VI ASCII diagrams, the internal section-type chip renders only in edit mode; og:image declares the real 500x667. docs: the 2026-10-29 site audit and spec-v8-seo-hardening (stages 1-3 repo-side DONE; owner browser walkthrough, CSP enforcement decision D5 and stage 4 D4 open).
This commit is contained in:
1 parent
e02fe19bbe
commit
0dd2c6b3ee
32 files changed
+1180
-46
No files matched your search
@@ -23,7 +23,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
| Command | Description |
|
| Command | Description |
|
||||||
|---------|-------------|
|
|---------|-------------|
|
||||||
| `pnpm dev` | Start dev server with HMR |
|
| `pnpm dev` | Start dev server with HMR |
|
||||||
| `pnpm build` | Type-check (`tsc -b`), build for production (the site-identity plugin fills `%SITE_URL%` / `%SITE_NAME%` in `index.html`), then generate `dist/sitemap.xml` + `dist/robots.txt` |
|
|`pnpm build`|Type-check (`tsc -b`), build for production (the site-identity plugin fills `%SITE_URL%` / `%SITE_NAME%` in `index.html`), then generate the per-route pages (`dist/<route>/index.html` + `dist/404.html`), then `dist/sitemap.xml` + `dist/robots.txt`|
|
||||||
| `pnpm build:resume` | Generate resume PDF (default EN) via Playwright |
|
| `pnpm build:resume` | Generate resume PDF (default EN) via Playwright |
|
||||||
| `pnpm build:resume-all` | Generate bilingual resume PDFs (EN + VI) |
|
| `pnpm build:resume-all` | Generate bilingual resume PDFs (EN + VI) |
|
||||||
| `pnpm lint` | Run Oxlint |
|
| `pnpm lint` | Run Oxlint |
|
||||||
@@ -53,6 +53,7 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript
|
|||||||
| `/contact` | `ContactPage` | Contact info |
|
| `/contact` | `ContactPage` | Contact info |
|
||||||
| `/philosophy` | `PhilosophyPage` | Engineering philosophy |
|
| `/philosophy` | `PhilosophyPage` | Engineering philosophy |
|
||||||
| `/how-it-works` | `HowItWorksPage` | Intro video: git-backed content, live editing, CI deploy |
|
| `/how-it-works` | `HowItWorksPage` | Intro video: git-backed content, live editing, CI deploy |
|
||||||
|
| `*` (catch-all) | `NotFoundPage` | In-app 404 for dead links inside the SPA; direct hits on unknown URLs are answered by nginx with a real 404 + the generated `404.html` |
|
||||||
|
|
||||||
## Theming
|
## Theming
|
||||||
|
|
||||||
@@ -77,7 +78,7 @@ Content is split once, at authoring time, into language-neutral **structure docu
|
|||||||
- `src/data/skills.json` + `skills.ts` loader — skill groups: `{id, skills}`; group titles are text
|
- `src/data/skills.json` + `skills.ts` loader — skill groups: `{id, skills}`; group titles are text
|
||||||
- `src/data/experience.json` + `experience.ts` loader — work history: id / location / logo / optional `variant: 'current' | 'gap'` (timeline decoration: live node / career break); company, duration, titles and responsibilities are text — the VI document carries localized dates ("11/2026 – nay") and company labels, en overrides with the originals, proper nouns identical per language
|
- `src/data/experience.json` + `experience.ts` loader — work history: id / location / logo / optional `variant: 'current' | 'gap'` (timeline decoration: live node / career break); company, duration, titles and responsibilities are text — the VI document carries localized dates ("11/2026 – nay") and company labels, en overrides with the originals, proper nouns identical per language
|
||||||
- `src/data/projects.json` + `projects.ts` loader — cards: category / technologies / featured / `sections[].{id, type}`; titles, summaries, role, metrics and section prose are text (role follows the owner's EN title convention; metrics are localized)
|
- `src/data/projects.json` + `projects.ts` loader — cards: category / technologies / featured / `sections[].{id, type}`; titles, summaries, role, metrics and section prose are text (role follows the owner's EN title convention; metrics are localized)
|
||||||
- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy.<id>.{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 15 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `howItWorks`, `resume`, `edit`, `common`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission
|
- `src/i18n/locales/{vi,en}/content/{profile,skills,experience,projects}.json` — all content text, one file per entity, keyed by the structure ids; the `profile` record is fixed-keyed (`name`, `title`, `bio`, `subtitle`, `tldr`, `tagline`, `currentInterests`, `roles`, `philosophyQuotes`, `philosophy.<id>.{title, description, keywords}`); `src/i18n/locales/{vi,en}/ui/{group}.json` — 16 chrome groups (`navigation`, `footer`, `social`, `hero`, `about`, `expertise`, `experience`, `projects`, `projectDetail`, `contact`, `philosophy`, `howItWorks`, `resume`, `edit`, `common`, `meta`), in each language (nav group labels, Mode options, language names `langEn` / `langVi`, action labels, social `aria-label`s, the resume's section labels, edit-mode labels, the `notFound` 404 texts, and `meta` — the per-page SEO title/description the route generator writes into each page's head, keyed by PageId for the six static pages and claimed by exactly those six manifests; project pages derive their meta from the content records instead) — person text never lives here; `src/i18n/index.ts` merges both trees back into the same `UI`/`CONTENT` records and asserts the merge against the group lists — a group dropped in the split is a load-time error, never a silent omission
|
||||||
- Content ids and the category values a project uses are **generated**, never hand-maintained (spec: `docs/design/specs/v5/spec-v5-generated-content-ids.md`): `scripts/generate-content-types.ts` reads the four structure documents and writes `src/types/content-ids.ts` (gitignored) under `predev` / `prebuild` / `prepare`; `src/types/index.ts` re-exports those unions type-only and keeps only the code-owned ones (`Language`, `Palette`, `SocialId`, `PageId`, manifest types). A content add or delete touches JSON only — a text entry left behind by a deleted record is a `tsc` error (`TS2741`), never a stale union member — and a category with no label in either language is a validator error naming both `ui/projects.json` files (rule 7)
|
- Content ids and the category values a project uses are **generated**, never hand-maintained (spec: `docs/design/specs/v5/spec-v5-generated-content-ids.md`): `scripts/generate-content-types.ts` reads the four structure documents and writes `src/types/content-ids.ts` (gitignored) under `predev` / `prebuild` / `prepare`; `src/types/index.ts` re-exports those unions type-only and keeps only the code-owned ones (`Language`, `Palette`, `SocialId`, `PageId`, manifest types). A content add or delete touches JSON only — a text entry left behind by a deleted record is a `tsc` error (`TS2741`), never a stale union member — and a category with no label in either language is a validator error naming both `ui/projects.json` files (rule 7)
|
||||||
- `src/data/pages/{home,about,experience,projects,project-detail,contact,philosophy,how-it-works,resume}.json` + `pages.ts` loader — per-route manifests: which entity fields the page renders (`fields[]`; `*` = every field the record id owns) and which UI groups it reads; `src/types/index.ts` carries `PageId` / `PageManifestClaim` / `PageManifest`. A manifest describes the whole page, chrome included — the footer renders `profile.name` on every route, so every manifest claims it. The validator enforces: no unknown entity, no unknown UI group, no unresolvable field path, **no orphan text field** (every text leaf in the content documents is claimed by at least one manifest), no missing manifest for a route in `src/data/navigation.ts` plus `/projects/:id`
|
- `src/data/pages/{home,about,experience,projects,project-detail,contact,philosophy,how-it-works,resume}.json` + `pages.ts` loader — per-route manifests: which entity fields the page renders (`fields[]`; `*` = every field the record id owns) and which UI groups it reads; `src/types/index.ts` carries `PageId` / `PageManifestClaim` / `PageManifest`. A manifest describes the whole page, chrome included — the footer renders `profile.name` on every route, so every manifest claims it. The validator enforces: no unknown entity, no unknown UI group, no unresolvable field path, **no orphan text field** (every text leaf in the content documents is claimed by at least one manifest), no missing manifest for a route in `src/data/navigation.ts` plus `/projects/:id`
|
||||||
- `src/i18n/index.ts` — load + validate + join ONCE at module load; exports `UI` and `CONTENT` as `Record<Language, Resolved…>`; `src/i18n/dict-types.ts` carries the document types; `src/i18n/validate.ts` + `scripts/validate-content.ts` enforce the cross-document rules (orphan or missing keys, HTML markup in text values, the manifest rules above) — a malformed document fails `pnpm build`, CI, and the browser load, never a silent half-render
|
- `src/i18n/index.ts` — load + validate + join ONCE at module load; exports `UI` and `CONTENT` as `Record<Language, Resolved…>`; `src/i18n/dict-types.ts` carries the document types; `src/i18n/validate.ts` + `scripts/validate-content.ts` enforce the cross-document rules (orphan or missing keys, HTML markup in text values, the manifest rules above) — a malformed document fails `pnpm build`, CI, and the browser load, never a silent half-render
|
||||||
@@ -142,12 +143,13 @@ video/ # standalone Remotion project (spec-v7-intro-video), a pnpm work
|
|||||||
- `public/resume-logos/` — official company logo SVGs (Lazada, SAP from Wikimedia Commons), embedded in the resume timeline via `ExperienceEntry.logo`
|
- `public/resume-logos/` — official company logo SVGs (Lazada, SAP from Wikimedia Commons), embedded in the resume timeline via `ExperienceEntry.logo`
|
||||||
- `public/resume-qr/` — owner-supplied QR images (`telegram.jpg`, `zalo.jpg`) embedded in the resume header via `resumeQr` in `src/data/resume.ts`; committed like the other resume assets, so CI renders the QR block too — a missing file prints a warning and that QR is skipped
|
- `public/resume-qr/` — owner-supplied QR images (`telegram.jpg`, `zalo.jpg`) embedded in the resume header via `resumeQr` in `src/data/resume.ts`; committed like the other resume assets, so CI renders the QR block too — a missing file prints a warning and that QR is skipped
|
||||||
- `public/profile-photo.webp` — profile photo
|
- `public/profile-photo.webp` — profile photo
|
||||||
- `robots.txt` is generated, not committed: `scripts/generate-sitemap.ts` writes `dist/robots.txt` (allow-all + the `Sitemap:` pointer) from the same `SITE_URL` the sitemap uses — no `public/robots.txt` exists anymore
|
- `robots.txt` is generated, not committed: `scripts/generate-sitemap.ts` writes `dist/robots.txt` (allow-all + the `Sitemap:` pointer) from the same `SITE_URL` the sitemap uses — no `public/robots.txt` exists anymore; the sitemap's `lastmod` per URL is the newest git commit touching the documents that back that page (manifest, claimed entity documents, claimed UI groups), falling back to the build date only when git is unavailable, and a guard refuses any sitemap URL whose generated route file is missing
|
||||||
|
|
||||||
## Scripts
|
## Scripts
|
||||||
|
|
||||||
- `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi)
|
- `scripts/generate-resume.ts` — Playwright-based PDF resume generator (bilingual en/vi)
|
||||||
- `scripts/generate-content-types.ts` — writes `src/types/content-ids.ts` from the four structure documents (`pnpm generate:ids`, wired as `predev` / `prebuild` / `prepare`): the id unions and the project category values in document order, `never` for an emptied document, a duplicate id refused with the file named
|
- `scripts/generate-content-types.ts` — writes `src/types/content-ids.ts` from the four structure documents (`pnpm generate:ids`, wired as `predev` / `prebuild` / `prepare`): the id unions and the project category values in document order, `never` for an emptied document, a duplicate id refused with the file named
|
||||||
|
- `scripts/generate-route-pages.ts` — the route-page generator (`pnpm generate:routes`, run by `build` after `vite build`, before the sitemap step; spec-v8 §2): rewrites `dist/index.html`'s head per route with page-specific title/description/canonical/og (static pages from the `meta` UI group, project pages from their content records), adds a manifest-claimed `<noscript>` body to every page, writes `dist/404.html` (client-free links + `<meta http-equiv="refresh">` to `/`), and fails the build when an inline script's SHA-256 no longer matches the CSP hash in `nginx.conf`
|
||||||
- `scripts/smoke-draft.ts` — regression check of the draft-store semantics (`pnpm tsx scripts/smoke-draft.ts`): accept/reject paths, empty-required rejection, orphan-free record delete, template creation, id re-sluging on rename, snapshot round-trip, conflict detection, clean rebase, the category-label rule, the scoped-baseline rules of spec-v4-live-edit §5.1 (an adopted baseline replaces an untouched document only; a bundle-seeded document is never PUT over the branch), and the 409 path of spec-v6 D5 (a conflict refreshes the base, keeps the draft, and never stops the sequence)
|
- `scripts/smoke-draft.ts` — regression check of the draft-store semantics (`pnpm tsx scripts/smoke-draft.ts`): accept/reject paths, empty-required rejection, orphan-free record delete, template creation, id re-sluging on rename, snapshot round-trip, conflict detection, clean rebase, the category-label rule, the scoped-baseline rules of spec-v4-live-edit §5.1 (an adopted baseline replaces an untouched document only; a bundle-seeded document is never PUT over the branch), and the 409 path of spec-v6 D5 (a conflict refreshes the base, keeps the draft, and never stops the sequence)
|
||||||
- `scripts/smoke-generated-ids.ts` — regression check of the generator (`pnpm tsx scripts/smoke-generated-ids.ts`): the shipped module equals the shipped documents, byte-stable output, `never` for emptied documents, malformed documents refused with the file named
|
- `scripts/smoke-generated-ids.ts` — regression check of the generator (`pnpm tsx scripts/smoke-generated-ids.ts`): the shipped module equals the shipped documents, byte-stable output, `never` for emptied documents, malformed documents refused with the file named
|
||||||
|
|
||||||
@@ -158,6 +160,7 @@ video/ # standalone Remotion project (spec-v7-intro-video), a pnpm work
|
|||||||
- Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are GitHub **repository variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable
|
- Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are GitHub **repository variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable
|
||||||
- The stack directory and the container name are deployment-time configuration as well: both workflows read the stack path from the repository variable `STACK_DIR` — absolute, **no trailing slash**, because the jobs append `/dist/` and `/` themselves — and the infra job reads the compose service / container name it recreates and probes from `CONTAINER_NAME`. Each job refuses a bad value in its first step, before any artifact download or rsync reaches the VPS, and the infra guard greps `compose.yaml` so `CONTAINER_NAME` cannot disagree with the service and `container_name` this repository declares (spec-v6 D15)
|
- The stack directory and the container name are deployment-time configuration as well: both workflows read the stack path from the repository variable `STACK_DIR` — absolute, **no trailing slash**, because the jobs append `/dist/` and `/` themselves — and the infra job reads the compose service / container name it recreates and probes from `CONTAINER_NAME`. Each job refuses a bad value in its first step, before any artifact download or rsync reaches the VPS, and the infra guard greps `compose.yaml` so `CONTAINER_NAME` cannot disagree with the service and `container_name` this repository declares (spec-v6 D15)
|
||||||
- Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `${{ vars.STACK_DIR }}/dist/`
|
- Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `${{ vars.STACK_DIR }}/dist/`
|
||||||
|
- `nginx.conf` also carries the SEO/security layer (spec-v8): `location /` resolves each URL against its generated file — `try_files $uri/index.html $uri =404` (the composite first parameter is deliberate: a bare `$uri`/`$uri/` on a directory makes nginx 301 `/about` → `/about/`, which would break canonical/sitemap/internal-link identity) — so known routes serve 200 at the exact URL and unknown URLs get a genuine 404 answered by `dist/404.html` via a server-level `error_page`; the six security headers (`X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options: DENY`, `Permissions-Policy`, HSTS, and a CSP **in Report-Only form** — enforcing after the owner observes `Report-Only-Violation` reports, D5; its `script-src` hashes must match the inline scripts, guarded by `generate-route-pages.ts`) are server-level so they cover every response including 404s; `gzip on` with explicit `gzip_types` (CSS/JS/JSON/SVG/XML — HTML is nginx's always-on default type; the already-compressed images/PDFs/video are not types) compresses the transferred bodies
|
||||||
- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`/etc/nginx/htpasswd` — the file is **not committed**: `deploy-infra.yml` writes it on the VPS from the `HTPASSWD_CONTENT` repository secret, spec-v6 D16) in front of a proxied Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec-v4 D14, verified against `api.github.com` 2026-10-26; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template carries only `${CONTENT_API_BASE}` and `Bearer ${CONTENT_API_TOKEN}` — the token and the git host never enter the SPA bundle or the repository). The image's envsubst step renders the template **before nginx parses it**, so `proxy_pass` is a literal upstream rather than an nginx variable — the reason the location-prefix → directive-URI mapping works and the reason a placeholder in `proxy_pass` must be a resolvable literal IP (spec-v6 D4a)
|
- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`/etc/nginx/htpasswd` — the file is **not committed**: `deploy-infra.yml` writes it on the VPS from the `HTPASSWD_CONTENT` repository secret, spec-v6 D16) in front of a proxied Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec-v4 D14, verified against `api.github.com` 2026-10-26; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template carries only `${CONTENT_API_BASE}` and `Bearer ${CONTENT_API_TOKEN}` — the token and the git host never enter the SPA bundle or the repository). The image's envsubst step renders the template **before nginx parses it**, so `proxy_pass` is a literal upstream rather than an nginx variable — the reason the location-prefix → directive-URI mapping works and the reason a placeholder in `proxy_pass` must be a resolvable literal IP (spec-v6 D4a)
|
||||||
- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `CONTENT_API_TOKEN=` / `CONTENT_API_BASE=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml`; `deploy/htpasswd` is the exception (spec-v6 D16): it is gitignored, lives only on the server (written by the infra job from the `HTPASSWD_CONTENT` secret) and as an untracked local copy for the local compose mount
|
- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `CONTENT_API_TOKEN=` / `CONTENT_API_BASE=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml`; `deploy/htpasswd` is the exception (spec-v6 D16): it is gitignored, lives only on the server (written by the infra job from the `HTPASSWD_CONTENT` secret) and as an untracked local copy for the local compose mount
|
||||||
- `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected
|
- `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected
|
||||||
@@ -221,6 +224,7 @@ All specification documents are in `docs/design/`:
|
|||||||
| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope. `spec-v4-deploy-infra.md`: pipeline redeploy of the VPS nginx container, Dockge-managed stack (paths-filtered `deploy-infra.yml`, test-before-touch, repo-as-source-of-truth, token-safety rules) + externalizing site identity — `SITE_URL` / `SITE_NAME` as CI Actions variables, `GITEA_TOKEN` + `GITEA_CONTENTS_API` in the stack's single config file `secrets/site_config` — repo side implemented 2026-10-23 (`deploy-infra.yml`, `compose.yaml` secret + entrypoint override, env-driven identity); owner-side variables/config file + first verified run pending |
|
| `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope. `spec-v4-deploy-infra.md`: pipeline redeploy of the VPS nginx container, Dockge-managed stack (paths-filtered `deploy-infra.yml`, test-before-touch, repo-as-source-of-truth, token-safety rules) + externalizing site identity — `SITE_URL` / `SITE_NAME` as CI Actions variables, `GITEA_TOKEN` + `GITEA_CONTENTS_API` in the stack's single config file `secrets/site_config` — repo side implemented 2026-10-23 (`deploy-infra.yml`, `compose.yaml` secret + entrypoint override, env-driven identity); owner-side variables/config file + first verified run pending |
|
||||||
| `specs/v5/spec-v5-*.md` | v5 feature specs. `spec-v5-generated-content-ids.md`: the content id unions and the project category values are generated from the structure documents (`scripts/generate-content-types.ts`, run by `predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages — implemented 2026-10-24; it supersedes the id-union legs of `spec-v4-live-edit.md` §3.1 |
|
| `specs/v5/spec-v5-*.md` | v5 feature specs. `spec-v5-generated-content-ids.md`: the content id unions and the project category values are generated from the structure documents (`scripts/generate-content-types.ts`, run by `predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages — implemented 2026-10-24; it supersedes the id-union legs of `spec-v4-live-edit.md` §3.1 |
|
||||||
|`specs/v7/spec-v7-*.md`|v7 feature specs. `spec-v7-intro-video.md`: the 62-second Remotion-rendered explainer (`video/` workspace member → `public/media/`) shown on the new `/how-it-works` page — route, manifest, `howItWorks` UI group, EN/VI caption tracks, chapter seeking; the optional captured-footage variant awaits owner screen recordings — implemented 2026-10-28 (automated checks pass; browser walkthrough pending)|
|
|`specs/v7/spec-v7-*.md`|v7 feature specs. `spec-v7-intro-video.md`: the 62-second Remotion-rendered explainer (`video/` workspace member → `public/media/`) shown on the new `/how-it-works` page — route, manifest, `howItWorks` UI group, EN/VI caption tracks, chapter seeking; the optional captured-footage variant awaits owner screen recordings — implemented 2026-10-28 (automated checks pass; browser walkthrough pending)|
|
||||||
|
|`specs/v8/spec-v8-*.md`|v8 feature specs. `spec-v8-seo-hardening.md`: response to the 2026-10-29 site audit — build-time per-route HTML (`scripts/generate-route-pages.ts` rewrites the built head per route: page-specific title/description/canonical/og from the `meta` UI group or the project records, manifest-claimed `<noscript>` content, generated `404.html`), genuine nginx 404s (`try_files $uri/index.html $uri =404`), six security headers with CSP in Report-Only form + gzip, sitemap `lastmod` from git, H1 hierarchy + diagram `<pre>` rendering + og:image dimensions — implemented 2026-10-29 (repo side; nginx end-to-end verified in a 1.31 container; browser walkthrough + CSP enforcement decision owner-side)|
|
||||||
|`specs/v6/spec-v6-*.md`|v6 feature specs. `spec-v6-github-actions.md`: both pipelines move to GitHub Actions and the repository becomes GitHub-primary, the write-path values are renamed `CONTENT_API_TOKEN` / `CONTENT_API_BASE` with a `Bearer` upstream header, `draft.ts` learns GitHub's 409 conflict answer, the site keeps its VPS/nginx/Dockge host and its three-job pipeline, and the Basic-auth file leaves the repository — `deploy/htpasswd` is gitignored, the infra job writes it on the VPS from the `HTPASSWD_CONTENT` repository secret (D16, 2026-10-28) — repo side implemented 2026-10-26 (owner-side GitHub variables/secrets, the VPS `secrets/site_config` rewrite and the first verified run are open); it supersedes the CI-host legs of `spec-v4-deploy-infra.md` and the Contents-API status codes of `spec-v4-live-edit.md` §6.1|
|
|`specs/v6/spec-v6-*.md`|v6 feature specs. `spec-v6-github-actions.md`: both pipelines move to GitHub Actions and the repository becomes GitHub-primary, the write-path values are renamed `CONTENT_API_TOKEN` / `CONTENT_API_BASE` with a `Bearer` upstream header, `draft.ts` learns GitHub's 409 conflict answer, the site keeps its VPS/nginx/Dockge host and its three-job pipeline, and the Basic-auth file leaves the repository — `deploy/htpasswd` is gitignored, the infra job writes it on the VPS from the `HTPASSWD_CONTENT` repository secret (D16, 2026-10-28) — repo side implemented 2026-10-26 (owner-side GitHub variables/secrets, the VPS `secrets/site_config` rewrite and the first verified run are open); it supersedes the CI-host legs of `spec-v4-deploy-infra.md` and the Contents-API status codes of `spec-v4-live-edit.md` §6.1|
|
||||||
|
|
||||||
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope.
|
||||||
|
|||||||
@@ -0,0 +1,211 @@
|
|||||||
|
# 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 `<main>`|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` — `<div id="root"></div>`; 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 `<h2>` 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 `<p>` regardless of its type|Yes|
|
||||||
|
|4.7 "Internal text/diagram labels" on the public page|`ProjectDetailPage.tsx:184` renders `<Tag accent>{section.type}</Tag>` — 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/<route>/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` + `<script type="module">` — the SPA boots from any shell exactly as it does today;
|
||||||
|
- optionally a `<noscript>` block generated from the manifest claims (page heading, nav links, claimed content text) — Decision D4 (§6).
|
||||||
|
- Writes `dist/404.html`: localized from new `notFound` keys in `ui/common.json` (title, message, links to `/` and `/projects`), linking the build's hashed CSS (the script reads the asset filename from `dist/index.html`) plus a small inline `<style>` for the `.not-found` layout using the site's CSS variables.
|
||||||
|
- Registers the `meta` group in `src/i18n/index.ts`, `dict-types.ts`, `validate.ts` group lists; every manifest claims it (the page's own metadata is part of the page — the orphan-text rule then covers it).
|
||||||
|
- `nginx.conf` — real 404 for unknown URLs:
|
||||||
|
```nginx
|
||||||
|
location / {
|
||||||
|
try_files $uri/index.html $uri =404;
|
||||||
|
}
|
||||||
|
|
||||||
|
error_page 404 /404.html;
|
||||||
|
```
|
||||||
|
Known routes hit their generated file → 200 at the exact URL. The first
|
||||||
|
parameter is the composite file path: nginx's bare-directory semantics
|
||||||
|
301 `/about` → `/about/`, which would break the audit's consistency
|
||||||
|
requirement (canonicals, internal links and sitemap URLs are slashless);
|
||||||
|
pointing at `/<route>/index.html` directly serves the exact URL with 200.
|
||||||
|
Unknown URLs → genuine 404 + the localized 404 page. `error_page` is at
|
||||||
|
server level so asset misses are answered with the same 404 page at a 404
|
||||||
|
status. The two changes are coupled on purpose: the 404 correctness depends
|
||||||
|
on the route files existing, so they ship in one step, and
|
||||||
|
`generate-sitemap.ts` fails the build when a sitemap URL has no file.
|
||||||
|
- `src/App.tsx` — add `<Route path="*" element={<NotFoundPage />} />` (named export, lazy like the other non-LCP pages). Covers client-side navigation to a dead link and `pnpm preview`/dev-server parity (vite preview keeps its SPA fallback and answers 200 — the client page is what a visitor sees there).
|
||||||
|
- `src/pages/NotFoundPage.tsx` — new page: heading + message from `ui/common.notFound`, links to `/` and `/projects`, standard `InView` + item motion recipe.
|
||||||
|
- `scripts/generate-sitemap.ts` — `lastmod` per URL from the git history of the documents that back it: the script already knows each route's manifest claims, so lastmod = the newest commit date among the claimed structure/content/UI files (project detail pages: `projects.json` + both `content/projects.json` + both `ui/projects.json`). Fallback to the build date only if git is unavailable.
|
||||||
|
|
||||||
|
### 2.2 Affected files
|
||||||
|
|
||||||
|
|File|Change|
|
||||||
|
|---|---|
|
||||||
|
`scripts/generate-route-pages.ts`|new|
|
||||||
|
`package.json`|`generate:routes` script; `build` chain extended|
|
||||||
|
`src/i18n/locales/{en,vi}/ui/meta.json`|new group (9 static pages… 8 PageIds × {title, description})|
|
||||||
|
`src/i18n/locales/{en,vi}/ui/common.json`|+ `notFound` keys|
|
||||||
|
`src/i18n/index.ts`, `dict-types.ts`, `validate.ts`|register the `meta` group|
|
||||||
|
`src/data/pages/*.json`|claim `meta`|
|
||||||
|
`nginx.conf:12-14`|`try_files … =404` + `error_page 404 /404.html`|
|
||||||
|
`src/App.tsx`|lazy import + catch-all route|
|
||||||
|
`src/pages/NotFoundPage.tsx`|new|
|
||||||
|
`scripts/generate-sitemap.ts:26`|git-derived lastmod|
|
||||||
|
|
||||||
|
### 2.3 Acceptance criteria (audit 4.1 + 4.2)
|
||||||
|
|
||||||
|
- [x] Each generated page's initial HTML contains its own title, description, og/twitter values and a self-referencing canonical; the homepage is no longer the canonical of any inner page. (Verified from `dist/about/index.html` and `dist/projects/iot-dws-integration/index.html`.)
|
||||||
|
- [x] `GET /seo-audit-not-found-20261029` → HTTP 404 with the 404 page body; all nine existing URLs still return 200 on direct navigation and refresh. (Verified against a live nginx 1.31 container serving `dist/` with the new config — every route 200 at the exact URL, no trailing-slash 301; unknown URL 404 + localized body.)
|
||||||
|
- [x] Sitemap URLs, canonicals and internal links are identical strings. (Same source: manifest routes + project ids; the `generate-sitemap.ts` route-file guard fails the build on any divergence.)
|
||||||
|
- [x] `pnpm build`, `pnpm validate:content`, `pnpm lint` green.
|
||||||
|
|
||||||
|
## 3. Stage 2 — security headers + compression (fixes 4.3, 4.6)
|
||||||
|
|
||||||
|
`nginx.conf` only; no application code.
|
||||||
|
|
||||||
|
### 3.1 Implementation details
|
||||||
|
|
||||||
|
- **Compression** (server level):
|
||||||
|
```nginx
|
||||||
|
gzip on;
|
||||||
|
gzip_types text/css application/javascript application/json image/svg+xml text/xml application/xml;
|
||||||
|
gzip_min_length 1024;
|
||||||
|
gzip_vary on;
|
||||||
|
gzip_comp_level 6;
|
||||||
|
```
|
||||||
|
The official nginx image carries no brotli module — Brotli would mean a custom image; gzip is the boring choice. The hashed-asset block keeps its `immutable` caching untouched (audit §4.6 requires preserving it).
|
||||||
|
- **Security headers.** nginx gotcha: `add_header` does not inherit into a block that declares its own `add_header` — `location = /index.html` and the asset block already set `Cache-Control`, so the header set must be written into every block that serves site responses (`location /`, `location = /index.html`, the asset regex). Kept in one file because the deploy pipeline rsyncs `nginx.conf` alone.
|
||||||
|
- `Strict-Transport-Security: max-age=31536000` — no `includeSubDomains` (subdomain readiness unverified).
|
||||||
|
- `X-Content-Type-Options: nosniff`
|
||||||
|
- `Referrer-Policy: strict-origin-when-cross-origin`
|
||||||
|
- `Permissions-Policy: geolocation=(), camera=(), microphone=()` — the site uses none of them.
|
||||||
|
- `X-Frame-Options: DENY` + CSP `frame-ancestors 'none'` (the pair the audit asks for).
|
||||||
|
- **CSP, Report-Only first** (audit's own instruction):
|
||||||
|
```
|
||||||
|
Content-Security-Policy-Report-Only: default-src 'self'; script-src 'self' 'sha256-<hash>';
|
||||||
|
style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none';
|
||||||
|
base-uri 'self'; form-action 'self'
|
||||||
|
```
|
||||||
|
`'unsafe-inline'` in `style-src` is required — motion writes inline style attributes. `script-src` needs the exact SHA-256 of the theme-init inline script in `index.html` (the hash is computed once and recorded in the config comment; **coupling: editing that script requires recomputing the hash**). No external origins exist today (no analytics, no embeds); the resume PDFs and QR/media assets are same-origin. Owner verifies the report-only console output in a real browser, then the header name drops `-Report-Only`.
|
||||||
|
- Config validation before touch already exists: `deploy-infra.yml` runs `nginx -t` with placeholders, then force-recreates and health-probes.
|
||||||
|
|
||||||
|
### 3.2 Affected files
|
||||||
|
|
||||||
|
`nginx.conf` only. `docs/design/specs/v4/spec-v4-deploy-infra.md` gets a pointer note if the header block is documented there.
|
||||||
|
|
||||||
|
### 3.3 Acceptance criteria (audit 4.3 + 4.6)
|
||||||
|
|
||||||
|
- [x] `curl -I` on a page, an asset and an error response shows the full header set; JS/CSS transfer compressed (`Content-Encoding: gzip`) when `Accept-Encoding` allows; HTML unchanged. (Verified against the live nginx 1.31 container: all six headers on `/about` and on a 404 response; gzip on JS/CSS only for accepting clients, none for a plain client.)
|
||||||
|
- [ ] Public pages, edit mode (auth probe iframe, Contents API proxy), resume dialog/PDF downloads and the video page work with CSP enforced. (Report-Only is live; enforcement is the owner's console observation — D5.)
|
||||||
|
- [x] No regression in the hashed-asset cache headers. (`immutable` caching preserved; verified on the served asset.)
|
||||||
|
- [x] `nginx -t` green with placeholder values, as `deploy-infra.yml` runs it before touch. (Verified in an nginx 1.31-alpine container 2026-10-29.)
|
||||||
|
|
||||||
|
## 4. Stage 3 — headings, diagram rendering, og:image (fixes 4.7)
|
||||||
|
|
||||||
|
### 4.1 Implementation details
|
||||||
|
|
||||||
|
- **Page H1s:** `SectionHeading` gains `level?: 'h1' | 'h2'` (default `'h2'` — current behaviour unchanged). Each standalone page passes `level="h1"` to its top heading; inner headings and the homepage keep `h2`. `App.css` `.section-heading` selectors audited and mirrored for the new level.
|
||||||
|
- **Project detail hierarchy:** `ProjectDetailPage.tsx` — the four `h3` block headings (`impact`, `role`, `technologies`, `experiments`) become `h2`; section-title `EditableText as="h4"` becomes `as="h3"`. Matching selectors in `App.css` updated. `ResumeDialog` heading stays as is (dialog internals are not part of the document outline).
|
||||||
|
- **Diagram sections:**
|
||||||
|
- `ProjectDetailPage.tsx`: `section.type === 'diagram'` renders the content in a `<pre className="project-diagram">` (monospace, `overflow-x: auto` for mobile); in edit mode `EditableText as="pre"`. `text` sections unchanged.
|
||||||
|
- `src/i18n/locales/vi/content/projects.json:24,:54`: strip the ```` ```text ````/```` ``` ```` fences — the fences are Markdown syntax for a renderer that does not exist here; the diagram text itself stays. EN keeps falling back to VI (unchanged behaviour).
|
||||||
|
- `ProjectDetailPage.tsx:184`: the `<Tag accent>{section.type}</Tag>` chip renders **only in edit mode** — it is an internal label, not public content.
|
||||||
|
- `RecordSettings` project-section type picker: confirm it offers `diagram` (the structure document already uses it); the generator (`generate-content-types.ts`) derives category values only, section types are free strings in the structure doc — validator unaffected.
|
||||||
|
- **og:image:** `index.html:28-29` — declare the real `500`×`667`. Optional Decision D3 (§6): generate a real 1200×630 share card.
|
||||||
|
|
||||||
|
### 4.2 Affected files
|
||||||
|
|
||||||
|
|File|Change|
|
||||||
|
|---|---|
|
||||||
|
`src/components/ui/SectionHeading.tsx`|`level` prop|
|
||||||
|
`src/pages/{AboutPage,ExperiencePage,ProjectsListPage,ContactPage,PhilosophyPage,HowItWorksPage}.tsx`|top heading `level="h1"`|
|
||||||
|
`src/pages/ProjectDetailPage.tsx:105,125,137,152,179,183-184`|h2/h3 hierarchy, `<pre>` diagram branch, edit-only type tag|
|
||||||
|
`src/i18n/locales/vi/content/projects.json:24,:54`|strip fences|
|
||||||
|
`src/App.css`|`.section-heading h1` variants, `.project-diagram`, project-detail selector renames|
|
||||||
|
|
||||||
|
### 4.3 Acceptance criteria (audit 4.7)
|
||||||
|
|
||||||
|
- [x] Every page has exactly one H1; no level skips (H1→H2→H3) on any page. (Implemented: SectionHeading `level="h1"` on the six standalone pages + the in-app 404 pages; project detail H1 → H2 blocks → H3 section titles; homepage unchanged. Visual walkthrough — owner.)
|
||||||
|
- [x] IoT-DWS architecture/pipeline diagrams render as formatted monospace blocks in both languages; no ```` ``` ```` visible; no `text`/`diagram` chips in view mode (present in edit mode). (Fences removed; `<pre class="project-diagram">` branch implemented; the type tag renders only in edit mode. Browser confirmation — owner.)
|
||||||
|
- [x] Declared og:image dimensions equal the actual file dimensions. (`index.html` now declares 500×667, the verified size of `public/profile-photo.webp`.)
|
||||||
|
|
||||||
|
## 5. Stage 4 — language versions for search (fixes 4.5) — decision, not yet design
|
||||||
|
|
||||||
|
The audit itself permits deprioritizing this. Two coherent options:
|
||||||
|
|
||||||
|
**Option A — language stays out of URLs (current model).** VI remains a visitor convenience; crawlers see the EN shells. No hreflang (it would be meaningless without distinct URLs). Zero work.
|
||||||
|
|
||||||
|
**Option B — `/vi/` prefix.** Real bilingual indexing:
|
||||||
|
- `useLanguage` derives the language from the path prefix (`/vi/...`) instead of localStorage alone; the switcher navigates to the same path with the prefix swapped (fixes "always to the homepage").
|
||||||
|
- The Stage 1 generator emits both language shells per route (`<html lang="vi">`, localized meta, self-canonical per language, `og:locale` per language) and reciprocal `hreflang` pairs + `x-default`.
|
||||||
|
- Sitemap lists both sets with hreflang; `navPaths`/`MobileMenu`/`Footer` link builders gain the prefix; edit mode is unaffected (it previews the branch's JSON, language is a render concern).
|
||||||
|
- Cost: a routing change touching every link surface + the generator; the manifests/PageIds stay identical.
|
||||||
|
|
||||||
|
Recommendation: adopt the Stage 1–3 work regardless; decide B only if VI search visibility is an actual goal.
|
||||||
|
|
||||||
|
## 6. Open decisions (owner review required before implementation)
|
||||||
|
|
||||||
|
|ID|Decision|Options|Recommended|
|
||||||
|
|---|---|---|---|
|
||||||
|
|D1|Approve Stage 1–3 as the implementation scope|Stage 1 only / 1–2 / 1–3 / 1–4|1–3|
|
||||||
|
|D2|Initial-HTML content depth (audit 4.4)|a) head shells only — fixes 4.1, not 4.4; b) shells + manifest-generated `<noscript>` body — satisfies the audit criterion with zero hydration risk; c) full `react-dom/server` prerender + `hydrateRoot` — best for no-JS users but needs SSR-safe providers (localStorage reads in `useLanguage`/`useTheme`/`edit-session` need guarded defaults) and carries hydration-mismatch risk|b|
|
||||||
|
|D3|Open Graph share image|a) declare the real 500×667 only; b) additionally generate a 1200×630 share card via a small Playwright script (dependency already exists) → `public/share-card.png`, og/twitter point at it, test previews incl. Zalo|a now, b as follow-up if link sharing matters|
|
||||||
|
|D4|Language URLs (§5)|A — keep localStorage model (audit-permitted deprioritization) / B — `/vi/` prefix + hreflang|A unless VI search visibility is a goal|
|
||||||
|
|D5|CSP rollout|Report-Only first, then enforce after owner console check (audit's instruction)|Report-Only first|
|
||||||
|
|
||||||
|
## 7. Out of repository scope (owner-side, from audit §5)
|
||||||
|
|
||||||
|
- Google Search Console verification, sitemap submission, URL Inspection after deploy.
|
||||||
|
- Certificate renewal monitoring.
|
||||||
|
- Device visual testing, keyboard/screen-reader walkthrough, contrast across palettes.
|
||||||
|
- Editor API auth review beyond the single HEAD probe; login-attempt limits and failed-auth logging (rate limiting on the server, not in this config today).
|
||||||
|
- CSRF: low risk as designed — auth is an `Authorization` header at the proxy, not cookie-based; recorded so it is not mistaken for an open finding.
|
||||||
|
- Copy review EN/VI and case-study structure (content decisions, JSON edits when decided).
|
||||||
|
|
||||||
|
## 8. Progress tracking
|
||||||
|
|
||||||
|
|Stage|Status|
|
||||||
|
|---|---|
|
||||||
|
§1 audit verification|DONE 2026-10-29 (all findings reproduced against the repo)|
|
||||||
|
Stage 1 — route pages + 404|DONE 2026-10-29 — `scripts/generate-route-pages.ts` in the build chain; 9 route files + 404.html; nginx end-to-end verified in a 1.31 container; in-app catch-all route|
|
||||||
|
Stage 2 — headers + gzip|DONE 2026-10-29 (repo side) — `nginx -t` green; headers + gzip verified on a live container; CSP is Report-Only: enforcement after the owner's console observation (D5)|
|
||||||
|
Stage 3 — headings + diagrams + og|DONE 2026-10-29 (repo side) — hierarchy, `<pre>` diagram branch, fences removed, edit-only type tag, og 500×667; browser confirmation owner-side|
|
||||||
|
Stage 4 — language URLs|NOT PLANNED without an owner decision (D4)|
|
||||||
|
Post-deploy re-audit|TODO (owner deploys and re-runs the audit checks; acceptance criteria above are directly measurable)|
|
||||||
|
|
||||||
|
## 9. Known limits
|
||||||
|
|
||||||
|
- Stage 1's real-404 routing depends on the generated route files: a build that skips `generate:routes` would 404 every SPA route. The `build` script chains them together; a missing step is a loud deploy failure, not a silent soft-404.
|
||||||
|
- The CSP `script-src` hash is coupled to the exact bytes of the theme-init script in `index.html`; the coupling is commented at the header.
|
||||||
|
- `<noscript>` text (D2b) is a crawler/no-JS affordance; real users still see the app paint after JS. Full prerender (D2c) is the only option that shows content pre-hydration and is scoped separately.
|
||||||
|
- EN fallback means the IoT-DWS diagram text stays English in both languages until VI section text is authored — a content task, not a code task (matches the existing fallback convention, AGENTS.md gotcha 5).
|
||||||
|
- The audit's §3 positives (caching, auth 401, UTM canonical, noopener) are already repo behaviour; nothing in this spec changes them.
|
||||||
@@ -0,0 +1,219 @@
|
|||||||
|
# Website Audit Report: cv.vugado.com
|
||||||
|
|
||||||
|
**Website:** https://cv.vugado.com/
|
||||||
|
**Audit date:** 29 October 2026
|
||||||
|
**Scope:** technical SEO, basic security, public-page functionality, and general recommendations.
|
||||||
|
|
||||||
|
## 1. Executive Summary
|
||||||
|
|
||||||
|
The website fulfils its primary purpose as a personal portfolio: presenting professional experience, showcasing projects, and providing contact details and a resume in two languages. The main user journeys tested are working.
|
||||||
|
|
||||||
|
The main area requiring improvement is technical SEO. Internal pages share the same metadata and point their canonical URLs to the homepage, nonexistent URLs are not handled correctly, and the main content becomes available only after JavaScript executes. These issues may prevent search engines from processing and indexing individual pages correctly.
|
||||||
|
|
||||||
|
Regarding security, HTTPS is configured, and the tested unauthenticated request to the editor API was rejected. However, several security-related HTTP headers are missing. These are security-hardening gaps, not evidence of a compromise or the ability to modify the website without permission.
|
||||||
|
|
||||||
|
**Recommended order of work:** correct metadata and canonical URLs, implement proper 404 responses, add security headers, and enable asset compression; then improve page generation, language versions, and content presentation.
|
||||||
|
|
||||||
|
## 2. Audit Scope
|
||||||
|
|
||||||
|
The audit covered nine public pages: Home, About, Experience, Projects, Contact, Philosophy, How it works, and two project detail pages.
|
||||||
|
|
||||||
|
The following were checked:
|
||||||
|
|
||||||
|
- HTTP responses, initial HTML, and content rendered after JavaScript execution;
|
||||||
|
- title, description, canonical URLs, Open Graph, H1–H3 headings, and structured data;
|
||||||
|
- robots.txt, sitemap.xml, and the response to one nonexistent URL;
|
||||||
|
- navigation to projects and contacts, language switching, and the resume selection dialog;
|
||||||
|
- availability of both PDF resume versions;
|
||||||
|
- size, compression, and caching of the main JS/CSS assets;
|
||||||
|
- HTTPS, the certificate, and security-related HTTP headers;
|
||||||
|
- public client-side code and one unauthenticated HEAD request to the editor API;
|
||||||
|
- homepage horizontal overflow through DOM measurements at viewport widths of 375 and 1440 pixels.
|
||||||
|
|
||||||
|
The audit was non-destructive: no website data was changed, no save operations were performed, and no password guessing or load testing was carried out.
|
||||||
|
|
||||||
|
## 3. What Is Working Correctly
|
||||||
|
|
||||||
|
| Area | Finding | Value to the website |
|
||||||
|
|---|---|---|
|
||||||
|
| Public pages | All nine pages checked are accessible and display content after JavaScript executes. | Visitors can browse the portfolio. |
|
||||||
|
| Main navigation | The tested links to the project list, a project detail page, and contacts work. | Navigation does not block the main user journeys tested. |
|
||||||
|
| Language switcher | Switches between English and Vietnamese content and updates the document language attribute. | Visitors can choose their preferred language. SEO for the language versions requires separate improvements. |
|
||||||
|
| Resume | The language selection dialog opens, and both PDF links return 200 with the application/pdf content type. | The files are available for download. PDF content and layout were not assessed separately. |
|
||||||
|
| HTTPS | Certificate validation succeeds; HTTP redirects to HTTPS with a 301 response. | The connection is encrypted. |
|
||||||
|
| Certificate | At the time of the audit, the certificate is valid until 5 January 2027. | There is no certificate expiry error; automatic renewal should be monitored. |
|
||||||
|
| Search crawler access | robots.txt allows crawling and references sitemap.xml. | The checked robots.txt does not block crawling of the website. |
|
||||||
|
| Sitemap | sitemap.xml contains nine HTTPS URLs, with no apparent structural errors. | Search engines are provided with a list of pages. |
|
||||||
|
| Basic SEO markup | The initial HTML includes title, description, Open Graph, Twitter Cards, and Person JSON-LD. | Basic metadata is available without JavaScript execution. Page-specific metadata still needs to be corrected. |
|
||||||
|
| Homepage UTM parameters | The canonical URL points to the clean homepage URL without campaign parameters. | This reduces the risk of duplicate homepage URLs caused by tracking tags. |
|
||||||
|
| External links | The checked links that open in a new tab use noopener noreferrer. | A basic safeguard for opening external websites is in place. |
|
||||||
|
| Caching | The main hashed JS/CSS files are cached for 30 days with immutable. | Repeat visits require fewer downloads. |
|
||||||
|
| Editor authentication | The tested API HEAD request without credentials returned 401 Unauthorized and a Basic Auth challenge. | Authentication is enforced for this request. This is not a complete assessment of all API operations. |
|
||||||
|
| Responsive structure | DOM checks at 375 and 1440 pixels found no horizontal overflow on the homepage. | The basic page width is correct under these conditions; visual testing on devices is still required. |
|
||||||
|
|
||||||
|
## 4. Required Improvements
|
||||||
|
|
||||||
|
### 4.1. High Priority: Page-Specific SEO
|
||||||
|
|
||||||
|
**Finding.** All nine pages return the same title and description, while canonical and og:url point to the homepage. This remains unchanged after JavaScript executes on the internal pages checked.
|
||||||
|
|
||||||
|
**Why it matters.** The website signals to search engines that the homepage is the preferred version of its internal pages. This conflicts with those pages having distinct content and may interfere with their separate indexing. Shared links also lack project-specific descriptions.
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
|
||||||
|
- Give each standalone indexable page a canonical URL pointing to its own clean address.
|
||||||
|
- Write a unique title and description that reflect the page content.
|
||||||
|
- Set page-specific og:title, og:description, and og:url values, plus a project image where appropriate.
|
||||||
|
- Include the correct metadata in the initial HTML, not only after JavaScript execution.
|
||||||
|
- Keep canonical URLs, internal links, and sitemap.xml URLs consistent.
|
||||||
|
|
||||||
|
**Acceptance criteria:** each page's initial HTML contains its own metadata and canonical URL; project pages no longer identify the homepage as their canonical version.
|
||||||
|
|
||||||
|
### 4.2. High Priority: Correct Error Page Handling
|
||||||
|
|
||||||
|
**Finding.** The nonexistent URL `/seo-audit-not-found-20261029` returns HTTP 200, an index, follow meta directive, and an empty main content area instead of an error page.
|
||||||
|
|
||||||
|
**Why it matters.** Visitors are not told what happened, and search engines may classify the response as a soft 404: an error page incorrectly served with a success status.
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
|
||||||
|
- Return a genuine HTTP 404 status for unknown URLs.
|
||||||
|
- Display a clear message with links to the homepage and projects.
|
||||||
|
- Do not use a homepage canonical URL as a substitute for the correct error status.
|
||||||
|
- After changing server routing, test direct navigation and refreshes on all existing pages.
|
||||||
|
|
||||||
|
**Acceptance criteria:** unknown URLs return 404, while existing pages remain directly accessible with a 200 response.
|
||||||
|
|
||||||
|
### 4.3. Priority Security Hardening: HTTP Security Headers
|
||||||
|
|
||||||
|
**Finding.** The checked HTML responses lack Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options, and explicit Referrer-Policy and Permissions-Policy headers.
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
|
||||||
|
| Setting | Purpose and implementation considerations |
|
||||||
|
|---|---|
|
||||||
|
| Content-Security-Policy | Restrict permitted sources of scripts, styles, and other resources. Test the policy in Report-Only mode first. Account for existing inline scripts using appropriate hashes or nonces. |
|
||||||
|
| CSP frame-ancestors | Prevent third-party embedding unless it is required. Where appropriate, supplement this with a consistent X-Frame-Options header. |
|
||||||
|
| Strict-Transport-Security | Instruct browsers to use HTTPS for subsequent connections. Introduce it after confirming reliable HTTPS operation; use includeSubDomains only when all affected subdomains are ready. |
|
||||||
|
| X-Content-Type-Options: nosniff | Prevent MIME sniffing that could override the declared Content-Type. |
|
||||||
|
| Referrer-Policy | Explicitly define how much Referer information is sent. Consider strict-origin-when-cross-origin for a typical portfolio. |
|
||||||
|
| Permissions-Policy | Restrict unnecessary browser capabilities, such as geolocation, camera, and microphone access, if the website does not use them. |
|
||||||
|
|
||||||
|
**Acceptance criteria:** the required policies appear on the relevant responses without breaking public pages or authorized editor workflows. Error responses are checked separately.
|
||||||
|
|
||||||
|
Missing headers alone do not establish the presence of XSS, a data leak, or a website takeover vulnerability. No specific exploitable impact was established through this review.
|
||||||
|
|
||||||
|
### 4.4. Medium Priority: Content Availability Without JavaScript
|
||||||
|
|
||||||
|
**Finding.** The initial HTML body contains an empty application container. Portfolio text, headings, and navigation are generated on the client.
|
||||||
|
|
||||||
|
**Why it matters.** Google can execute JavaScript, but processing depends on a separate rendering stage. Other crawlers may have more limited capabilities. Visitors may also lose access to the main content if application loading fails.
|
||||||
|
|
||||||
|
**Recommendation:** for a small portfolio, consider static generation or build-time prerendering. Server-side rendering is also an option, but it is not essential if content only changes during publication.
|
||||||
|
|
||||||
|
**Acceptance criteria:** the initial HTML contains the main text, page heading, working links, and metadata before JavaScript executes.
|
||||||
|
|
||||||
|
### 4.5. Medium Priority: SEO for Both Language Versions
|
||||||
|
|
||||||
|
**Finding.** Switching languages does not change the URL, and hreflang is absent. After switching to Vietnamese, the metadata and primary Open Graph locale remain English.
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
|
||||||
|
- If both language versions should appear in search results, provide separate, stable URLs for them.
|
||||||
|
- Localize titles, descriptions, and social sharing metadata.
|
||||||
|
- Add reciprocal hreflang links and the correct lang attribute.
|
||||||
|
- Use a self-referencing canonical URL for each language page.
|
||||||
|
- Make the language switcher lead to the equivalent page in the other language, rather than always to the homepage.
|
||||||
|
|
||||||
|
If the second language is only a convenience for visitors and separate search visibility is not a goal, this work can be assigned a lower priority. It does not block the more urgent canonical and 404 fixes.
|
||||||
|
|
||||||
|
### 4.6. Medium Priority: Compression and Performance
|
||||||
|
|
||||||
|
**Finding.** The two main JS files and the CSS file are delivered without gzip/Brotli, despite the client advertising compression support. Their combined size is 542,833 bytes, approximately 543 KB. Compression was observed for HTML.
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
|
||||||
|
- Enable gzip or Brotli for JavaScript and CSS.
|
||||||
|
- Preserve long-lived caching for assets with hashes in their filenames.
|
||||||
|
- Check that editor code and optional features do not unnecessarily increase the initial download.
|
||||||
|
- Measure mobile performance after the fixes, then optimize the actual bottlenecks.
|
||||||
|
|
||||||
|
**Acceptance criteria:** the server returns compressed JS/CSS when supported by the client's Accept-Encoding header; transfer size decreases without functional regressions.
|
||||||
|
|
||||||
|
The audit did not establish that the website is slow: reliable Lighthouse scores and field Core Web Vitals were not obtained. It identified a specific opportunity to reduce download size.
|
||||||
|
|
||||||
|
### 4.7. Planned Improvements: Headings, Content, and Link Previews
|
||||||
|
|
||||||
|
**Findings:**
|
||||||
|
|
||||||
|
- The About, Experience, Projects, Contact, Philosophy, and How it works pages have no H1 heading.
|
||||||
|
- Project detail pages use H3 headings after H1 without an intermediate H2 level.
|
||||||
|
- The IoT-DWS project page displays raw Markdown code fences and internal text/diagram labels.
|
||||||
|
- The Open Graph image declares dimensions of 1200×1600, but the actual file is 500×667.
|
||||||
|
|
||||||
|
**Recommendations:**
|
||||||
|
|
||||||
|
- Use H1 for each page's main heading and a logical heading hierarchy for subsections.
|
||||||
|
- Render diagrams and code blocks correctly, and remove internal labels from public-facing content.
|
||||||
|
- Prepare a separate wide image for link sharing; 1200×630 pixels is a practical option.
|
||||||
|
- Declare the actual image dimensions and test previews in the messaging platforms used, including Zalo.
|
||||||
|
|
||||||
|
These changes improve structure, accessibility, and presentation, but they do not guarantee higher search rankings.
|
||||||
|
|
||||||
|
## 5. General Website Recommendations
|
||||||
|
|
||||||
|
The following are recommendations and areas for additional review, not confirmed defects.
|
||||||
|
|
||||||
|
### Content and Credibility
|
||||||
|
|
||||||
|
- Clearly state the professional specialization, core capabilities, and preferred type of engagement in the first screen.
|
||||||
|
- Structure project case studies around the problem, individual role, constraints, solution, and outcome. Include measurable results only where they can be substantiated.
|
||||||
|
- Check that dates, job titles, and descriptions are consistent across the website and both PDF resume versions.
|
||||||
|
- Review the quality of English and Vietnamese copy. Retain established technical terms, but avoid mixing languages where it makes the text harder to understand.
|
||||||
|
- Do not publish confidential information from previous employers, internal addresses, access keys, or private project materials.
|
||||||
|
|
||||||
|
### Usability and Accessibility
|
||||||
|
|
||||||
|
- Run a complete visual check on phones and computers, covering menus, long headings, both languages, display themes, and the CV download dialog.
|
||||||
|
- Test keyboard navigation, visible focus, closing dialogs with Escape, and returning focus to the button that opened the dialog.
|
||||||
|
- Check text and control contrast across all available color themes.
|
||||||
|
- Review link labels, image alternative text, and tap-target usability on small screens.
|
||||||
|
- Respect the system's reduced-motion preference when using noticeable transitions or effects.
|
||||||
|
|
||||||
|
### Search Visibility and Measurement
|
||||||
|
|
||||||
|
- Verify the website in Google Search Console, submit the sitemap, and investigate reasons why pages are excluded from the index.
|
||||||
|
- After the fixes, use URL Inspection to check the homepage, project list, and individual project pages.
|
||||||
|
- Update sitemap lastmod values when page content changes meaningfully, rather than automatically when content has not changed.
|
||||||
|
- Monitor Core Web Vitals separately for mobile and desktop. Do not substitute a single laboratory measurement for real-user data.
|
||||||
|
- If analytics is needed, measure useful actions such as contact-link clicks, project views, and CV downloads. Define privacy and visitor-notice requirements before implementation.
|
||||||
|
|
||||||
|
### Operations and Editor Security
|
||||||
|
|
||||||
|
- Maintain automatic certificate renewal and alerts before expiry.
|
||||||
|
- Review protection for every editor API operation, rather than relying on interface visibility or one HEAD response.
|
||||||
|
- Check login-attempt limits and logging of failed authentication; password guessing was not performed during this audit.
|
||||||
|
- Assess CSRF protection for state-changing operations in light of the actual authentication mechanism.
|
||||||
|
- Store integration secrets only on the server and grant them the minimum required permissions.
|
||||||
|
- Keep dependencies up to date and maintain a tested recovery and deployment rollback procedure.
|
||||||
|
- Test security policy and server routing changes in a staging environment first.
|
||||||
|
|
||||||
|
## 6. Suggested Implementation Order
|
||||||
|
|
||||||
|
| Stage | Work | Verifiable outcome |
|
||||||
|
|---|---|---|
|
||||||
|
| 1. Fix core technical issues | Unique metadata, correct canonical URLs, and genuine HTTP 404 responses. | Each page has its own SEO metadata; unknown URLs no longer return a success response. |
|
||||||
|
| 2. Strengthen basic security and reduce downloads | Security headers, gzip/Brotli, and a review of API authentication and authorization configuration. | Policies work without breaking functionality; JS/CSS are compressed; access controls are reviewed within the agreed scope. |
|
||||||
|
| 3. Improve indexing and presentation | Static generation/prerendering, language-specific URLs if needed, H1 headings, project formatting, and Open Graph images. | Content is available in the initial HTML, language pages are distinguishable, and public content and previews are well presented. |
|
||||||
|
| 4. Repeat the audit | Search Console, mobile browser testing, accessibility, performance, and key user journeys. | Results are confirmed through measurements and regression testing after deployment. |
|
||||||
|
|
||||||
|
## 7. Limitations and Interpretation
|
||||||
|
|
||||||
|
- Findings describe the website as observed on 29 October 2026. A follow-up check is required after changes are deployed.
|
||||||
|
- The source repository, server configuration, logs, Search Console, and analytics were not available for review.
|
||||||
|
- Actual indexing, rankings, and search traffic were not verified.
|
||||||
|
- Screenshot-based visual testing could not be completed because the embedded browser's visible surface was unavailable. DOM checks do not replace visual testing on devices.
|
||||||
|
- A 401 response to one request does not establish that all API methods are protected. Write operations, authentication bypass, and password strength were not tested.
|
||||||
|
- The absence of confirmed vulnerabilities in this review is not a guarantee of complete website security.
|
||||||
|
|
||||||
|
**Conclusion:** the portfolio's core functionality works. The immediate priorities are to fix the confirmed technical SEO issues and strengthen basic security settings. Further improvements should be guided by follow-up testing rather than assumptions.
|
||||||
+2
-2
@@ -28,8 +28,8 @@
|
|||||||
<meta property="og:locale" content="en_US" />
|
<meta property="og:locale" content="en_US" />
|
||||||
<meta property="og:locale:alternate" content="vi_VN" />
|
<meta property="og:locale:alternate" content="vi_VN" />
|
||||||
<meta property="og:image" content="%SITE_URL%/profile-photo.webp" />
|
<meta property="og:image" content="%SITE_URL%/profile-photo.webp" />
|
||||||
<meta property="og:image:width" content="1200" />
|
<meta property="og:image:width" content="500" />
|
||||||
<meta property="og:image:height" content="1600" />
|
<meta property="og:image:height" content="667" />
|
||||||
<meta property="og:image:alt" content="Portrait of Nguyễn Đông" />
|
<meta property="og:image:alt" content="Portrait of Nguyễn Đông" />
|
||||||
|
|
||||||
<meta name="twitter:card" content="summary_large_image" />
|
<meta name="twitter:card" content="summary_large_image" />
|
||||||
|
|||||||
+56
-2
@@ -7,16 +7,63 @@ server {
|
|||||||
root /usr/share/nginx/html;
|
root /usr/share/nginx/html;
|
||||||
index index.html;
|
index index.html;
|
||||||
|
|
||||||
# React/Vue/Vite SPA routing
|
# Compression (spec-v8 §3): the image ships gzip enabled, but gzip_types
|
||||||
|
# defaults to text/html only — the audit measured the hashed JS/CSS
|
||||||
|
# uncompressed. Long-lived immutable caching for hashed assets stays as
|
||||||
|
# it was; only the transfer encoding changes.
|
||||||
|
gzip on;
|
||||||
|
gzip_types text/css application/javascript application/json image/svg+xml text/xml application/xml;
|
||||||
|
gzip_min_length 1024;
|
||||||
|
gzip_vary on;
|
||||||
|
gzip_comp_level 6;
|
||||||
|
|
||||||
|
# Security headers (spec-v8 §3). nginx gotcha: add_header is NOT inherited
|
||||||
|
# into a block that declares its own add_header — the index.html and asset
|
||||||
|
# blocks set Cache-Control, so those two repeat the set verbatim.
|
||||||
|
# CSP is deliberately the Report-Only header (spec-v8 D5): watch the
|
||||||
|
# browser console on a real page, then drop the "-Report-Only" suffix to
|
||||||
|
# enforce. style-src needs 'unsafe-inline' because motion writes inline
|
||||||
|
# style attributes; there are no third-party script or image origins.
|
||||||
|
# script-src carries the SHA-256 of the theme-init inline script in
|
||||||
|
# index.html — the hash is verified against the built bytes by
|
||||||
|
# scripts/generate-route-pages.ts: editing that script (or vite adding
|
||||||
|
# one) fails the build and prints the new hash to paste here.
|
||||||
|
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' 'sha256-FlEXeas8Ye/eeYFpd9EIm0va9LsSvF9SetK7HmeJMUQ='; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'" always;
|
||||||
|
add_header Strict-Transport-Security "max-age=31536000" always;
|
||||||
|
add_header X-Content-Type-Options "nosniff" always;
|
||||||
|
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||||||
|
add_header Permissions-Policy "geolocation=(), camera=(), microphone=()" always;
|
||||||
|
add_header X-Frame-Options "DENY" always;
|
||||||
|
|
||||||
|
# SPA routing with genuine 404s (spec-v8 §2.1): known routes are real
|
||||||
|
# files — `pnpm generate:routes` writes dist/<route>/index.html for every
|
||||||
|
# manifest route and project page. The first try_files parameter is the
|
||||||
|
# composite file path, not the bare directory: '/about' is served from
|
||||||
|
# dist/about/index.html with a 200 at the exact URL — no trailing-slash
|
||||||
|
# 301, so canonical, internal links and sitemap URLs stay identical
|
||||||
|
# strings (the audit's consistency point). Unknown URLs fall to =404,
|
||||||
|
# answered with the generated 404 page at a real 404 status.
|
||||||
|
# The coupling is guarded in generate-sitemap.ts: a sitemap URL without
|
||||||
|
# its generated file fails the build before deploy.
|
||||||
location / {
|
location / {
|
||||||
try_files $uri $uri/ /index.html;
|
try_files $uri/index.html $uri =404;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
error_page 404 /404.html;
|
||||||
|
|
||||||
# Do not aggressively cache index.html.
|
# Do not aggressively cache index.html.
|
||||||
# It references the latest hashed JS/CSS files.
|
# It references the latest hashed JS/CSS files.
|
||||||
location = /index.html {
|
location = /index.html {
|
||||||
try_files $uri =404;
|
try_files $uri =404;
|
||||||
|
|
||||||
|
# add_header here ends the inheritance of the server-level set —
|
||||||
|
# the security headers are repeated, not replaced (spec-v8 §3).
|
||||||
|
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' 'sha256-FlEXeas8Ye/eeYFpd9EIm0va9LsSvF9SetK7HmeJMUQ='; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'" always;
|
||||||
|
add_header Strict-Transport-Security "max-age=31536000" always;
|
||||||
|
add_header X-Content-Type-Options "nosniff" always;
|
||||||
|
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||||||
|
add_header Permissions-Policy "geolocation=(), camera=(), microphone=()" always;
|
||||||
|
add_header X-Frame-Options "DENY" always;
|
||||||
add_header Cache-Control "no-cache, must-revalidate";
|
add_header Cache-Control "no-cache, must-revalidate";
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -26,6 +73,13 @@ server {
|
|||||||
try_files $uri =404;
|
try_files $uri =404;
|
||||||
|
|
||||||
expires 30d;
|
expires 30d;
|
||||||
|
# Same repetition rule as the index.html block above.
|
||||||
|
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self' 'sha256-FlEXeas8Ye/eeYFpd9EIm0va9LsSvF9SetK7HmeJMUQ='; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'" always;
|
||||||
|
add_header Strict-Transport-Security "max-age=31536000" always;
|
||||||
|
add_header X-Content-Type-Options "nosniff" always;
|
||||||
|
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
||||||
|
add_header Permissions-Policy "geolocation=(), camera=(), microphone=()" always;
|
||||||
|
add_header X-Frame-Options "DENY" always;
|
||||||
add_header Cache-Control "public, max-age=2592000, immutable";
|
add_header Cache-Control "public, max-age=2592000, immutable";
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
+2
-1
@@ -6,9 +6,10 @@
|
|||||||
"scripts": {
|
"scripts": {
|
||||||
"dev": "vite",
|
"dev": "vite",
|
||||||
"predev": "pnpm generate:ids",
|
"predev": "pnpm generate:ids",
|
||||||
"build": "tsc -b && vite build && pnpm tsx scripts/generate-sitemap.ts",
|
"build": "tsc -b && vite build && pnpm tsx scripts/generate-route-pages.ts && pnpm tsx scripts/generate-sitemap.ts",
|
||||||
"prebuild": "pnpm generate:ids",
|
"prebuild": "pnpm generate:ids",
|
||||||
"generate:ids": "pnpm tsx scripts/generate-content-types.ts",
|
"generate:ids": "pnpm tsx scripts/generate-content-types.ts",
|
||||||
|
"generate:routes": "pnpm tsx scripts/generate-route-pages.ts",
|
||||||
"prepare": "pnpm generate:ids",
|
"prepare": "pnpm generate:ids",
|
||||||
"build:resume": "pnpm tsx scripts/generate-resume.ts",
|
"build:resume": "pnpm tsx scripts/generate-resume.ts",
|
||||||
"build:resume-all": "pnpm tsx scripts/generate-resume.ts --lang=all",
|
"build:resume-all": "pnpm tsx scripts/generate-resume.ts --lang=all",
|
||||||
|
|||||||
@@ -0,0 +1,371 @@
|
|||||||
|
// Route-page generator (spec-v8 §2): build-time per-route HTML. Runs after
|
||||||
|
// `vite build`, before the sitemap step: reads dist/index.html as the head
|
||||||
|
// template and writes a real file per route so nginx can answer known routes
|
||||||
|
// with 200 and unknown ones with a genuine 404 (spec-v8 §2.1).
|
||||||
|
//
|
||||||
|
// What each generated page carries:
|
||||||
|
// - a head specific to the route: title, description, canonical, og:url,
|
||||||
|
// og:title/og:description and the twitter pair. Static pages read the ui
|
||||||
|
// `meta` group (the six static page manifests claim it); project detail
|
||||||
|
// pages derive the same fields from their content records. The homepage
|
||||||
|
// keeps its existing head — it is already self-canonical and unique — and
|
||||||
|
// only gains the noscript body.
|
||||||
|
// - a <noscript> body generated from the page manifest claims (spec-v8 D2b):
|
||||||
|
// the page heading, the nav links, and every text leaf the manifest claims
|
||||||
|
// for the route — the same claim-matching the validator's orphan rule and
|
||||||
|
// EditBar use, never a second description of the page in code. Project
|
||||||
|
// detail pages render their fixed record shape (title, summary, metrics,
|
||||||
|
// role, technologies, sections — diagrams as <pre>) because their layout is
|
||||||
|
// a structure fact, not a claim.
|
||||||
|
// - dist/404.html: the static error page nginx serves with a real 404
|
||||||
|
// (ui/common notFound keys, EN + VI block), linked to the build's hashed
|
||||||
|
// CSS so it carries the site's theme variables.
|
||||||
|
//
|
||||||
|
// This is not prerender: the #root stays empty for JavaScript users — the
|
||||||
|
// SPA boots from any shell exactly as before. No hydration, no SSR.
|
||||||
|
import { createHash } from 'node:crypto';
|
||||||
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
||||||
|
import { dirname, join, resolve } from 'node:path';
|
||||||
|
import { siteName, siteUrl } from '../src/data/site.js';
|
||||||
|
import { manifestClaimsPath, pageManifests } from '../src/data/pages.js';
|
||||||
|
import { navPaths } from '../src/data/navigation.js';
|
||||||
|
import { projects } from '../src/data/projects.js';
|
||||||
|
import { CONTENT, UI } from '../src/i18n/index.js';
|
||||||
|
import profileViJson from '../src/i18n/locales/vi/content/profile.json';
|
||||||
|
import skillsViJson from '../src/i18n/locales/vi/content/skills.json';
|
||||||
|
import experienceViJson from '../src/i18n/locales/vi/content/experience.json';
|
||||||
|
import projectsViJson from '../src/i18n/locales/vi/content/projects.json';
|
||||||
|
import profileEnJson from '../src/i18n/locales/en/content/profile.json';
|
||||||
|
import skillsEnJson from '../src/i18n/locales/en/content/skills.json';
|
||||||
|
import experienceEnJson from '../src/i18n/locales/en/content/experience.json';
|
||||||
|
import projectsEnJson from '../src/i18n/locales/en/content/projects.json';
|
||||||
|
import type { ContentEntityId } from '../src/types/index.js';
|
||||||
|
|
||||||
|
const ROOT = resolve(import.meta.dirname, '..');
|
||||||
|
const distDir = join(ROOT, 'dist');
|
||||||
|
|
||||||
|
// Same guard as generate-sitemap.ts: the template head must carry the same
|
||||||
|
// SITE_URL this script derives its canonicals from.
|
||||||
|
const template = (() => {
|
||||||
|
const file = join(distDir, 'index.html');
|
||||||
|
if (!existsSync(file)) {
|
||||||
|
console.error('dist/index.html not found — run `vite build` before `pnpm generate:routes`.');
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
const html = readFileSync(file, 'utf-8');
|
||||||
|
if (!html.includes(siteUrl)) {
|
||||||
|
console.error(
|
||||||
|
`Canonical origin mismatch: dist/index.html does not contain "${siteUrl}". ` +
|
||||||
|
'The site-identity plugin injects it from SITE_URL — check the build environment.',
|
||||||
|
);
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
return html;
|
||||||
|
})();
|
||||||
|
|
||||||
|
// --- CSP coupling guard (spec-v8 §3) ------------------------------------------
|
||||||
|
// nginx.conf's CSP script-src lists the SHA-256 of every inline script the
|
||||||
|
// built page carries. Editing the theme-init script — or vite adding one —
|
||||||
|
// would otherwise show up as a silently refused script on the live site;
|
||||||
|
// here it fails the build and prints the hash to paste into nginx.conf.
|
||||||
|
const nginxConf = readFileSync(join(ROOT, 'nginx.conf'), 'utf-8');
|
||||||
|
for (const inline of template.matchAll(/<script>([\s\S]*?)<\/script>/g)) {
|
||||||
|
const hash = `sha256-${createHash('sha256').update(inline[1], 'utf-8').digest('base64')}`;
|
||||||
|
if (!nginxConf.includes(hash)) {
|
||||||
|
console.error(
|
||||||
|
`CSP script-src hash mismatch: the built page carries an inline script whose hash is ${hash}, ` +
|
||||||
|
'not listed in nginx.conf. Update the CSP header (see its comment) or revert the script.',
|
||||||
|
);
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- text documents, walked for the noscript bodies ---------------------------
|
||||||
|
// vi is complete by validator rule 1; en is checked leaf-by-leaf, mirroring
|
||||||
|
// i18n/index.ts deepMerge: missing en fields fall back to vi, arrays are
|
||||||
|
// atomic, never merged item by item.
|
||||||
|
const TEXT_DOCS: Record<
|
||||||
|
'profile' | 'skills' | 'experience' | 'projects',
|
||||||
|
{ vi: unknown; en: unknown }
|
||||||
|
> = {
|
||||||
|
profile: { vi: profileViJson, en: profileEnJson },
|
||||||
|
skills: { vi: skillsViJson, en: skillsEnJson },
|
||||||
|
experience: { vi: experienceViJson, en: experienceEnJson },
|
||||||
|
projects: { vi: projectsViJson, en: projectsEnJson },
|
||||||
|
};
|
||||||
|
|
||||||
|
const ENTITY_TO_NS: Record<ContentEntityId, keyof typeof TEXT_DOCS> = {
|
||||||
|
profile: 'profile',
|
||||||
|
skillGroups: 'skills',
|
||||||
|
experiences: 'experience',
|
||||||
|
projects: 'projects',
|
||||||
|
};
|
||||||
|
|
||||||
|
type Leaf = { path: string; value: string | string[] };
|
||||||
|
|
||||||
|
function resolvedLeaves(vi: unknown, en: unknown, prefix: string): Leaf[] {
|
||||||
|
if (typeof vi === 'string') {
|
||||||
|
return [{ path: prefix, value: typeof en === 'string' ? en : vi }];
|
||||||
|
}
|
||||||
|
if (Array.isArray(vi)) {
|
||||||
|
if (vi.every((item) => typeof item === 'string')) {
|
||||||
|
const atomic = Array.isArray(en) && en.every((item) => typeof item === 'string');
|
||||||
|
return [{ path: prefix, value: (atomic ? en : vi) as string[] }];
|
||||||
|
}
|
||||||
|
return vi.flatMap((item, i) =>
|
||||||
|
resolvedLeaves(item, Array.isArray(en) ? en[i] : undefined, `${prefix}[${i}]`),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if (vi && typeof vi === 'object') {
|
||||||
|
return Object.entries(vi).flatMap(([key, value]) =>
|
||||||
|
resolvedLeaves(
|
||||||
|
value,
|
||||||
|
en && typeof en === 'object' && !Array.isArray(en)
|
||||||
|
? (en as Record<string, unknown>)[key]
|
||||||
|
: undefined,
|
||||||
|
prefix ? `${prefix}.${key}` : key,
|
||||||
|
),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
// The claimed text of one manifest: document leaves filtered through the same
|
||||||
|
// claim matcher the orphan-field rule uses. Structure fields (ids, handles,
|
||||||
|
// technologies, categories) are not text documents and never appear.
|
||||||
|
function claimedText(manifestId: string, restrictToId?: string): Leaf[] {
|
||||||
|
const manifest = pageManifests.find((m) => m.id === manifestId);
|
||||||
|
if (!manifest) throw new Error(`no manifest for ${manifestId}`);
|
||||||
|
const out: Leaf[] = [];
|
||||||
|
for (const claim of manifest.content) {
|
||||||
|
const ns = ENTITY_TO_NS[claim.entity];
|
||||||
|
if (!ns) continue;
|
||||||
|
const docs = TEXT_DOCS[ns];
|
||||||
|
for (const leaf of resolvedLeaves(docs.vi, docs.en, '')) {
|
||||||
|
if (restrictToId && !leaf.path.startsWith(`${restrictToId}.`)) continue;
|
||||||
|
if (manifestClaimsPath(manifest, claim.entity, leaf.path)) out.push(leaf);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- html helpers -------------------------------------------------------------
|
||||||
|
const esc = (value: string) =>
|
||||||
|
value
|
||||||
|
.replace(/&/g, '&')
|
||||||
|
.replace(/</g, '<')
|
||||||
|
.replace(/>/g, '>')
|
||||||
|
.replace(/"/g, '"');
|
||||||
|
|
||||||
|
function leafHtml(leaf: Leaf): string {
|
||||||
|
if (Array.isArray(leaf.value)) {
|
||||||
|
const items = leaf.value.filter((item) => item.trim() !== '');
|
||||||
|
if (items.length === 0) return '';
|
||||||
|
return `<ul>${items.map((item) => `<li>${esc(item)}</li>`).join('')}</ul>`;
|
||||||
|
}
|
||||||
|
if (leaf.value.trim() === '') return '';
|
||||||
|
return `<p>${esc(leaf.value)}</p>`;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Nav links are the same paths the bar renders, labelled from the nav group
|
||||||
|
// (path '/' maps to the 'home' label key).
|
||||||
|
function navHtml(): string {
|
||||||
|
const labels = UI.en.nav as Record<string, string>;
|
||||||
|
const links = navPaths.map((path) => {
|
||||||
|
const key = path === '/' ? 'home' : path.slice(1);
|
||||||
|
return `<a href="${path}">${esc(labels[key] ?? path)}</a>`;
|
||||||
|
});
|
||||||
|
return `<nav>${links.join('')}</nav>`;
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- head rewriting ------------------------------------------------------------
|
||||||
|
// The built head keeps index.html's formatting; each replacement targets one
|
||||||
|
// tag by its identifying attribute and rewrites the whole tag.
|
||||||
|
function replaceTag(html: string, pattern: RegExp, replacement: string): string {
|
||||||
|
if (!pattern.test(html)) throw new Error(`head template missing: ${pattern}`);
|
||||||
|
return html.replace(pattern, replacement);
|
||||||
|
}
|
||||||
|
|
||||||
|
function headFor(html: string, meta: { title: string; description: string; url: string }): string {
|
||||||
|
let out = html;
|
||||||
|
// SITE_NAME itself contains an em dash ("Nguyễn Đông — Senior Software
|
||||||
|
// Engineer"), so the page/site separator is the middot — a second em dash
|
||||||
|
// would read as a broken title.
|
||||||
|
const pageTitle = `${meta.title} · ${siteName}`;
|
||||||
|
out = replaceTag(out, /<title>[\s\S]*?<\/title>/, `<title>${esc(pageTitle)}</title>`);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<meta\s+name="description"\s+content="[^"]*"\s*\/>/,
|
||||||
|
`<meta name="description" content="${esc(meta.description)}" />`,
|
||||||
|
);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<link\s+rel="canonical"\s+href="[^"]*"\s*\/>/,
|
||||||
|
`<link rel="canonical" href="${esc(meta.url)}" />`,
|
||||||
|
);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<meta\s+property="og:title"\s+content="[^"]*"\s*\/>/,
|
||||||
|
`<meta property="og:title" content="${esc(pageTitle)}" />`,
|
||||||
|
);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<meta\s+property="og:description"\s+content="[^"]*"\s*\/>/,
|
||||||
|
`<meta property="og:description" content="${esc(meta.description)}" />`,
|
||||||
|
);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<meta\s+property="og:url"\s+content="[^"]*"\s*\/>/,
|
||||||
|
`<meta property="og:url" content="${esc(meta.url)}" />`,
|
||||||
|
);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<meta\s+name="twitter:title"\s+content="[^"]*"\s*\/>/,
|
||||||
|
`<meta name="twitter:title" content="${esc(pageTitle)}" />`,
|
||||||
|
);
|
||||||
|
out = replaceTag(
|
||||||
|
out,
|
||||||
|
/<meta\s+name="twitter:description"\s+content="[^"]*"\s*\/>/,
|
||||||
|
`<meta name="twitter:description" content="${esc(meta.description)}" />`,
|
||||||
|
);
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
|
||||||
|
function withNoscript(html: string, body: string): string {
|
||||||
|
const marker = '<div id="root"></div>';
|
||||||
|
if (!html.includes(marker)) throw new Error('head template missing #root');
|
||||||
|
return html.replace(marker, `<noscript>${body}</noscript>${marker}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
function routeDir(route: string): string {
|
||||||
|
// '/about' → dist/about/index.html; '/projects/<id>' → dist/projects/<id>/index.html.
|
||||||
|
return join(distDir, route.slice(1), 'index.html');
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- static pages --------------------------------------------------------------
|
||||||
|
const META_IDS = ['about', 'experience', 'projects', 'contact', 'philosophy', 'how-it-works'] as const;
|
||||||
|
|
||||||
|
function staticPage(id: (typeof META_IDS)[number]): void {
|
||||||
|
const manifest = pageManifests.find((m) => m.id === id);
|
||||||
|
if (!manifest || !manifest.route) throw new Error(`manifest ${id} has no route`);
|
||||||
|
const meta = (UI.en.meta as Record<string, { title: string; description: string }>)[id];
|
||||||
|
let html = headFor(template, {
|
||||||
|
title: meta.title,
|
||||||
|
description: meta.description,
|
||||||
|
url: `${siteUrl}${manifest.route}`,
|
||||||
|
});
|
||||||
|
const content = claimedText(id)
|
||||||
|
.map(leafHtml)
|
||||||
|
.join('');
|
||||||
|
const body =
|
||||||
|
`${navHtml()}<h1>${esc(meta.title)}</h1><p>${esc(meta.description)}</p>${content}`;
|
||||||
|
html = withNoscript(html, body);
|
||||||
|
const file = routeDir(manifest.route);
|
||||||
|
mkdirSync(dirname(file), { recursive: true });
|
||||||
|
writeFileSync(file, html);
|
||||||
|
console.log(` ${manifest.route} → ${file.slice(ROOT.length + 1)}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- homepage -------------------------------------------------------------------
|
||||||
|
// Head unchanged (already correct); only the noscript body is added, h1 = the
|
||||||
|
// person name the hero renders.
|
||||||
|
function homeNoscript(): void {
|
||||||
|
const profile = CONTENT.en.profile;
|
||||||
|
const content = claimedText('home')
|
||||||
|
.filter((leaf) => leaf.path !== 'name')
|
||||||
|
.map(leafHtml)
|
||||||
|
.join('');
|
||||||
|
const body =
|
||||||
|
`${navHtml()}<h1>${esc(profile.name)}</h1><p>${esc(profile.title)}</p>${content}`;
|
||||||
|
writeFileSync(join(distDir, 'index.html'), withNoscript(template, body));
|
||||||
|
console.log(' / → dist/index.html (noscript body added, head untouched)');
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- project detail pages --------------------------------------------------------
|
||||||
|
// Fixed record shape — the same fields the page renders, in reading order.
|
||||||
|
function projectPage(id: string): void {
|
||||||
|
const project = projects.find((p) => p.id === id);
|
||||||
|
if (!project) throw new Error(`no project ${id}`);
|
||||||
|
const text = CONTENT.en.projects.find((p) => p.id === id);
|
||||||
|
if (!text) throw new Error(`no joined project record ${id}`);
|
||||||
|
let html = headFor(template, {
|
||||||
|
title: text.title,
|
||||||
|
description: text.summary,
|
||||||
|
url: `${siteUrl}/projects/${id}`,
|
||||||
|
});
|
||||||
|
const sections = text.sections
|
||||||
|
.map((section) => {
|
||||||
|
const block =
|
||||||
|
section.type === 'diagram' || section.type === 'code'
|
||||||
|
? `<pre>${esc(section.content)}</pre>`
|
||||||
|
: `<p>${esc(section.content)}</p>`;
|
||||||
|
return `<h2>${esc(section.title)}</h2>${block}`;
|
||||||
|
})
|
||||||
|
.join('');
|
||||||
|
const body =
|
||||||
|
`${navHtml()}<h1>${esc(text.title)}</h1><p>${esc(text.summary)}</p>` +
|
||||||
|
(text.metrics?.length ? `<ul>${text.metrics.map((m) => `<li>${esc(m)}</li>`).join('')}</ul>` : '') +
|
||||||
|
(text.role ? `<p>${esc(text.role)}</p>` : '') +
|
||||||
|
(project.technologies.length
|
||||||
|
? `<ul>${project.technologies.map((t) => `<li>${esc(t)}</li>`).join('')}</ul>`
|
||||||
|
: '') +
|
||||||
|
sections;
|
||||||
|
html = withNoscript(html, body);
|
||||||
|
const file = routeDir(`/projects/${id}`);
|
||||||
|
mkdirSync(dirname(file), { recursive: true });
|
||||||
|
writeFileSync(file, html);
|
||||||
|
console.log(` /projects/${id} → ${file.slice(ROOT.length + 1)}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- 404 page --------------------------------------------------------------------
|
||||||
|
// Served by nginx with a real 404 (spec-v8 §2.1). No canonical on purpose —
|
||||||
|
// the audit's point: an error page must not claim the homepage's URL. EN and
|
||||||
|
// VI text from the common group; the theme comes from the linked hashed CSS
|
||||||
|
// (its :root block + the prefers-color-scheme bridge work without JS).
|
||||||
|
function notFoundPage(): void {
|
||||||
|
const en = UI.en.common as Record<string, string>;
|
||||||
|
const vi = UI.vi.common as Record<string, string>;
|
||||||
|
const styleMatch = template.match(/<link[^>]+rel="stylesheet"[^>]*href="([^"]+)"/);
|
||||||
|
const cssLink = styleMatch
|
||||||
|
? `<link rel="stylesheet" href="${styleMatch[1]}" />`
|
||||||
|
: '';
|
||||||
|
const html = `<!doctype html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
|
<title>${esc(en.notFoundTitle)} — ${esc(siteName)}</title>
|
||||||
|
<meta name="robots" content="noindex" />
|
||||||
|
${cssLink}
|
||||||
|
<style>
|
||||||
|
.not-found { max-width: 680px; margin: 96px auto; padding: 0 24px; }
|
||||||
|
.not-found p { font-size: 18px; line-height: 1.65; color: var(--text-secondary); }
|
||||||
|
.not-found a { color: var(--accent); }
|
||||||
|
.not-found .vi { margin-top: 32px; }
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<main class="not-found">
|
||||||
|
<h1>${esc(en.notFoundTitle)}</h1>
|
||||||
|
<p>${esc(en.notFoundBody)}</p>
|
||||||
|
<p><a href="/">${esc(en.notFoundHome)}</a> · <a href="/projects">${esc(en.notFoundProjects)}</a></p>
|
||||||
|
<div class="vi" lang="vi">
|
||||||
|
<h2>${esc(vi.notFoundTitle)}</h2>
|
||||||
|
<p>${esc(vi.notFoundBody)}</p>
|
||||||
|
<p><a href="/">${esc(vi.notFoundHome)}</a> · <a href="/projects">${esc(vi.notFoundProjects)}</a></p>
|
||||||
|
</div>
|
||||||
|
</main>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
`;
|
||||||
|
writeFileSync(join(distDir, '404.html'), html);
|
||||||
|
console.log(' 404 → dist/404.html');
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- run --------------------------------------------------------------------------
|
||||||
|
console.log('route pages (spec-v8 §2):');
|
||||||
|
homeNoscript();
|
||||||
|
for (const id of META_IDS) staticPage(id);
|
||||||
|
for (const project of projects) projectPage(project.id);
|
||||||
|
notFoundPage();
|
||||||
|
console.log('done.');
|
||||||
+133
-9
@@ -1,14 +1,18 @@
|
|||||||
|
import { execFileSync } from 'node:child_process';
|
||||||
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
||||||
import { join, resolve } from 'node:path';
|
import { join, resolve } from 'node:path';
|
||||||
import { siteUrl } from '../src/data/site.js';
|
import { siteUrl } from '../src/data/site.js';
|
||||||
import { navPaths } from '../src/data/navigation.js';
|
import { navPaths } from '../src/data/navigation.js';
|
||||||
import { projects } from '../src/data/projects.js';
|
import { projects } from '../src/data/projects.js';
|
||||||
|
import { pageManifests } from '../src/data/pages.js';
|
||||||
|
import type { ContentEntityId } from '../src/types/index.js';
|
||||||
|
|
||||||
const ROOT = resolve(import.meta.dirname, '..');
|
const ROOT = resolve(import.meta.dirname, '..');
|
||||||
const distDir = join(ROOT, 'dist');
|
const distDir = join(ROOT, 'dist');
|
||||||
|
|
||||||
// Run after `vite build`: the sitemap is a build artifact, and the guard below can
|
// Run after `vite build` and `pnpm generate:routes`: the sitemap is a build
|
||||||
// only compare against a head that has already been produced.
|
// artifact, and the guards below can only compare against artifacts that have
|
||||||
|
// already been produced.
|
||||||
if (!existsSync(distDir)) {
|
if (!existsSync(distDir)) {
|
||||||
console.error(`dist/ not found — run \`pnpm build\` before \`pnpm sitemap\`.`);
|
console.error(`dist/ not found — run \`pnpm build\` before \`pnpm sitemap\`.`);
|
||||||
process.exit(1);
|
process.exit(1);
|
||||||
@@ -22,22 +26,142 @@ const indexHtml = readFileSync(join(distDir, 'index.html'), 'utf-8');
|
|||||||
if (!indexHtml.includes(siteUrl)) {
|
if (!indexHtml.includes(siteUrl)) {
|
||||||
console.error(
|
console.error(
|
||||||
`Canonical origin mismatch: dist/index.html does not contain "${siteUrl}". ` +
|
`Canonical origin mismatch: dist/index.html does not contain "${siteUrl}". ` +
|
||||||
`The site-identity plugin injects it from SITE_URL — check the build environment.`,
|
'The site-identity plugin injects it from SITE_URL — check the build environment.',
|
||||||
);
|
);
|
||||||
process.exit(1);
|
process.exit(1);
|
||||||
}
|
}
|
||||||
|
|
||||||
const lastmod = new Date().toISOString().slice(0, 10);
|
// The coupling guard (spec-v8 §9): every sitemap URL must have the real file
|
||||||
|
// the route generator wrote for it — nginx answers known routes from those
|
||||||
|
// files, so a skipped `generate:routes` step is a loud build failure here,
|
||||||
|
// never a deploy that 404s every SPA route.
|
||||||
|
const routeFiles = new Map<string, string>([[navPaths[0], 'index.html']]);
|
||||||
|
for (const project of projects) routeFiles.set(`/projects/${project.id}`, `projects/${project.id}/index.html`);
|
||||||
|
for (const manifest of pageManifests) {
|
||||||
|
// '/projects/:id' is a route template, not a file — its concrete URLs are
|
||||||
|
// enumerated from the project data above.
|
||||||
|
if (manifest.route && manifest.route !== '/' && !manifest.route.includes(':'))
|
||||||
|
routeFiles.set(manifest.route, `${manifest.route.slice(1)}/index.html`);
|
||||||
|
}
|
||||||
|
for (const [route, file] of routeFiles) {
|
||||||
|
if (!existsSync(join(distDir, file))) {
|
||||||
|
console.error(
|
||||||
|
`Route file missing: ${route} → dist/${file}. Run \`pnpm generate:routes\` after \`vite build\` ` +
|
||||||
|
'(the build script chains them) — a sitemap URL without its file deploys as a 404.',
|
||||||
|
);
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
// navPaths is the six bar routes; the seventh route (/projects/:id) is enumerated
|
// --- lastmod from the documents that back each URL (spec-v8 §2.1) ----------
|
||||||
// from the project data, so a new project lands in the sitemap automatically.
|
// The audit's point (§5): lastmod means "this page's content changed", not
|
||||||
|
// "the build ran". Each URL's date is the newest commit touching the files
|
||||||
|
// that page renders — the manifest itself, the structure + text documents of
|
||||||
|
// every entity it claims, and the locale files of every UI group it owns.
|
||||||
|
const ENTITY_FILES: Record<ContentEntityId, string[]> = {
|
||||||
|
profile: [
|
||||||
|
'src/data/profile.json',
|
||||||
|
'src/i18n/locales/vi/content/profile.json',
|
||||||
|
'src/i18n/locales/en/content/profile.json',
|
||||||
|
],
|
||||||
|
skillGroups: [
|
||||||
|
'src/data/skills.json',
|
||||||
|
'src/i18n/locales/vi/content/skills.json',
|
||||||
|
'src/i18n/locales/en/content/skills.json',
|
||||||
|
],
|
||||||
|
experiences: [
|
||||||
|
'src/data/experience.json',
|
||||||
|
'src/i18n/locales/vi/content/experience.json',
|
||||||
|
'src/i18n/locales/en/content/experience.json',
|
||||||
|
],
|
||||||
|
projects: [
|
||||||
|
'src/data/projects.json',
|
||||||
|
'src/i18n/locales/vi/content/projects.json',
|
||||||
|
'src/i18n/locales/en/content/projects.json',
|
||||||
|
],
|
||||||
|
};
|
||||||
|
|
||||||
|
// UI group key → locale file stem (the names i18n/index.ts imports).
|
||||||
|
const UI_GROUP_FILES: Record<string, string> = {
|
||||||
|
nav: 'navigation',
|
||||||
|
social: 'social',
|
||||||
|
footer: 'footer',
|
||||||
|
hero: 'hero',
|
||||||
|
about: 'about',
|
||||||
|
expertise: 'expertise',
|
||||||
|
experience: 'experience',
|
||||||
|
projects: 'projects',
|
||||||
|
contact: 'contact',
|
||||||
|
projectDetail: 'project-detail',
|
||||||
|
philosophy: 'philosophy',
|
||||||
|
howItWorks: 'how-it-works',
|
||||||
|
common: 'common',
|
||||||
|
resume: 'resume',
|
||||||
|
edit: 'edit',
|
||||||
|
meta: 'meta',
|
||||||
|
};
|
||||||
|
|
||||||
|
const PROJECT_DETAIL_FILES = [
|
||||||
|
'src/data/projects.json',
|
||||||
|
'src/i18n/locales/vi/content/projects.json',
|
||||||
|
'src/i18n/locales/en/content/projects.json',
|
||||||
|
'src/i18n/locales/vi/ui/projects.json',
|
||||||
|
'src/i18n/locales/en/ui/projects.json',
|
||||||
|
];
|
||||||
|
|
||||||
|
const buildDate = new Date().toISOString().slice(0, 10);
|
||||||
|
|
||||||
|
function gitDate(files: string[]): string {
|
||||||
|
try {
|
||||||
|
const out = execFileSync(
|
||||||
|
'git',
|
||||||
|
['log', '-1', '--date=short', '--format=%ad', '--', ...files],
|
||||||
|
{ cwd: ROOT, encoding: 'utf-8' },
|
||||||
|
).trim();
|
||||||
|
return out || buildDate;
|
||||||
|
} catch {
|
||||||
|
// No git available (or this tree is not a checkout) — fall back to the
|
||||||
|
// build date rather than failing the pipeline over a metadata nicety.
|
||||||
|
return buildDate;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function manifestFiles(manifestId: string): string[] | null {
|
||||||
|
const manifest = pageManifests.find((m) => m.id === manifestId && m.route);
|
||||||
|
if (!manifest) return null;
|
||||||
|
const files = [`src/data/pages/${manifest.id}.json`];
|
||||||
|
for (const claim of manifest.content) files.push(...ENTITY_FILES[claim.entity]);
|
||||||
|
for (const group of manifest.ui) {
|
||||||
|
const stem = UI_GROUP_FILES[group];
|
||||||
|
if (stem) files.push(`src/i18n/locales/vi/ui/${stem}.json`, `src/i18n/locales/en/ui/${stem}.json`);
|
||||||
|
}
|
||||||
|
return files;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Route id = the bar path with the leading slash dropped ('/' → 'home',
|
||||||
|
// '/how-it-works' → 'how-it-works') — the same ids the manifests carry.
|
||||||
|
function lastmodForRoute(route: string): string {
|
||||||
|
const id = route === '/' ? 'home' : route.slice(1);
|
||||||
|
const files = manifestFiles(id);
|
||||||
|
return files ? gitDate(files) : buildDate;
|
||||||
|
}
|
||||||
|
|
||||||
|
// navPaths is the seven bar routes; the eighth URL group (/projects/:id) is
|
||||||
|
// enumerated from the project data, so a new project lands in the sitemap
|
||||||
|
// automatically.
|
||||||
const locations = [
|
const locations = [
|
||||||
...navPaths.map((path) => `${siteUrl}${path}`),
|
...navPaths.map((path) => ({
|
||||||
...projects.map((project) => `${siteUrl}/projects/${project.id}`),
|
loc: `${siteUrl}${path}`,
|
||||||
|
lastmod: lastmodForRoute(path),
|
||||||
|
})),
|
||||||
|
...projects.map((project) => ({
|
||||||
|
loc: `${siteUrl}/projects/${project.id}`,
|
||||||
|
lastmod: gitDate(PROJECT_DETAIL_FILES),
|
||||||
|
})),
|
||||||
];
|
];
|
||||||
|
|
||||||
const entries = locations
|
const entries = locations
|
||||||
.map((loc) => ` <url>\n <loc>${loc}</loc>\n <lastmod>${lastmod}</lastmod>\n </url>`)
|
.map((url) => ` <url>\n <loc>${url.loc}</loc>\n <lastmod>${url.lastmod}</lastmod>\n </url>`)
|
||||||
.join('\n');
|
.join('\n');
|
||||||
|
|
||||||
const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries}\n</urlset>\n`;
|
const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries}\n</urlset>\n`;
|
||||||
|
|||||||
+19
-2
@@ -610,10 +610,20 @@
|
|||||||
margin-bottom: 48px;
|
margin-bottom: 48px;
|
||||||
}
|
}
|
||||||
|
|
||||||
.section-heading h2 {
|
.section-heading h2,
|
||||||
|
.section-heading h1 {
|
||||||
margin-bottom: 8px;
|
margin-bottom: 8px;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Page H1 (spec-v8 §4): a standalone page's main heading is now an h1 — it
|
||||||
|
keeps the section-heading visual size, so the visual hierarchy is unchanged
|
||||||
|
and only the document outline is corrected. The hero's own h1 (homepage)
|
||||||
|
is not a SectionHeading and keeps the global display size. */
|
||||||
|
.section-heading h1 {
|
||||||
|
font-size: clamp(24px, 4vw, 40px);
|
||||||
|
letter-spacing: -0.01em;
|
||||||
|
}
|
||||||
|
|
||||||
.section-heading p {
|
.section-heading p {
|
||||||
font-size: 18px;
|
font-size: 18px;
|
||||||
}
|
}
|
||||||
@@ -2044,7 +2054,7 @@
|
|||||||
box-shadow: inset 0 1px 0 var(--inset-highlight);
|
box-shadow: inset 0 1px 0 var(--inset-highlight);
|
||||||
}
|
}
|
||||||
|
|
||||||
.project-section h4 {
|
.project-section h3 {
|
||||||
margin-top: 0;
|
margin-top: 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -2053,6 +2063,13 @@
|
|||||||
line-height: var(--leading-body);
|
line-height: var(--leading-body);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Diagram/code sections (spec-v8 §4): the global pre block in index.css
|
||||||
|
carries the monospace chrome; only the margin is neutralised so the block
|
||||||
|
sits inside the card's own padding. */
|
||||||
|
.project-section .project-diagram {
|
||||||
|
margin: 0;
|
||||||
|
}
|
||||||
|
|
||||||
.back-link {
|
.back-link {
|
||||||
display: inline-block;
|
display: inline-block;
|
||||||
font-size: var(--text-meta);
|
font-size: var(--text-meta);
|
||||||
|
|||||||
@@ -20,6 +20,9 @@ const HowItWorksPage = lazy(() => import('@/pages/HowItWorksPage').then((m) => (
|
|||||||
|
|
||||||
const ContactPage = lazy(() => import('@/pages/ContactPage').then((m) => ({ default: m.ContactPage })))
|
const ContactPage = lazy(() => import('@/pages/ContactPage').then((m) => ({ default: m.ContactPage })))
|
||||||
|
|
||||||
|
// The in-app 404 is lazy like the other non-LCP routes (spec-v8 §2.1).
|
||||||
|
const NotFoundPage = lazy(() => import('@/pages/NotFoundPage').then((m) => ({ default: m.NotFoundPage })))
|
||||||
|
|
||||||
// Edit mode is lazy too: visitors never download the draft store, the panel
|
// Edit mode is lazy too: visitors never download the draft store, the panel
|
||||||
// or the save pipeline (spec-v4 §7 P3.4). The gate opens the shell on `?edit`
|
// or the save pipeline (spec-v4 §7 P3.4). The gate opens the shell on `?edit`
|
||||||
// or on a session that is already in the mode; the shell authenticates, or it
|
// or on a session that is already in the mode; the shell authenticates, or it
|
||||||
@@ -63,6 +66,10 @@ function App() {
|
|||||||
<Route path="/philosophy" element={<PhilosophyPage />} />
|
<Route path="/philosophy" element={<PhilosophyPage />} />
|
||||||
<Route path="/how-it-works" element={<HowItWorksPage />} />
|
<Route path="/how-it-works" element={<HowItWorksPage />} />
|
||||||
<Route path="/contact" element={<ContactPage />} />
|
<Route path="/contact" element={<ContactPage />} />
|
||||||
|
{/* spec-v8 §2.1: a dead link inside the SPA lands on the
|
||||||
|
in-app 404 instead of an empty main. Direct hits on
|
||||||
|
unknown URLs are answered by nginx with a real 404. */}
|
||||||
|
<Route path="*" element={<NotFoundPage />} />
|
||||||
</Routes>
|
</Routes>
|
||||||
</Suspense>
|
</Suspense>
|
||||||
</Layout>
|
</Layout>
|
||||||
|
|||||||
@@ -7,13 +7,18 @@ interface SectionHeadingProps {
|
|||||||
subtitle?: ReactNode
|
subtitle?: ReactNode
|
||||||
tag?: string
|
tag?: string
|
||||||
id?: string
|
id?: string
|
||||||
|
// spec-v8 §4: every standalone page renders its main heading as h1 — this
|
||||||
|
// is the single place page headings are produced. Sections inside a page
|
||||||
|
// (and the homepage's sections) keep the default h2.
|
||||||
|
level?: 'h1' | 'h2'
|
||||||
}
|
}
|
||||||
|
|
||||||
export function SectionHeading({ title, subtitle, tag, id }: SectionHeadingProps) {
|
export function SectionHeading({ title, subtitle, tag, id, level = 'h2' }: SectionHeadingProps) {
|
||||||
|
const Heading = level
|
||||||
return (
|
return (
|
||||||
<div className="section-heading" id={id}>
|
<div className="section-heading" id={id}>
|
||||||
{tag && <span className="section-tag">{tag}</span>}
|
{tag && <span className="section-tag">{tag}</span>}
|
||||||
<h2>{title}</h2>
|
<Heading>{title}</Heading>
|
||||||
{subtitle}
|
{subtitle}
|
||||||
</div>
|
</div>
|
||||||
)
|
)
|
||||||
|
|||||||
@@ -8,5 +8,5 @@
|
|||||||
},
|
},
|
||||||
{ "entity": "skillGroups", "fields": ["*"] }
|
{ "entity": "skillGroups", "fields": ["*"] }
|
||||||
],
|
],
|
||||||
"ui": ["about"]
|
"ui": ["about", "meta"]
|
||||||
}
|
}
|
||||||
@@ -16,5 +16,5 @@
|
|||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"ui": ["contact"]
|
"ui": ["contact", "meta"]
|
||||||
}
|
}
|
||||||
@@ -5,5 +5,5 @@
|
|||||||
{ "entity": "profile", "fields": ["tldr", "name"] },
|
{ "entity": "profile", "fields": ["tldr", "name"] },
|
||||||
{ "entity": "experiences", "fields": ["*"] }
|
{ "entity": "experiences", "fields": ["*"] }
|
||||||
],
|
],
|
||||||
"ui": ["experience"]
|
"ui": ["experience", "meta"]
|
||||||
}
|
}
|
||||||
@@ -4,5 +4,5 @@
|
|||||||
"content": [
|
"content": [
|
||||||
{ "entity": "profile", "fields": ["name"] }
|
{ "entity": "profile", "fields": ["name"] }
|
||||||
],
|
],
|
||||||
"ui": ["howItWorks"]
|
"ui": ["howItWorks", "meta"]
|
||||||
}
|
}
|
||||||
@@ -4,5 +4,5 @@
|
|||||||
"content": [
|
"content": [
|
||||||
{ "entity": "profile", "fields": ["philosophyQuotes", "name"] }
|
{ "entity": "profile", "fields": ["philosophyQuotes", "name"] }
|
||||||
],
|
],
|
||||||
"ui": ["philosophy"]
|
"ui": ["philosophy", "meta"]
|
||||||
}
|
}
|
||||||
@@ -5,5 +5,5 @@
|
|||||||
{ "entity": "projects", "fields": ["*"] },
|
{ "entity": "projects", "fields": ["*"] },
|
||||||
{ "entity": "profile", "fields": ["name"] }
|
{ "entity": "profile", "fields": ["name"] }
|
||||||
],
|
],
|
||||||
"ui": ["projects"]
|
"ui": ["projects", "meta"]
|
||||||
}
|
}
|
||||||
@@ -24,6 +24,7 @@ import howItWorksJson from './locales/vi/ui/how-it-works.json';
|
|||||||
import commonJson from './locales/vi/ui/common.json';
|
import commonJson from './locales/vi/ui/common.json';
|
||||||
import resumeJson from './locales/vi/ui/resume.json';
|
import resumeJson from './locales/vi/ui/resume.json';
|
||||||
import editJson from './locales/vi/ui/edit.json';
|
import editJson from './locales/vi/ui/edit.json';
|
||||||
|
import metaJson from './locales/vi/ui/meta.json';
|
||||||
|
|
||||||
// --- structure (src/data/*.json) ---
|
// --- structure (src/data/*.json) ---
|
||||||
|
|
||||||
@@ -157,4 +158,8 @@ export type UIDict = {
|
|||||||
common: typeof commonJson;
|
common: typeof commonJson;
|
||||||
resume: typeof resumeJson;
|
resume: typeof resumeJson;
|
||||||
edit: typeof editJson;
|
edit: typeof editJson;
|
||||||
|
// Per-page SEO meta (spec-v8 §2): the title/description the route generator
|
||||||
|
// writes into each page's head. Page-owned by definition — the titles match
|
||||||
|
// the page H1s, so the group is claimed by the six static page manifests.
|
||||||
|
meta: typeof metaJson;
|
||||||
};
|
};
|
||||||
@@ -28,6 +28,7 @@ import uiHowItWorksViJson from './locales/vi/ui/how-it-works.json';
|
|||||||
import uiCommonViJson from './locales/vi/ui/common.json';
|
import uiCommonViJson from './locales/vi/ui/common.json';
|
||||||
import uiResumeViJson from './locales/vi/ui/resume.json';
|
import uiResumeViJson from './locales/vi/ui/resume.json';
|
||||||
import uiEditViJson from './locales/vi/ui/edit.json';
|
import uiEditViJson from './locales/vi/ui/edit.json';
|
||||||
|
import uiMetaViJson from './locales/vi/ui/meta.json';
|
||||||
import uiNavEnJson from './locales/en/ui/navigation.json';
|
import uiNavEnJson from './locales/en/ui/navigation.json';
|
||||||
import uiSocialEnJson from './locales/en/ui/social.json';
|
import uiSocialEnJson from './locales/en/ui/social.json';
|
||||||
import uiFooterEnJson from './locales/en/ui/footer.json';
|
import uiFooterEnJson from './locales/en/ui/footer.json';
|
||||||
@@ -43,6 +44,7 @@ import uiHowItWorksEnJson from './locales/en/ui/how-it-works.json';
|
|||||||
import uiCommonEnJson from './locales/en/ui/common.json';
|
import uiCommonEnJson from './locales/en/ui/common.json';
|
||||||
import uiResumeEnJson from './locales/en/ui/resume.json';
|
import uiResumeEnJson from './locales/en/ui/resume.json';
|
||||||
import uiEditEnJson from './locales/en/ui/edit.json';
|
import uiEditEnJson from './locales/en/ui/edit.json';
|
||||||
|
import uiMetaEnJson from './locales/en/ui/meta.json';
|
||||||
import type {
|
import type {
|
||||||
ContentEn,
|
ContentEn,
|
||||||
ContentVi,
|
ContentVi,
|
||||||
@@ -97,6 +99,7 @@ const uiVi: UIDict = {
|
|||||||
common: uiCommonViJson,
|
common: uiCommonViJson,
|
||||||
resume: uiResumeViJson,
|
resume: uiResumeViJson,
|
||||||
edit: uiEditViJson,
|
edit: uiEditViJson,
|
||||||
|
meta: uiMetaViJson,
|
||||||
};
|
};
|
||||||
// tsc enforces en completeness against the Vietnamese tree (§3.3).
|
// tsc enforces en completeness against the Vietnamese tree (§3.3).
|
||||||
const uiEn: UIDict = {
|
const uiEn: UIDict = {
|
||||||
@@ -115,6 +118,7 @@ const uiEn: UIDict = {
|
|||||||
common: uiCommonEnJson,
|
common: uiCommonEnJson,
|
||||||
resume: uiResumeEnJson,
|
resume: uiResumeEnJson,
|
||||||
edit: uiEditEnJson,
|
edit: uiEditEnJson,
|
||||||
|
meta: uiMetaEnJson,
|
||||||
};
|
};
|
||||||
|
|
||||||
const structures = {
|
const structures = {
|
||||||
|
|||||||
@@ -6,5 +6,9 @@
|
|||||||
"resumeModalClose": "Close resume options",
|
"resumeModalClose": "Close resume options",
|
||||||
"backToTop": "Scroll to top",
|
"backToTop": "Scroll to top",
|
||||||
"contactTag": "Contact",
|
"contactTag": "Contact",
|
||||||
"experienceTag": "Experience"
|
"experienceTag": "Experience",
|
||||||
|
"notFoundTitle": "Page not found",
|
||||||
|
"notFoundBody": "The page you were looking for does not exist — the address may be mistyped or the page may have moved.",
|
||||||
|
"notFoundHome": "Go to homepage",
|
||||||
|
"notFoundProjects": "Browse projects"
|
||||||
}
|
}
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"about": {
|
||||||
|
"title": "About Me",
|
||||||
|
"description": "The person, engineering principles and current interests behind this portfolio — Nguyễn Đông, Senior Software Engineer in Ho Chi Minh City."
|
||||||
|
},
|
||||||
|
"experience": {
|
||||||
|
"title": "Experience",
|
||||||
|
"description": "Work history in Ho Chi Minh City: SAP Lab Vietnam — a logistics digital-twin platform, Lazada — automation and computer vision on sortation lines, and the breaks between."
|
||||||
|
},
|
||||||
|
"projects": {
|
||||||
|
"title": "Projects",
|
||||||
|
"description": "Project case studies with role, constraints and results: IoT-DWS integration across 16 sortations and AWB detection with computer vision."
|
||||||
|
},
|
||||||
|
"contact": {
|
||||||
|
"title": "Contact",
|
||||||
|
"description": "Get in touch with Nguyễn Đông — email, GitHub, LinkedIn and Telegram links."
|
||||||
|
},
|
||||||
|
"philosophy": {
|
||||||
|
"title": "Philosophy",
|
||||||
|
"description": "The engineering principles applied in every project on this site, stated as short quotes with their keywords."
|
||||||
|
},
|
||||||
|
"how-it-works": {
|
||||||
|
"title": "How this site works",
|
||||||
|
"description": "A short explainer of how this portfolio is built: git-backed content, live editing on the page, bilingual dictionaries and automatic deploy through GitHub Actions."
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -21,7 +21,7 @@
|
|||||||
},
|
},
|
||||||
"architecture": {
|
"architecture": {
|
||||||
"title": "Architecture",
|
"title": "Architecture",
|
||||||
"content": "```text\nIoT Devices\n ↓\nProtocol Adapters (HMI/FTP/HTTP)\n ↓\nHTTP Engine + HMAC Security\n ↓\nRocketMQ\n ↓\nDWS Machines\n```"
|
"content": "IoT Devices\n ↓\nProtocol Adapters (HMI/FTP/HTTP)\n ↓\nHTTP Engine + HMAC Security\n ↓\nRocketMQ\n ↓\nDWS Machines"
|
||||||
},
|
},
|
||||||
"challenges": {
|
"challenges": {
|
||||||
"title": "Challenges",
|
"title": "Challenges",
|
||||||
@@ -51,7 +51,7 @@
|
|||||||
},
|
},
|
||||||
"pipeline": {
|
"pipeline": {
|
||||||
"title": "Pipeline",
|
"title": "Pipeline",
|
||||||
"content": "```text\nImage\n ↓\nAWB/Label Detection (YOLO)\n ↓\nBounding Box / OBB\n ↓\nRotation Correction\n ↓\nCrop\n ↓\nOCR\n ↓\nText Extraction\n```"
|
"content": "Image\n ↓\nAWB/Label Detection (YOLO)\n ↓\nBounding Box / OBB\n ↓\nRotation Correction\n ↓\nCrop\n ↓\nOCR\n ↓\nText Extraction"
|
||||||
},
|
},
|
||||||
"challenges": {
|
"challenges": {
|
||||||
"title": "Challenges",
|
"title": "Challenges",
|
||||||
|
|||||||
@@ -6,5 +6,9 @@
|
|||||||
"resumeModalClose": "Đóng tùy chọn tải CV",
|
"resumeModalClose": "Đóng tùy chọn tải CV",
|
||||||
"backToTop": "Cuộn lên đầu trang",
|
"backToTop": "Cuộn lên đầu trang",
|
||||||
"contactTag": "Liên hệ",
|
"contactTag": "Liên hệ",
|
||||||
"experienceTag": "Kinh nghiệm"
|
"experienceTag": "Kinh nghiệm",
|
||||||
|
"notFoundTitle": "Không tìm thấy trang",
|
||||||
|
"notFoundBody": "Trang bạn tìm không tồn tại — có thể địa chỉ bị gõ sai hoặc trang đã được chuyển đi.",
|
||||||
|
"notFoundHome": "Về trang chủ",
|
||||||
|
"notFoundProjects": "Xem các dự án"
|
||||||
}
|
}
|
||||||
@@ -0,0 +1,26 @@
|
|||||||
|
{
|
||||||
|
"about": {
|
||||||
|
"title": "Giới thiệu",
|
||||||
|
"description": "Con người, nguyên tắc làm việc và mối quan tâm hiện tại của Nguyễn Đông — kỹ sư phần mềm cấp cao tại TP.HCM."
|
||||||
|
},
|
||||||
|
"experience": {
|
||||||
|
"title": "Kinh nghiệm",
|
||||||
|
"description": "Lịch sử làm việc tại TP.HCM: SAP Lab Vietnam — nền tảng digital twin logistics, Lazada — tự động hóa và computer vision trên các dây phân loại, và những khoảng nghỉ giữa hai công ty."
|
||||||
|
},
|
||||||
|
"projects": {
|
||||||
|
"title": "Dự án",
|
||||||
|
"description": "Toàn bộ dự án kèm vai trò, ràng buộc và kết quả: tích hợp IoT-DWS trên 16 dây phân loại và phát hiện AWB bằng computer vision."
|
||||||
|
},
|
||||||
|
"contact": {
|
||||||
|
"title": "Liên hệ",
|
||||||
|
"description": "Liên hệ với Nguyễn Đông — email, GitHub, LinkedIn và Telegram."
|
||||||
|
},
|
||||||
|
"philosophy": {
|
||||||
|
"title": "Triết lý",
|
||||||
|
"description": "Các nguyên tắc kỹ sư được áp dụng trong mọi dự án trên trang này."
|
||||||
|
},
|
||||||
|
"how-it-works": {
|
||||||
|
"title": "Trang hoạt động như thế nào",
|
||||||
|
"description": "Giới thiệu ngắn về cách trang này được xây dựng: nội dung lưu trong git, chỉnh sửa trực tiếp trên trang, từ điển song ngữ và tự động deploy qua GitHub Actions."
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -27,6 +27,7 @@ export function AboutPage() {
|
|||||||
}}
|
}}
|
||||||
>
|
>
|
||||||
<SectionHeading
|
<SectionHeading
|
||||||
|
level="h1"
|
||||||
title={s.about.heading}
|
title={s.about.heading}
|
||||||
subtitle={
|
subtitle={
|
||||||
<EditableText
|
<EditableText
|
||||||
|
|||||||
@@ -18,7 +18,7 @@ export function ContactPage() {
|
|||||||
visible: { opacity: 1, transition: { duration: 0.5 } },
|
visible: { opacity: 1, transition: { duration: 0.5 } },
|
||||||
}}
|
}}
|
||||||
>
|
>
|
||||||
<SectionHeading title={s.contact.heading} tag={s.common.contactTag} />
|
<SectionHeading level="h1" title={s.contact.heading} tag={s.common.contactTag} />
|
||||||
<ContactLinks />
|
<ContactLinks />
|
||||||
</motion.section>
|
</motion.section>
|
||||||
</InView>
|
</InView>
|
||||||
|
|||||||
@@ -26,7 +26,7 @@ export function ExperiencePage() {
|
|||||||
visible: { opacity: 1, transition: { duration: 0.5 } },
|
visible: { opacity: 1, transition: { duration: 0.5 } },
|
||||||
}}
|
}}
|
||||||
>
|
>
|
||||||
<SectionHeading title={s.experience.heading} tag={s.common.experienceTag} />
|
<SectionHeading level="h1" title={s.experience.heading} tag={s.common.experienceTag} />
|
||||||
<div className="timeline">
|
<div className="timeline">
|
||||||
{c.experiences.map((exp, i) => (
|
{c.experiences.map((exp, i) => (
|
||||||
<motion.div
|
<motion.div
|
||||||
|
|||||||
@@ -40,6 +40,7 @@ export function HowItWorksPage() {
|
|||||||
>
|
>
|
||||||
<SectionHeading
|
<SectionHeading
|
||||||
id="how-it-works-heading"
|
id="how-it-works-heading"
|
||||||
|
level="h1"
|
||||||
title={s.howItWorks.heading}
|
title={s.howItWorks.heading}
|
||||||
tag={s.howItWorks.heading}
|
tag={s.howItWorks.heading}
|
||||||
/>
|
/>
|
||||||
|
|||||||
@@ -0,0 +1,39 @@
|
|||||||
|
import { Link } from 'react-router'
|
||||||
|
import { motion } from 'motion/react'
|
||||||
|
import { InView } from '@/components/ui/InView'
|
||||||
|
import { SectionHeading } from '@/components/ui/SectionHeading'
|
||||||
|
import { useI18n } from '@/i18n/provider'
|
||||||
|
|
||||||
|
// The in-app 404 (spec-v8 §2.1): what a visitor sees when the SPA itself
|
||||||
|
// navigates to a dead link (dev server, preview, or a stale internal link).
|
||||||
|
// Direct hits on unknown URLs are answered by nginx with a real 404 and the
|
||||||
|
// generated dist/404.html — this page is the client-side counterpart, sharing
|
||||||
|
// the same ui/common notFound text.
|
||||||
|
const sectionVariants = {
|
||||||
|
hidden: { opacity: 0 },
|
||||||
|
visible: { opacity: 1, transition: { duration: 0.5 } },
|
||||||
|
}
|
||||||
|
|
||||||
|
export function NotFoundPage() {
|
||||||
|
const { ui: s } = useI18n()
|
||||||
|
|
||||||
|
return (
|
||||||
|
<InView>
|
||||||
|
<motion.section
|
||||||
|
className="section container-content"
|
||||||
|
initial="hidden"
|
||||||
|
whileInView="visible"
|
||||||
|
viewport={{ once: true, amount: 0.1 }}
|
||||||
|
variants={sectionVariants}
|
||||||
|
>
|
||||||
|
<SectionHeading level="h1" title={s.common.notFoundTitle} />
|
||||||
|
<div className="page-body">
|
||||||
|
<p>{s.common.notFoundBody}</p>
|
||||||
|
<p>
|
||||||
|
<Link to="/">{s.common.notFoundHome}</Link>
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
</motion.section>
|
||||||
|
</InView>
|
||||||
|
)
|
||||||
|
}
|
||||||
@@ -27,7 +27,7 @@ export function PhilosophyPage() {
|
|||||||
visible: {opacity: 1, transition: {duration: 0.5}},
|
visible: {opacity: 1, transition: {duration: 0.5}},
|
||||||
}}
|
}}
|
||||||
>
|
>
|
||||||
<SectionHeading id="philosophy-heading" title={s.philosophy.heading} tag={s.philosophy.heading}/>
|
<SectionHeading id="philosophy-heading" level="h1" title={s.philosophy.heading} tag={s.philosophy.heading}/>
|
||||||
<div className="prose prose-wide">
|
<div className="prose prose-wide">
|
||||||
{c.profile.philosophyQuotes.map((quote, i) => (
|
{c.profile.philosophyQuotes.map((quote, i) => (
|
||||||
<motion.div
|
<motion.div
|
||||||
|
|||||||
@@ -2,6 +2,7 @@ import { useParams, Link } from 'react-router'
|
|||||||
import { motion, type Transition } from 'motion/react'
|
import { motion, type Transition } from 'motion/react'
|
||||||
import { Badge } from '@/components/ui/Badge'
|
import { Badge } from '@/components/ui/Badge'
|
||||||
import { Tag } from '@/components/ui/Tag'
|
import { Tag } from '@/components/ui/Tag'
|
||||||
|
import { SectionHeading } from '@/components/ui/SectionHeading'
|
||||||
import { EditableText } from '@/components/ui/EditableText'
|
import { EditableText } from '@/components/ui/EditableText'
|
||||||
import { InView } from '@/components/ui/InView'
|
import { InView } from '@/components/ui/InView'
|
||||||
import { useI18n } from '@/i18n/provider'
|
import { useI18n } from '@/i18n/provider'
|
||||||
@@ -37,7 +38,7 @@ export function ProjectDetailPage() {
|
|||||||
viewport={{ once: true, amount: 0.1 }}
|
viewport={{ once: true, amount: 0.1 }}
|
||||||
variants={sectionVariants}
|
variants={sectionVariants}
|
||||||
>
|
>
|
||||||
<h2>{s.projectDetail.notFound}</h2>
|
<SectionHeading level="h1" title={s.projectDetail.notFound} />
|
||||||
<p>
|
<p>
|
||||||
<Link to="/projects">{s.projectDetail.backToProjects} ←</Link>
|
<Link to="/projects">{s.projectDetail.backToProjects} ←</Link>
|
||||||
</p>
|
</p>
|
||||||
@@ -102,7 +103,7 @@ export function ProjectDetailPage() {
|
|||||||
viewport={{ once: true, amount: 0.2 }}
|
viewport={{ once: true, amount: 0.2 }}
|
||||||
transition={itemTransition(0.16)}
|
transition={itemTransition(0.16)}
|
||||||
>
|
>
|
||||||
<h3>{s.projectDetail.impact}</h3>
|
<h2>{s.projectDetail.impact}</h2>
|
||||||
<TagListEditor
|
<TagListEditor
|
||||||
arrayPath={`projects.${project.id}.metrics`}
|
arrayPath={`projects.${project.id}.metrics`}
|
||||||
items={project.metrics ?? []}
|
items={project.metrics ?? []}
|
||||||
@@ -122,7 +123,7 @@ export function ProjectDetailPage() {
|
|||||||
viewport={{ once: true, amount: 0.2 }}
|
viewport={{ once: true, amount: 0.2 }}
|
||||||
transition={itemTransition(0.24)}
|
transition={itemTransition(0.24)}
|
||||||
>
|
>
|
||||||
<h3>{s.projectDetail.role}</h3>
|
<h2>{s.projectDetail.role}</h2>
|
||||||
<EditableText as="p" path={`projects.${project.id}.role`} label={s.edit.fields.projectRole}>
|
<EditableText as="p" path={`projects.${project.id}.role`} label={s.edit.fields.projectRole}>
|
||||||
{project.role}
|
{project.role}
|
||||||
</EditableText>
|
</EditableText>
|
||||||
@@ -134,7 +135,7 @@ export function ProjectDetailPage() {
|
|||||||
viewport={{ once: true, amount: 0.2 }}
|
viewport={{ once: true, amount: 0.2 }}
|
||||||
transition={itemTransition(0.32)}
|
transition={itemTransition(0.32)}
|
||||||
>
|
>
|
||||||
<h3>{s.projectDetail.technologies}</h3>
|
<h2>{s.projectDetail.technologies}</h2>
|
||||||
<TagListEditor
|
<TagListEditor
|
||||||
doc="projects"
|
doc="projects"
|
||||||
arrayPath={`[${c.projects.findIndex((p) => p.id === project.id)}].technologies`}
|
arrayPath={`[${c.projects.findIndex((p) => p.id === project.id)}].technologies`}
|
||||||
@@ -149,14 +150,14 @@ export function ProjectDetailPage() {
|
|||||||
|
|
||||||
{(edit || (project.sections?.length ?? 0) > 0) && (
|
{(edit || (project.sections?.length ?? 0) > 0) && (
|
||||||
<div>
|
<div>
|
||||||
<motion.h3
|
<motion.h2
|
||||||
initial={{ opacity: 0, y: 24 }}
|
initial={{ opacity: 0, y: 24 }}
|
||||||
whileInView={{ opacity: 1, y: 0 }}
|
whileInView={{ opacity: 1, y: 0 }}
|
||||||
viewport={{ once: true, amount: 0.2 }}
|
viewport={{ once: true, amount: 0.2 }}
|
||||||
transition={itemTransition(0.4)}
|
transition={itemTransition(0.4)}
|
||||||
>
|
>
|
||||||
{s.projectDetail.experiments}
|
{s.projectDetail.experiments}
|
||||||
</motion.h3>
|
</motion.h2>
|
||||||
{project.sections.map((section, idx) => (
|
{project.sections.map((section, idx) => (
|
||||||
<motion.div
|
<motion.div
|
||||||
key={section.id}
|
key={section.id}
|
||||||
@@ -176,13 +177,23 @@ export function ProjectDetailPage() {
|
|||||||
onDelete={() => edit.deleteRecord('section', { id: section.id, projectId: project.id })}
|
onDelete={() => edit.deleteRecord('section', { id: section.id, projectId: project.id })}
|
||||||
/>
|
/>
|
||||||
)}
|
)}
|
||||||
<EditableText as="h4" path={`projects.${project.id}.sections.${section.id}.title`} label={`${section.title} — ${s.edit.fields.sectionTitle}`}>
|
<EditableText as="h3" path={`projects.${project.id}.sections.${section.id}.title`} label={`${section.title} — ${s.edit.fields.sectionTitle}`}>
|
||||||
{section.title}
|
{section.title}
|
||||||
</EditableText>
|
</EditableText>
|
||||||
<EditableText as="p" path={`projects.${project.id}.sections.${section.id}.content`} label={`${section.title} — ${s.edit.fields.sectionContent}`} multiline>
|
{/* spec-v8 §4: diagram and code sections are monospace blocks —
|
||||||
{section.content}
|
the ASCII pipeline diagrams in the VI document render as
|
||||||
</EditableText>
|
written; the record's type chip is edit-mode chrome, never
|
||||||
<Tag accent>{section.type}</Tag>
|
public content. */}
|
||||||
|
{(section.type === 'diagram' || section.type === 'code') ? (
|
||||||
|
<EditableText as="pre" className="project-diagram" path={`projects.${project.id}.sections.${section.id}.content`} label={`${section.title} — ${s.edit.fields.sectionContent}`} multiline>
|
||||||
|
{section.content}
|
||||||
|
</EditableText>
|
||||||
|
) : (
|
||||||
|
<EditableText as="p" path={`projects.${project.id}.sections.${section.id}.content`} label={`${section.title} — ${s.edit.fields.sectionContent}`} multiline>
|
||||||
|
{section.content}
|
||||||
|
</EditableText>
|
||||||
|
)}
|
||||||
|
{edit && <Tag accent>{section.type}</Tag>}
|
||||||
</motion.div>
|
</motion.div>
|
||||||
))}
|
))}
|
||||||
{edit && (
|
{edit && (
|
||||||
|
|||||||
@@ -32,7 +32,7 @@ export function ProjectsListPage() {
|
|||||||
visible: { opacity: 1, transition: { duration: 0.5 } },
|
visible: { opacity: 1, transition: { duration: 0.5 } },
|
||||||
}}
|
}}
|
||||||
>
|
>
|
||||||
<SectionHeading title={s.projects.all} tag={s.projects.all} />
|
<SectionHeading level="h1" title={s.projects.all} tag={s.projects.all} />
|
||||||
<div className="projects-grid">
|
<div className="projects-grid">
|
||||||
{c.projects.map((project, i) => {
|
{c.projects.map((project, i) => {
|
||||||
const card = (
|
const card = (
|
||||||
|
|||||||
Reference in new issue
Block a user