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

+57 -3
View File
@@ -7,16 +7,63 @@ server {
root /usr/share/nginx/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 / {
try_files $uri $uri/ /index.html;
try_files $uri/index.html $uri =404;
}
error_page 404 /404.html;
# Do not aggressively cache index.html.
# It references the latest hashed JS/CSS files.
location = /index.html {
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";
}
@@ -26,6 +73,13 @@ server {
try_files $uri =404;
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";
}
@@ -67,4 +121,4 @@ server {
# prefix was Gitea's.
proxy_set_header Authorization "Bearer ${CONTENT_API_TOKEN}";
}
}
}