docula 1.13.0 → 2.0.0

package/README.md

@@ -56,7 +56,7 @@ You can build Docula as a standalone binary that runs without Node.js installed.
 
 ## Building the Binary
 
-Requires Node.js >= 20 to build (the resulting binary does not need Node.js to run).
+Requires Node.js >= 25.7.0 to build (the resulting binary does not need Node.js to run). The build uses [tsdown's `exe` option](https://tsdown.dev/options/exe), which wraps Node.js's [Single Executable Applications](https://nodejs.org/api/single-executable-applications.html) feature added in Node 25.7.
 
 ```bash
 pnpm install
@@ -69,7 +69,7 @@ This produces a platform-specific binary at `dist/docula` (or `dist/docula.exe`
 
 1. Embeds all built-in templates (modern, classic) into the bundle as base64
 2. Bundles all source code and dependencies into a single CJS file via [tsdown](https://tsdown.dev/)
-3. Uses tsdown's built-in `exe` option to create a Node.js SEA binary (blob generation, injection, and code signing are handled automatically)
+3. Uses tsdown's built-in `exe` option to create a Node.js SEA binary — blob generation, injection, and (on macOS hosts) ad-hoc code signing are handled automatically
 
 ## Testing the Binary
 
@@ -91,7 +91,7 @@ After building, test it locally:
 
 ## Cross-Platform Binaries
 
-Node.js SEA cannot cross-compile — the binary matches the OS and architecture it was built on. The CI workflow (`.github/workflows/build-binaries.yaml`) builds for all platforms using a matrix strategy:
+The CI workflow (`.github/workflows/build-binaries.yaml`) builds each platform natively on its own runner. Native builds avoid the cross-compile signing pitfall on Apple Silicon, where unsigned Mach-O binaries are killed on launch.
 
 | Platform | Runner | Artifact |
 |---|---|---|

package/dist/docula.d.ts

@@ -83,6 +83,7 @@ type ApiOperation = {
   id: string;
   method: string;
   methodUpper: string;
+  methodShort: string;
   path: string;
   summary: string;
   description: string;
@@ -214,6 +215,7 @@ type DoculaData = {
   changelogUrl: string;
   editPageUrl?: string;
   openGraph?: DoculaOpenGraph;
+  faviconUrl?: string;
 };
 type DoculaTemplates = {
   home: string;
@@ -448,6 +450,7 @@ declare class DoculaBuilder {
   private readonly _console;
   private readonly _hash;
   onReleaseChangelog?: (entries: DoculaChangelogEntry[], console: DoculaConsole) => Promise<DoculaChangelogEntry[]> | DoculaChangelogEntry[];
+  onAutoReadme?: (content: string, sourcePath: string, console: DoculaConsole) => Promise<string> | string;
   get console(): DoculaConsole;
   constructor(options?: DoculaBuilderOptions, engineOptions?: any);
   get options(): DoculaOptions;

package/dist/docula.js

@@ -11,8 +11,9 @@ import { Writr, Writr as Writr$1 } from "writr";
 import { blue, bold, cyan, dim, gray, green, magenta, red, white, yellow } from "colorette";
 import { CacheableNet } from "@cacheable/net";
 import os from "node:os";
+import sea from "node:sea";
 //#region package.json
-var version = "1.13.0";
+var version = "2.0.0";
 var package_default = {
 	name: "docula",
 	version,
@@ -27,12 +28,12 @@ var package_default = {
 		"url": "git+https://github.com/jaredwray/docula.git"
 	},
 	author: "Jared Wray <me@jaredwray.com>",
-	engines: { "node": ">=20" },
+	engines: { "node": "^22.18.0 || >=24.0.0" },
 	license: "MIT",
 	scripts: {
 		"clean": "rimraf ./dist ./coverage ./node_modules ./package-lock.json ./yarn.lock ./pnpm-lock.yaml ./site/dist",
 		"build": "pnpm generate-init-file && tsdown",
-		"build:binary": "pnpm generate-init-file && pnpm generate-embedded-templates && tsdown --config tsdown.config.binary.ts && tsx scripts/build-sea.ts",
+		"build:binary": "pnpm generate-init-file && pnpm generate-embedded-templates && tsdown --config tsdown.config.binary.ts",
 		"generate-embedded-templates": "tsx scripts/generate-embedded-templates.ts",
 		"lint": "biome check --write --error-on-warnings",
 		"lint:ci": "biome check --error-on-warnings",
@@ -69,42 +70,39 @@ var package_default = {
 	],
 	bin: { "docula": "./bin/docula.js" },
 	dependencies: {
-		"@ai-sdk/anthropic": "^3.0.63",
-		"@ai-sdk/google": "^3.0.52",
-		"@ai-sdk/openai": "^3.0.47",
-		"@cacheable/net": "^2.0.6",
-		"ai": "^6.0.134",
+		"@ai-sdk/anthropic": "^3.0.77",
+		"@ai-sdk/google": "^3.0.72",
+		"@ai-sdk/openai": "^3.0.63",
+		"@cacheable/net": "^2.0.7",
+		"ai": "^6.0.178",
 		"colorette": "^2.0.20",
-		"ecto": "^4.8.3",
-		"feed": "^5.2.0",
-		"hashery": "^1.5.1",
-		"jiti": "^2.6.1",
+		"ecto": "^4.8.5",
+		"hashery": "^2.0.0",
+		"jiti": "^2.7.0",
 		"serve-handler": "^6.1.7",
 		"update-notifier": "^7.3.1",
-		"writr": "^6.1.0"
+		"writr": "^6.1.2"
 	},
 	devDependencies: {
-		"@biomejs/biome": "^2.4.8",
-		"@playwright/test": "^1.58.2",
-		"@types/express": "^5.0.6",
-		"@types/js-yaml": "^4.0.9",
-		"@types/node": "^25.5.0",
+		"@biomejs/biome": "^2.4.15",
+		"@playwright/test": "^1.60.0",
+		"@types/node": "^24.12.4",
 		"@types/serve-handler": "^6.1.4",
 		"@types/update-notifier": "^6.0.8",
-		"@vitest/coverage-v8": "^4.1.0",
-		"dotenv": "^17.3.1",
-		"postject": "1.0.0-alpha.6",
+		"@vitest/coverage-v8": "^4.1.6",
+		"dotenv": "^17.4.2",
 		"rimraf": "^6.1.3",
-		"tsdown": "^0.21.7",
+		"tsdown": "^0.22.0",
 		"tsx": "^4.21.0",
-		"typescript": "^5.9.3",
-		"vitest": "^4.1.0"
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.6"
 	},
 	files: [
 		"dist",
 		"templates",
 		"bin"
-	]
+	],
+	packageManager: "pnpm@11.1.3+sha512.c85357fe17ca12dd23dd7071822666dfd7e3cb76fe214e3370b5ea2fb34f2a231185509b63e717f3cd0acb38dd3f8d82bcd5e8172400ae678b70ea4fbed0896d"
 };
 //#endregion
 //#region src/builder-ai.ts
@@ -121,15 +119,15 @@ async function createAIModel(ai) {
 		switch (ai.provider) {
 			case "anthropic": {
 				const { createAnthropic } = await import("@ai-sdk/anthropic");
-				return createAnthropic({ apiKey: ai.apiKey })(ai.model ?? "claude-haiku-4-5");
+				return createAnthropic(ai.apiKey ? { apiKey: ai.apiKey } : {})(ai.model || "claude-haiku-4-5");
 			}
 			case "openai": {
 				const { createOpenAI } = await import("@ai-sdk/openai");
-				return createOpenAI({ apiKey: ai.apiKey })(ai.model ?? "gpt-4o-mini-latest");
+				return createOpenAI(ai.apiKey ? { apiKey: ai.apiKey } : {})(ai.model || "gpt-4o-mini");
 			}
 			case "google": {
 				const { createGoogleGenerativeAI } = await import("@ai-sdk/google");
-				return createGoogleGenerativeAI({ apiKey: ai.apiKey })(ai.model ?? "gemini-2.5-flash-lite");
+				return createGoogleGenerativeAI(ai.apiKey ? { apiKey: ai.apiKey } : {})(ai.model || "gemini-2.5-flash-lite");
 			}
 			default: return;
 		}
@@ -379,10 +377,13 @@ function parseOpenApiSpec(specJson) {
 			const requestBody = extractRequestBody(operation, spec);
 			const responses = extractResponses(operation, spec);
 			const codeExamples = generateCodeExamples(method, pathStr, servers.length > 0 ? servers[0].url : "", parameters, requestBody);
+			const operationId = operation.operationId ?? `${method}-${pathStr.replaceAll(/[^a-zA-Z0-9]/g, "-")}`;
+			const methodUpper = method.toUpperCase();
 			const apiOperation = {
-				id: slugify(operation.operationId ?? `${method}-${pathStr.replaceAll(/[^a-zA-Z0-9]/g, "-")}`),
+				id: slugify(operationId),
 				method,
-				methodUpper: method.toUpperCase(),
+				methodUpper,
+				methodShort: methodUpper === "DELETE" ? "DEL" : methodUpper === "OPTIONS" ? "OPT" : methodUpper,
 				path: pathStr,
 				summary: operation.summary ?? "",
 				description: operation.description ?? "",
@@ -597,6 +598,7 @@ function extractResponses(operation, spec) {
 		responses.push({
 			statusCode,
 			statusClass: getStatusClass(statusCode),
+			/* v8 ignore next */
 			description: response.description ?? "",
 			contentType,
 			schemaProperties,
@@ -1093,6 +1095,22 @@ function hashFile(hash, filePath) {
 	const content = fs.readFileSync(filePath);
 	return hash.toHashSync(content);
 }
+function tryHashFile(hash, filePath) {
+	try {
+		return hashFile(hash, filePath);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		/* v8 ignore next 2 -- @preserve */
+		throw error;
+	}
+}
+function hashConfigFile(hash, sitePath) {
+	for (const name of ["docula.config.ts", "docula.config.mjs"]) {
+		const configPath = path.join(sitePath, name);
+		if (fs.existsSync(configPath)) return hashFile(hash, configPath);
+	}
+	return "";
+}
 function hashOptions(hash, options) {
 	const relevant = {
 		siteUrl: options.siteUrl,
@@ -1119,19 +1137,29 @@ function hashOptions(hash, options) {
 		ai: options.ai,
 		googleTagManager: options.googleTagManager
 	};
-	return hash.toHashSync(JSON.stringify(relevant));
+	const optionsHash = hash.toHashSync(JSON.stringify(relevant));
+	const configHash = hashConfigFile(hash, options.sitePath);
+	return hash.toHashSync(`${optionsHash}:${configHash}`);
 }
 function hashTemplateDirectory(hash, templatePath) {
 	/* v8 ignore next 3 -- @preserve */
 	if (!fs.existsSync(templatePath)) return "";
-	const hashes = listFilesRecursive(templatePath).map((f) => hashFile(hash, path.join(templatePath, f)));
+	const files = listFilesRecursive(templatePath);
+	const hashes = [];
+	for (const f of files) {
+		const fileHash = tryHashFile(hash, path.join(templatePath, f));
+		if (fileHash !== void 0) hashes.push(fileHash);
+	}
 	return hash.toHashSync(hashes.join(""));
 }
 function hashSourceFiles(hash, dir) {
 	const hashes = {};
 	if (!fs.existsSync(dir)) return hashes;
 	const files = listFilesRecursive(dir);
-	for (const file of files) hashes[file] = hashFile(hash, path.join(dir, file));
+	for (const file of files) {
+		const fileHash = tryHashFile(hash, path.join(dir, file));
+		if (fileHash !== void 0) hashes[file] = fileHash;
+	}
 	return hashes;
 }
 function recordsEqual(a, b) {
@@ -1145,6 +1173,7 @@ function hasAssetsChanged(hash, sitePath, previousAssets, autoReadme) {
 	for (const file of [
 		"favicon.ico",
 		"logo.svg",
+		"logo.png",
 		"logo_horizontal.png",
 		"variables.css",
 		"api/swagger.json",
@@ -2669,12 +2698,7 @@ var DoculaOptions = class {
 * Returns true when running as a single-executable application (SEA).
 */
 function isSEA() {
-	try {
-		return Boolean(process.sea);
-	} catch {
-		/* v8 ignore next -- @preserve */
-		return false;
-	}
+	return sea.isSea();
 }
 /**
 * Returns the deterministic temp directory path for extracted templates.
@@ -2739,6 +2763,7 @@ var DoculaBuilder = class {
 	_console;
 	_hash = new Hashery();
 	onReleaseChangelog;
+	onAutoReadme;
 	get console() {
 		return this._console;
 	}
@@ -2804,6 +2829,12 @@ var DoculaBuilder = class {
 			editPageUrl: this.options.editPageUrl,
 			openGraph: this.options.openGraph
 		};
+		const resolvedFavicon = [
+			"favicon.ico",
+			"logo.svg",
+			"logo.png"
+		].find((file) => fs.existsSync(path.join(this.options.sitePath, file)));
+		if (resolvedFavicon) doculaData.faviconUrl = buildUrlPath(this.options.baseUrl, resolvedFavicon);
 		if (siteReadmeExists) currentAssetHashes["README.md"] = hashFile(this._hash, path.join(this.options.sitePath, "README.md"));
 		else if (autoReadmeResult) currentAssetHashes.__autoReadme = hashFile(this._hash, autoReadmeResult.sourcePath);
 		if (Array.isArray(this.options.openApiUrl)) doculaData.openApiSpecs = this.options.openApiUrl.map((spec) => ({
@@ -2939,6 +2970,10 @@ var DoculaBuilder = class {
 			await fs.promises.copyFile(`${siteRelativePath}/logo.svg`, `${this.options.output}/logo.svg`);
 			this._console.fileCopied("logo.svg");
 		}
+		if (!hashAssetAndCheckSkip(this._hash, path.join(siteRelativePath, "logo.png"), path.join(this.options.output, "logo.png"), "logo.png", previousAssets, currentAssetHashes)) {
+			await fs.promises.copyFile(path.join(siteRelativePath, "logo.png"), path.join(this.options.output, "logo.png"));
+			this._console.fileCopied("logo.png");
+		}
 		if (!hashAssetAndCheckSkip(this._hash, `${siteRelativePath}/logo_horizontal.png`, `${this.options.output}/logo_horizontal.png`, "logo_horizontal.png", previousAssets, currentAssetHashes)) {
 			await fs.promises.copyFile(`${siteRelativePath}/logo_horizontal.png`, `${this.options.output}/logo_horizontal.png`);
 			this._console.fileCopied("logo_horizontal.png");
@@ -3014,9 +3049,16 @@ var DoculaBuilder = class {
 				if (packageJson.name && typeof packageJson.name === "string") readmeContent = `# ${packageJson.name}\n\n${readmeContent}`;
 			} catch {}
 		}
