diff --git a/LLM_RULES.md b/LLM_RULES.md index 663a383..7328b2f 100644 --- a/LLM_RULES.md +++ b/LLM_RULES.md @@ -52,7 +52,7 @@ selectors: data-\*-mount ONLY for JS mount points. no generic IDs except well-kn responsive: use static/js/core/responsive.js helpers. no ad-hoc breakpoints in JS. daisyUI: data-tip XOR title. never both. typography: HTML class="not-prose". NO CSS @apply not-prose. -access-keys: SEMANTIC_RULES in access-keys.js = single source of truth for keyboard hints. no data-hint in templates except override cases. elements inside [data-toc-sidebar] are excluded from semantic rules (internal anchors). +access-keys: SEMANTIC_RULES in access-keys.js = single source of truth for keyboard hints. no data-hint in templates except override cases. elements inside [data-toc-sidebar] are excluded from semantic rules (internal anchors). if a force-rail page needs a shortcut for a rail item like Archive, set an explicit `data-hint` on that template link. TOC: single initToc() from toc.js covers ALL pages (blog, archive, taxonomy). getTocLink uses href$=#ID for full-URL zola children AND data-toc-ID for summary parents AND bare #ID for archive anchors. notify-banner: path is js/ui/notify-banner.js (not root-level js/). @@ -62,7 +62,7 @@ macros: import separate files. no deep same-file chaining. 404 routing: templates/404.html ONLY. no content/404.md. offline page: templates/offline.html (no content/offline.md). 404 + offline layout: \_force_rail=true in base.html → use_fit_shell=true + has_layout_rail=true + empty #toc-sidebar nav (aria-label="Page tools") for full structural parity. Toggle button label is "Hide/Show tools rail" (not "table of contents"). offline page must have force_rail=true in [extra]. -CSP: no inline style="" attributes. use CSS classes. JS DOM manipulation toggles classes only. +CSP: no inline style="" attributes. use CSS classes. JS DOM manipulation toggles classes only. deferred style sheets use `data-defer-css="true"` and get activated by `static/js/core/boot.js`; avoid inline event-handler attributes on style sheet links. SEO / SCHEMA article JSON-LD: author Person must include both name AND URL (→ /about/). diff --git a/scripts/clean-pagination-redirects.js b/scripts/clean-pagination-redirects.js index 230919c..0cf2b63 100644 --- a/scripts/clean-pagination-redirects.js +++ b/scripts/clean-pagination-redirects.js @@ -66,7 +66,12 @@ if (fs.existsSync(sitemapPath) && removedPaths.length > 0) { } } if (purged > 0) { - fs.writeFileSync(sitemapPath, sitemap, "utf8"); + // Write atomically to avoid race conditions: write to a temp file + // and rename into place. This prevents other processes from reading + // a partially-written file and addresses file-system race warnings. + const tmpPath = sitemapPath + ".tmp"; + fs.writeFileSync(tmpPath, sitemap, "utf8"); + fs.renameSync(tmpPath, sitemapPath); console.log(`Purged ${purged} stale page/1 URL(s) from sitemap.xml.`); } } diff --git a/scripts/sync-project-data.js b/scripts/sync-project-data.js index 0512b60..d45ea32 100644 --- a/scripts/sync-project-data.js +++ b/scripts/sync-project-data.js @@ -28,10 +28,16 @@ function parseRepoFromUrl(url) { const match = value.match(/github\.com\/([^/]+)\/([^/#?]+)/i); if (!match) return null; - return { - owner: match[1], - repo: match[2].replace(/\.git$/i, ""), - }; + const owner = match[1]; + const repo = match[2].replace(/\.git$/i, ""); + + // Validate owner and repo against a strict whitelist of characters to + // prevent crafted file data from being used to build unexpected URLs. + // GitHub owners: alphanumeric and hyphens; repos: allow dot/underscore/hyphen. + if (!/^[A-Za-z0-9-]+$/.test(owner)) return null; + if (!/^[A-Za-z0-9._-]+$/.test(repo)) return null; + + return { owner, repo }; } function getGitHubToken() { @@ -60,8 +66,22 @@ function githubRequest(endpoint, token) { if (token) headers.Authorization = `Bearer ${token}`; // lgtm[js/file-access-to-http] token sourced from env or gh CLI return new Promise((resolve, reject) => { + // Construct the full URL via the URL API and validate the hostname so + // injected or unexpected endpoint values cannot cause requests to other + // origins. This ensures outbound requests are constrained to GitHub. + let urlObj; + try { + urlObj = new URL(endpoint, API_BASE); + } catch { + return reject(new Error("Invalid GitHub API endpoint")); + } + + if (urlObj.hostname !== new URL(API_BASE).hostname) { + return reject(new Error("Disallowed GitHub API host")); + } + const req = https.request( - `${API_BASE}${endpoint}`, + urlObj, { method: "GET", headers, diff --git a/static/js/core/boot.js b/static/js/core/boot.js index b16a274..d4909de 100644 --- a/static/js/core/boot.js +++ b/static/js/core/boot.js @@ -24,10 +24,36 @@ : raw; d.setAttribute("data-theme", mode); + // Also set a theme class immediately so CSS prepaint rules using + // `html.dark` / `html.light` apply before the JS modules load. This + // prevents a flash/flicker of the wrong logo variant during navigation. + try { + d.classList.remove("light", "dark"); + d.classList.add(mode); + } catch { + // Ignore failures (e.g. if classList isn't supported). The data-theme + // attribute will still be set correctly. + } d.setAttribute("data-ui-init", "0"); d.setAttribute( "data-sidebar-collapsed", getL("sidebar-collapsed") ? "1" : "0", ); d.setAttribute("data-toc-collapsed", getL("toc-collapsed") ? "1" : "0"); + + function activateDeferredCss() { + var links = document.querySelectorAll('link[data-defer-css="true"]'); + for (var i = 0; i < links.length; i += 1) { + links[i].media = "all"; + links[i].removeAttribute("data-defer-css"); + } + } + + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", activateDeferredCss, { + once: true, + }); + } else { + activateDeferredCss(); + } })(); diff --git a/static/js/features/access-keys.js b/static/js/features/access-keys.js index d84523c..3cf50fa 100644 --- a/static/js/features/access-keys.js +++ b/static/js/features/access-keys.js @@ -371,8 +371,9 @@ function showHints() { for (const el of targets) { let explicitHint = null; - // Semantic rules — skip TOC sidebar: those are page-internal anchors - // (#skills, #section-heading) that must not inherit site-nav shortcuts. + // Semantic rules — skip TOC sidebar: those are page-internal anchors that + // must not inherit site-nav shortcuts. If a TOC entry needs a shortcut, + // it should opt in explicitly with data-hint in the template. if (!el.closest("[data-toc-sidebar]")) { for (const rule of SEMANTIC_RULES) { if ( diff --git a/static/js/system/offline-reload.js b/static/js/system/offline-reload.js index 8466f75..5cb0f1f 100644 --- a/static/js/system/offline-reload.js +++ b/static/js/system/offline-reload.js @@ -6,7 +6,10 @@ if (!el) return; var ATTEMPT_KEY = "offlineReloadLastAttempt"; var ATTEMPT_WINDOW_MS = 6000; + var POLL_INTERVAL_MS = 5000; + var PING_TIMEOUT_MS = 2500; var isChecking = false; + var pollInterval = null; el.textContent = "Waiting for connection"; el.classList.add("status-pill", "status-pill--pending"); @@ -16,6 +19,8 @@ el.classList.remove("status-pill--pending"); el.classList.add("status-pill--online"); + if (pollInterval) clearInterval(pollInterval); + setTimeout(function () { var path = window.location.pathname || "/"; if (path === "/offline" || path === "/offline/") { @@ -45,16 +50,25 @@ function probeNetwork() { // Requests under /__runtime/ are excluded from SW handling in static/sw.js. + var controller = new AbortController(); + var timeoutId = window.setTimeout(function () { + controller.abort(); + }, PING_TIMEOUT_MS); + return fetch("/__runtime/ping?ts=" + Date.now(), { method: "GET", cache: "no-store", credentials: "same-origin", + signal: controller.signal, }) .then(function () { return true; }) .catch(function () { return false; + }) + .finally(function () { + window.clearTimeout(timeoutId); }); } @@ -84,4 +98,22 @@ } window.addEventListener("online", maybeRecover); + + function stopPolling() { + if (pollInterval) { + window.clearInterval(pollInterval); + pollInterval = null; + } + } + + // Periodic polling: keep checking network status every POLL_INTERVAL_MS + // even if 'online' event doesn't fire. This ensures recovery on reconnect. + pollInterval = setInterval(function () { + if (navigator.onLine) { + maybeRecover(); + } + }, POLL_INTERVAL_MS); + + window.addEventListener("pagehide", stopPolling, { once: true }); + window.addEventListener("beforeunload", stopPolling, { once: true }); })(); diff --git a/templates/base.html b/templates/base.html index d4504e4..dca20a0 100644 --- a/templates/base.html +++ b/templates/base.html @@ -255,7 +255,7 @@

