mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10: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
+1181
-47
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user