+		let content = readmeContent;
+		if (this.onAutoReadme) try {
+			content = await this.onAutoReadme(content, cwdReadmePath, this._console);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			this._console.error(`onAutoReadme error: ${message}`);
+		}
 		return {
 			sourcePath: cwdReadmePath,
-			content: readmeContent
+			content
 		};
 	}
 	async getGithubData(githubPath) {
@@ -3396,6 +3438,8 @@ var Docula = class {
 		const builder = new DoculaBuilder(Object.assign(this.options, { console: this._console }));
 		/* v8 ignore next 4 -- @preserve */
 		if (this._configFileModule.onReleaseChangelog) builder.onReleaseChangelog = this._configFileModule.onReleaseChangelog;
+		/* v8 ignore next 4 -- @preserve */
+		if (this._configFileModule.onAutoReadme) builder.onAutoReadme = this._configFileModule.onAutoReadme;
 		await builder.build();
 		return builder;
 	}
@@ -3496,12 +3540,16 @@ var Docula = class {
 			}
 			else {
 				const { createJiti } = await import("jiti");
-				this._configFileModule = await createJiti(import.meta.url, { interopDefault: true }).import(absolutePath);
+				const jiti = createJiti(import.meta.url, { interopDefault: true });
+				this._configFileModule = await jiti.import(absolutePath);
 			}
 			return;
 		}
 		/* v8 ignore next -- @preserve */