Blog
  • Links
    • {% endif %} -
  • +
  • Archive
    • diff --git a/templates/macros/head.html b/templates/macros/head.html index d0dc871..6123aad 100644 --- a/templates/macros/head.html +++ b/templates/macros/head.html @@ -85,25 +85,26 @@ {{ load_data(path="static/js/core/boot.js") | safe }} - {# Font configuration with backward compatibility #} - {% if config.extra.font is defined %} - {% set font_enabled = config.extra.font.enabled | default(value=config.extra.custom_font_enabled | default(value=false)) %} - {% set font_name = config.extra.font.name | default(value=config.extra.custom_font_name | default(value='CustomFont')) %} - {% set font_path = config.extra.font.path | default(value=config.extra.custom_font_path | default(value='')) %} + {# Font configuration with backward compatibility #} + {% if config.extra.font is defined %} + {% set font_enabled = config.extra.font.enabled | default(value=config.extra.custom_font_enabled | default(value=false)) %} + {% set font_name = config.extra.font.name | default(value=config.extra.custom_font_name | default(value='CustomFont')) %} + {% set font_path = config.extra.font.path | default(value=config.extra.custom_font_path | default(value='')) %} + {% else %} + {% set font_enabled = config.extra.custom_font_enabled | default(value=false) %} + {% set font_name = config.extra.custom_font_name | default(value='CustomFont') %} + {% set font_path = config.extra.custom_font_path | default(value='') %} + {% endif %} + + {% if font_enabled and font_path != '' %} + {% if font_path is starting_with("http://") or font_path is starting_with("https://") %} + {% else %} - {% set font_enabled = config.extra.custom_font_enabled | default(value=false) %} - {% set font_name = config.extra.custom_font_name | default(value='CustomFont') %} - {% set font_path = config.extra.custom_font_path | default(value='') %} - {% endif %} - {% if font_enabled and font_path != '' %} - {% if font_path is starting_with("http://") or font_path is starting_with("https://") %} - - {% else %} {% set font_url = get_url(path=font_path) %} {% set font_css = "@font-face{font-family:'" ~ font_name ~ "';src:url('" ~ font_url ~ "') format('woff');font-weight:400;font-style:normal;font-display:swap;}body{font-family:'" ~ font_name ~ "',sans-serif !important;}" %} - - {% endif %} + {% endif %} + {% endif %} {% if meta_description != "" %} @@ -145,96 +146,88 @@ {% endif %} {{- resolved_title -}} - - {# Ahrefs Site Verification Integration via Env or Config #} - {% set env_ahrefs_key = get_env(name="AHREFS_KEY", default="") %} - {% if env_ahrefs_key != "" %} - - {% elif config.extra.ahrefs_analytics_key is defined and config.extra.ahrefs_analytics_key != "" %} - + {# Ahrefs Integration (Consolidated) #} + {% set ahrefs_key = get_env(name="AHREFS_KEY", default="") %} + {% if ahrefs_key == "" and config.extra.ahrefs_analytics_key is defined %} + {% set ahrefs_key = config.extra.ahrefs_analytics_key %} {% endif %} - {# Google Analytics and Sentry are loaded client-side only after cookie consent. #} - {# Ahrefs Analytics: lightweight site-analytics script, no consent gate required. #} - {% set env_ahrefs_key = get_env(name="AHREFS_KEY", default="") %} - {% if env_ahrefs_key != "" %} - {% set ahrefs_key = env_ahrefs_key %} - {% elif config.extra.ahrefs_analytics_key is defined and config.extra.ahrefs_analytics_key != "" %} - {% set ahrefs_key = config.extra.ahrefs_analytics_key %} - {% endif %} - {% if ahrefs_key is defined and ahrefs_key != "" %} - + function schedule(){ + if ("requestIdleCallback" in window) { + requestIdleCallback(load, { timeout: 3000 }); + } else { + setTimeout(load, 1500); + } + } + if (document.readyState === 'complete') schedule(); + else window.addEventListener('load', schedule, {once:true}); + })(); + {% endif %} - {{ macros_seo::meta_tags(config=config, current_url=current_url, resolved_title=resolved_title, resolved_description=resolved_description, resolved_meta_type=resolved_meta_type, page=page | default(value=false)) }} - {{ macros_seo::website_schema(config=config) }} + {{ macros_seo::meta_tags(config=config, current_url=current_url, resolved_title=resolved_title, resolved_description=resolved_description, resolved_meta_type=resolved_meta_type, page=page | default(value=false)) }} + {{ macros_seo::website_schema(config=config) }} - + - {% if config.generate_feeds %} - - {% endif %} + {% if config.generate_feeds %} + + {% endif %} - {# Favicon configuration #} - {# Default path is /icons/ for all favicon files #} - {# Users can override individual paths in [extra.favicon] section #} - {% if config.extra.favicon is defined %} - {% set favicon_base = config.extra.favicon.base_path | default(value="/icons/") %} - {% set favicon_16x16 = config.extra.favicon.favicon_16x16 | default(value=favicon_base ~ "favicon-16x16-transparent.png") %} - {% set favicon_32x32 = config.extra.favicon.favicon_32x32 | default(value=favicon_base ~ "favicon-32x32-transparent.png") %} - {% set favicon_96x96 = config.extra.favicon.favicon_96x96 | default(value=favicon_base ~ "favicon-96x96-transparent.png") %} - {% set favicon_svg = config.extra.favicon.favicon_svg | default(value=favicon_base ~ "favicon.svg") %} - {% set favicon_ico = config.extra.favicon.favicon_ico | default(value=favicon_base ~ "favicon-transparent.ico") %} - {% set apple_touch_icon = config.extra.favicon.apple_touch_icon | default(value=favicon_base ~ "apple-touch-icon-180x180-transparent.png") %} - {% set site_webmanifest = config.extra.favicon.site_webmanifest | default(value=favicon_base ~ "site.webmanifest") %} - {% else %} - {% set favicon_base = "/icons/" %} - {% set favicon_16x16 = favicon_base ~ "favicon-16x16-transparent.png" %} - {% set favicon_32x32 = favicon_base ~ "favicon-32x32-transparent.png" %} - {% set favicon_96x96 = favicon_base ~ "favicon-96x96-transparent.png" %} - {% set favicon_svg = favicon_base ~ "favicon.svg" %} - {% set favicon_ico = favicon_base ~ "favicon-transparent.ico" %} - {% set apple_touch_icon = favicon_base ~ "apple-touch-icon-180x180-transparent.png" %} - {% set site_webmanifest = favicon_base ~ "site.webmanifest" %} - {% endif %} - - - - - - - - - + {# Favicon configuration #} + {% if config.extra.favicon is defined %} + {% set favicon_base = config.extra.favicon.base_path | default(value="/icons/") %} + {% set favicon_16x16 = config.extra.favicon.favicon_16x16 | default(value=favicon_base ~ "favicon-16x16-transparent.png") %} + {% set favicon_32x32 = config.extra.favicon.favicon_32x32 | default(value=favicon_base ~ "favicon-32x32-transparent.png") %} + {% set favicon_96x96 = config.extra.favicon.favicon_96x96 | default(value=favicon_base ~ "favicon-96x96-transparent.png") %} + {% set favicon_svg = config.extra.favicon.favicon_svg | default(value=favicon_base ~ "favicon.svg") %} + {% set favicon_ico = config.extra.favicon.favicon_ico | default(value=favicon_base ~ "favicon-transparent.ico") %} + {% set apple_touch_icon = config.extra.favicon.apple_touch_icon | default(value=favicon_base ~ "apple-touch-icon-180x180-transparent.png") %} + {% set site_webmanifest = config.extra.favicon.site_webmanifest | default(value=favicon_base ~ "site.webmanifest") %} + {% else %} + {% set favicon_base = "/icons/" %} + {% set favicon_16x16 = favicon_base ~ "favicon-16x16-transparent.png" %} + {% set favicon_32x32 = favicon_base ~ "favicon-32x32-transparent.png" %} + {% set favicon_96x96 = favicon_base ~ "favicon-96x96-transparent.png" %} + {% set favicon_svg = favicon_base ~ "favicon.svg" %} + {% set favicon_ico = favicon_base ~ "favicon-transparent.ico" %} + {% set apple_touch_icon = favicon_base ~ "apple-touch-icon-180x180-transparent.png" %} + {% set site_webmanifest = favicon_base ~ "site.webmanifest" %} + {% endif %} + + + + + + + + + - - + + + + data-katex-css="{{ get_url(path="css/katex.min.css") | safe }}" + data-sw-path="{{ get_url(path="sw.js") | safe }}"> {% endmacro head %} \ No newline at end of file diff --git a/templates/offline.html b/templates/offline.html index 6a43451..03cc08c 100644 --- a/templates/offline.html +++ b/templates/offline.html @@ -1,12 +1,33 @@ -{% extends "page.html" %} +{% extends "base.html" %} {% import "macros/nav.html" as macros_nav %} +{# Offline page — extends base.html directly (like 404.html) to force the rail layout. + This ensures _force_rail = true, which sets use_fit_shell = true for consistent width. #} + +{# Force the shell into the fitted layout so offline matches site width/state #} +{% set shell_fit = true %} + +{% block extra_head %} + +{% endblock extra_head %} + +{% block content %} +
    +
    +

    Offline

    +

    You appear to be offline.

    +
    +
    + +

    Your browser has lost connection to the internet. Check your network and try reloading the page.

    +

    Waiting for connection

    +{% endblock content %} + {% block prev_link %} {{ macros_nav::render_button(url="/", title="Home", subtitle="Back to", direction="prev") }} {% endblock prev_link %} -{% block next_link %} -{% endblock next_link %} +{% block next_link %}{% endblock next_link %} {% block js_body %} {{ super() }}