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:
dong.nguyen committed 2026-11-02 13:02:53 +07:00
1 parent e02fe19bbe
commit 0dd2c6b3ee
32 files changed
+1181 -47

No files matched your search

+371
View File
@@ -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, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
.replace(/"/g, '&quot;');
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
View File
@@ -1,14 +1,18 @@
import { execFileSync } from 'node:child_process';
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { siteUrl } from '../src/data/site.js';
import { navPaths } from '../src/data/navigation.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 distDir = join(ROOT, 'dist');
// Run after `vite build`: the sitemap is a build artifact, and the guard below can
// only compare against a head that has already been produced.
// Run after `vite build` and `pnpm generate:routes`: the sitemap is a build
// artifact, and the guards below can only compare against artifacts that have
// already been produced.
if (!existsSync(distDir)) {
console.error(`dist/ not found — run \`pnpm build\` before \`pnpm sitemap\`.`);
process.exit(1);
@@ -22,22 +26,142 @@ const indexHtml = readFileSync(join(distDir, 'index.html'), 'utf-8');
if (!indexHtml.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.`,
'The site-identity plugin injects it from SITE_URL — check the build environment.',
);
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
// from the project data, so a new project lands in the sitemap automatically.
// --- lastmod from the documents that back each URL (spec-v8 §2.1) ----------
// 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 = [
...navPaths.map((path) => `${siteUrl}${path}`),
...projects.map((project) => `${siteUrl}/projects/${project.id}`),
...navPaths.map((path) => ({
loc: `${siteUrl}${path}`,
lastmod: lastmodForRoute(path),
})),
...projects.map((project) => ({
loc: `${siteUrl}/projects/${project.id}`,
lastmod: gitDate(PROJECT_DETAIL_FILES),
})),
];
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');
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`;