-		if (fs.existsSync(mjsConfigFile)) this._configFileModule = await import(pathToFileURL(path.resolve(mjsConfigFile)).href);
+		if (fs.existsSync(mjsConfigFile)) {
+			const absolutePath = path.resolve(mjsConfigFile);
+			this._configFileModule = await import(pathToFileURL(absolutePath).href);
+		}
 	}
 	/**
 	* Watch the site path for file changes and rebuild on change

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.13.0",
+  "version": "2.0.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -17,7 +17,7 @@
   },
   "author": "Jared Wray <me@jaredwray.com>",
   "engines": {
-    "node": ">=20"
+    "node": "^22.18.0 || >=24.0.0"
   },
   "license": "MIT",
   "keywords": [
@@ -40,36 +40,32 @@
     "docula": "./bin/docula.js"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.63",
-    "@ai-sdk/google": "^3.0.52",
-    "@ai-sdk/openai": "^3.0.47",
-    "@cacheable/net": "^2.0.6",
-    "ai": "^6.0.134",
+    "@ai-sdk/anthropic": "^3.0.77",
+    "@ai-sdk/google": "^3.0.72",
+    "@ai-sdk/openai": "^3.0.63",
+    "@cacheable/net": "^2.0.7",
+    "ai": "^6.0.178",
     "colorette": "^2.0.20",
-    "ecto": "^4.8.3",
-    "feed": "^5.2.0",
-    "hashery": "^1.5.1",
-    "jiti": "^2.6.1",
+    "ecto": "^4.8.5",
+    "hashery": "^2.0.0",
+    "jiti": "^2.7.0",
     "serve-handler": "^6.1.7",
     "update-notifier": "^7.3.1",
-    "writr": "^6.1.0"
+    "writr": "^6.1.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.8",
-    "@playwright/test": "^1.58.2",
-    "@types/express": "^5.0.6",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
+    "@biomejs/biome": "^2.4.15",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^24.12.4",
     "@types/serve-handler": "^6.1.4",
     "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.1.0",
-    "dotenv": "^17.3.1",
-    "postject": "1.0.0-alpha.6",
+    "@vitest/coverage-v8": "^4.1.6",
+    "dotenv": "^17.4.2",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.21.7",
+    "tsdown": "^0.22.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "files": [
     "dist",
@@ -79,7 +75,7 @@
   "scripts": {
     "clean": "rimraf ./dist ./coverage ./node_modules ./package-lock.json ./yarn.lock ./pnpm-lock.yaml ./site/dist",
     "build": "pnpm generate-init-file && tsdown",
-    "build:binary": "pnpm generate-init-file && pnpm generate-embedded-templates && tsdown --config tsdown.config.binary.ts && tsx scripts/build-sea.ts",
+    "build:binary": "pnpm generate-init-file && pnpm generate-embedded-templates && tsdown --config tsdown.config.binary.ts",
     "generate-embedded-templates": "tsx scripts/generate-embedded-templates.ts",
     "lint": "biome check --write --error-on-warnings",
     "lint:ci": "biome check --error-on-warnings",

package/templates/classic/includes/header.hbs

@@ -31,4 +31,4 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
   rel="stylesheet"
 />
 <link rel="stylesheet" href="/css/highlight/styles/base16/dracula.min.css" />
-<link rel="icon" href="/favicon.ico" />
+{{#if faviconUrl}}<link rel="icon" href="{{faviconUrl}}" />{{/if}}

package/templates/modern/api.hbs

@@ -39,8 +39,8 @@
         <div class="api-sidebar__group-items">
           {{#each this.operations}}
           <a href="#{{this.id}}" class="api-sidebar__item" data-method="{{this.method}}" data-path="{{this.path}}">
-            <span class="method-badge method-badge--{{this.method}}">{{this.methodUpper}}</span>
             <span class="api-sidebar__item-path">{{this.path}}</span>
+            <span class="method-badge method-badge--{{this.method}}">{{this.methodShort}}</span>
           </a>
           {{/each}}
         </div>

package/templates/modern/css/api.css

@@ -100,17 +100,20 @@
 }
 
 .api-sidebar__group-items {
-  padding: 2px 0 8px 0;
+  padding: 4px 0 8px 12px;
+  margin-left: 10px;
+  border-left: 1px solid var(--border);
 }
 
 .api-sidebar__item {
   display: flex;
   align-items: center;
-  gap: 8px;
-  padding: 4px 10px;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 10px;
   font-size: 13px;
   border-radius: 4px;
-  color: var(--fg);
+  color: var(--muted-fg);
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -125,8 +128,23 @@
 }
 
 .api-sidebar__item-path {
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
+  color: var(--muted-fg);
+}
+
+.api-sidebar__item--active .api-sidebar__item-path {
+  color: var(--fg);
+}
+
+.api-sidebar__item .method-badge {
+  background: transparent;
+  padding: 0;
+  min-width: 0;
+  border-radius: 0;
+  font-size: 11px;
+  letter-spacing: 0.5px;
 }
 
 /* Method Badges */

