Add page-specific JavaScript support

Update documentation for new JS variables and rendering pipeline

Add script.js file support to content directories

Implement cache-busting for JavaScript files

Update static file serving to include JavaScript files

Document page-specific script loading in base.php

docs/04-development/02-content-system.md

@@ -126,6 +126,12 @@ Checks extensions in `COVER_IMAGE_EXTENSIONS` order: `jpg`, `jpeg`, `png`, `webp
 
 Returns `['url' => string, 'hash' => string]` or null. Hash is MD5 of file content for cache busting.
 
+## Page-Specific JavaScript
+
+**`findPageJs(string $dirPath, string $contentDir): ?array`** — Checks for `script.js` in content directory.
+
+Returns `['url' => string, 'hash' => string]` or null. Hash is MD5 of file content for cache busting. The script is loaded with the `defer` attribute in `base.php`, placed before `</body>` for non-blocking progressive enhancement.
+
 ## Meta Description Extraction
 
 **`extractMetaDescription(string $dirPath, ?array $metadata): ?string`**

docs/04-development/06-templates.md

@@ -59,6 +59,8 @@ Variables are injected via `extract()` — each array key becomes a local variab
 | `$homeLabel` | string | yes | Home link text |
 | `$pageCssUrl` | ?string | no | Page-specific CSS URL |
 | `$pageCssHash` | ?string | no | CSS cache-bust hash |
+| `$pageJsUrl` | ?string | no | Page-specific JS URL |
+| `$pageJsHash` | ?string | no | JS cache-bust hash |
 | `$feedUrl` | ?string | no | Atom feed URL (only on lists with `feed = true`) |
 | `$currentLang` | string | plugin | Language code (from languages plugin) |
 | `$langPrefix` | string | plugin | URL language prefix |

docs/04-development/07-rendering.md

@@ -23,7 +23,7 @@ Used for both frontpage and page views:
 1. Load metadata for `$pageDir`
 2. Load page plugins (from metadata `plugins` field)
 3. Render all content files, concatenate HTML
-4. Compute: `$pageTitle`, `$metaDescription`, `$pageCssUrl`/`$pageCssHash`, `$socialImageUrl`
+4. Compute: `$pageTitle`, `$metaDescription`, `$pageCssUrl`/`$pageCssHash`, `$pageJsUrl`/`$pageJsHash`, `$socialImageUrl`
 5. Fire `Hook::TEMPLATE_VARS` with all variables
 6. `extract()` variables → render `page.php` → capture output as `$content`
 7. Render `base.php` with `$content` + base variables
@@ -37,12 +37,12 @@ Handled directly in `router.php` (not a separate function):
 2. Load metadata, check `hide_list`
 3. Select list template from `page_template` metadata
 4. Call `buildListItems()` from `helpers.php` (builds + sorts items)
-5. Store `pageTitle`, `metaDescription`, `pageCssUrl`, `pageCssHash`, `feedUrl` on context
+5. Store `pageTitle`, `metaDescription`, `pageCssUrl`, `pageCssHash`, `pageJsUrl`, `pageJsHash`, `feedUrl` on context
 6. Fire `Hook::TEMPLATE_VARS`
 7. Render list template → capture as `$content`
 8. Pass to `renderTemplate()` which renders `base.php`
 
-**`renderTemplate(Context $ctx, string $content, int $statusCode = 200): void`** — Wraps content in base template. Used for list views and error pages. Reads `pageTitle`, `metaDescription`, `pageCssUrl`, `pageCssHash`, and `feedUrl` from the context object (set by the list case in `router.php`). For error pages, these context keys are unset, so base.php receives nulls.
+**`renderTemplate(Context $ctx, string $content, int $statusCode = 200): void`** — Wraps content in base template. Used for list views and error pages. Reads `pageTitle`, `metaDescription`, `pageCssUrl`, `pageCssHash`, `pageJsUrl`, `pageJsHash`, and `feedUrl` from the context object (set by the list case in `router.php`). For error pages, these context keys are unset, so base.php receives nulls.
 
 ## Atom Feed Rendering
 
@@ -79,9 +79,9 @@ setCachedMarkdown(string $filePath, string $html, string $langPrefix = ''): void
 
 Before content routing, the router serves static files from content directory with an explicit MIME type allowlist:
 
-`css`, `jpg`, `jpeg`, `png`, `gif`, `webp`, `svg`, `pdf`, `woff`, `woff2`, `ttf`, `otf`
+`css`, `jpg`, `jpeg`, `png`, `gif`, `webp`, `svg`, `pdf`, `woff`, `woff2`, `ttf`, `otf`, `js`
 
-Files not in this list are not served as static assets. Notably, `.js` files are excluded — JavaScript must be placed in `custom/assets/` to be served (at the document root URL), or linked from an external source.
+Files not in this list are not served as static assets.
 
 ### Custom Assets (router.php)
 
@@ -100,9 +100,9 @@ Files in `custom/assets/` are served at the document root URL. Example: `custom/
 
 MIME types resolved from extension map, falling back to `mime_content_type()`.
 
-## CSS Cache Busting
+## CSS and JS Cache Busting
 
-Page-specific CSS gets an MD5 hash appended: `?v={hash}`. Computed by `findPageCss()`. The default theme's CSS is linked directly without hash (uses browser caching).
+Page-specific CSS and JS get an MD5 hash appended: `?v={hash}`. Computed by `findPageCss()` and `findPageJs()` respectively. The default theme's CSS is linked directly without hash (uses browser caching).
 
 ## Parsedown