package/templates/modern/css/styles.css

@@ -289,6 +289,44 @@ body {
   letter-spacing: 0.24px;
 }
 
+.nav-sidebar__title:has(.nav-sidebar__toggle) {
+  padding: 0;
+}
+
+.nav-sidebar__toggle {
+  all: unset;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  cursor: pointer;
+  padding: 0 8px 0 10px;
+  font: inherit;
+  color: inherit;
+  text-transform: inherit;
+  letter-spacing: inherit;
+}
+
+.nav-sidebar__toggle:focus-visible {
+  outline: 2px solid var(--accent, currentColor);
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+.nav-sidebar__chevron {
+  flex-shrink: 0;
+  transition: transform 150ms ease;
+}
+
+.nav-sidebar__section--collapsed .nav-sidebar__chevron {
+  transform: rotate(-90deg);
+}
+
+.nav-sidebar__section--collapsed .nav-sidebar__list {
+  display: none;
+}
+
 .nav-sidebar__list {
   margin-block: 2px;
 }
@@ -360,7 +398,7 @@ body {
 .copy-code-btn { position: absolute; top: 8px; right: 8px; padding: 4px; line-height: 0; border-radius: 4px; background: transparent; color: var(--muted); border: none; cursor: pointer; opacity: 0; transition: opacity 0.15s; }
 pre:hover .copy-code-btn { opacity: 1; }
 .copy-code-btn:hover { color: var(--fg); }
-.article__main img, .changelog-entry-body img { cursor: zoom-in; }
+.article__main img:not(a img), .changelog-entry-body img:not(a img) { cursor: zoom-in; }
 .lightbox-overlay { display: none; position: fixed; inset: 0; z-index: 200; background: rgba(0, 0, 0, 0.8); justify-content: center; align-items: center; cursor: pointer; }
 .lightbox-overlay--visible { display: flex !important; }
 .lightbox-overlay img { max-width: 90vw; max-height: 90vh; border-radius: 8px; box-shadow: 0 4px 24px rgba(0, 0, 0, 0.4); cursor: default; }

package/templates/modern/includes/header.hbs

@@ -22,7 +22,7 @@ j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
 <link rel="stylesheet" href="{{baseUrl}}/css/variables.css">
 <link rel="stylesheet" href="{{baseUrl}}/css/styles.css">
 <link rel="stylesheet" href="{{baseUrl}}/css/highlight/styles/base16/docula.css">
-<link rel="icon" href="{{baseUrl}}/favicon.ico">
+{{#if faviconUrl}}<link rel="icon" href="{{faviconUrl}}">{{/if}}
 <script>
   (function(){
     window.__doculaThemeKey = 'docula:theme:' + ({{#if siteUrl}}'{{siteUrl}}'{{else}}location.origin{{/if}}).replace(/^https?:\/\//, '');

package/templates/modern/includes/scripts.hbs

@@ -227,6 +227,44 @@
       }
     });
 
+    // Sidebar section collapse/expand
+    const SIDEBAR_STORAGE_KEY = 'docula:sidebar-sections';
+    const collapsibleSections = document.querySelectorAll('.nav-sidebar__section--collapsible');
+    if (collapsibleSections.length > 0) {
+      let storedSectionState = {};
+      try {
+        storedSectionState = JSON.parse(localStorage.getItem(SIDEBAR_STORAGE_KEY) || '{}');
+      } catch (e) { storedSectionState = {}; }
+
+      const setSectionOpen = (section, toggle, open) => {
+        toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+        section.classList.toggle('nav-sidebar__section--collapsed', !open);
+      };
+
+      collapsibleSections.forEach((section, idx) => {
+        const toggle = section.querySelector('.nav-sidebar__toggle');
+        const list = section.querySelector('.nav-sidebar__list');
+        if (!toggle || !list) return;
+        const listId = 'nav-sidebar-section-' + idx;
+        list.id = listId;
+        toggle.setAttribute('aria-controls', listId);
+
+        const key = 'section-' + idx;
+        const hasStored = Object.prototype.hasOwnProperty.call(storedSectionState, key);
+        const isOpen = hasStored ? !!storedSectionState[key] : true;
+        setSectionOpen(section, toggle, isOpen);
+
+        toggle.addEventListener('click', () => {
+          const next = toggle.getAttribute('aria-expanded') !== 'true';
+          setSectionOpen(section, toggle, next);
+          storedSectionState[key] = next;
+          try {
+            localStorage.setItem(SIDEBAR_STORAGE_KEY, JSON.stringify(storedSectionState));
+          } catch (e) { /* storage unavailable */ }
+        });
+      });
+    }
+
     // Active header nav link highlighting
     const navLinks = document.querySelectorAll('.header-bottom__item');
     navLinks.forEach((link) => {
@@ -282,6 +320,7 @@
     document.body.appendChild(lightboxOverlay);
 
     document.querySelectorAll('.article__main img, .changelog-entry-body img').forEach(function(img) {
+      if (img.closest('a')) return;
       img.addEventListener('click', function() {
         lightboxImg.src = img.src;
         lightboxOverlay.classList.add('lightbox-overlay--visible');

package/templates/modern/includes/sidebar.hbs

@@ -1,7 +1,12 @@
 {{#forEach sidebarItems}}
   {{#if children}}
-    <section class="nav-sidebar__section">
-      <h2 class="nav-sidebar__title">{{name}}</h2>
+    <section class="nav-sidebar__section nav-sidebar__section--collapsible">
+      <h2 class="nav-sidebar__title">
+        <button type="button" class="nav-sidebar__toggle" aria-expanded="true">
+          <span class="nav-sidebar__toggle-label">{{name}}</span>
+          <svg class="nav-sidebar__chevron" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="6 9 12 15 18 9"/></svg>
+        </button>
+      </h2>
       <ul class="nav-sidebar__list">
         {{#forEach children}}
         <li>