docula 1.14.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

@@ -215,6 +215,7 @@ type DoculaData = {
   changelogUrl: string;
   editPageUrl?: string;
   openGraph?: DoculaOpenGraph;
+  faviconUrl?: string;
 };
 type DoculaTemplates = {
   home: string;

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.14.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,39 +70,39 @@ var package_default = {
 	],
 	bin: { "docula": "./bin/docula.js" },
 	dependencies: {
-		"@ai-sdk/anthropic": "^3.0.69",
-		"@ai-sdk/google": "^3.0.63",
-		"@ai-sdk/openai": "^3.0.53",
+		"@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.164",
+		"ai": "^6.0.178",
 		"colorette": "^2.0.20",
-		"ecto": "^4.8.4",
+		"ecto": "^4.8.5",
 		"hashery": "^2.0.0",
-		"jiti": "^2.6.1",
+		"jiti": "^2.7.0",
 		"serve-handler": "^6.1.7",
 		"update-notifier": "^7.3.1",
-		"writr": "^6.1.1"
+		"writr": "^6.1.2"
 	},
 	devDependencies: {
-		"@biomejs/biome": "^2.4.12",
-		"@playwright/test": "^1.59.1",
-		"@types/node": "^25.6.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.4",
+		"@vitest/coverage-v8": "^4.1.6",
 		"dotenv": "^17.4.2",
-		"postject": "1.0.0-alpha.6",
 		"rimraf": "^6.1.3",
-		"tsdown": "^0.21.9",
+		"tsdown": "^0.22.0",
 		"tsx": "^4.21.0",
-		"typescript": "^6.0.2",
-		"vitest": "^4.1.4"
+		"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
@@ -118,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;
 		}
@@ -597,6 +598,7 @@ function extractResponses(operation, spec) {
 		responses.push({
 			statusCode,
 			statusClass: getStatusClass(statusCode),
+			/* v8 ignore next */
 			description: response.description ?? "",
 			contentType,
 			schemaProperties,
@@ -1171,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",
@@ -2695,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.
@@ -2831,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) => ({
@@ -2966,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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.14.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,33 +40,32 @@
     "docula": "./bin/docula.js"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.69",
-    "@ai-sdk/google": "^3.0.63",
-    "@ai-sdk/openai": "^3.0.53",
+    "@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.164",
+    "ai": "^6.0.178",
     "colorette": "^2.0.20",
-    "ecto": "^4.8.4",
+    "ecto": "^4.8.5",
     "hashery": "^2.0.0",
-    "jiti": "^2.6.1",
+    "jiti": "^2.7.0",
     "serve-handler": "^6.1.7",
     "update-notifier": "^7.3.1",
-    "writr": "^6.1.1"
+    "writr": "^6.1.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.12",
-    "@playwright/test": "^1.59.1",
-    "@types/node": "^25.6.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.4",
+    "@vitest/coverage-v8": "^4.1.6",
     "dotenv": "^17.4.2",
-    "postject": "1.0.0-alpha.6",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.21.9",
+    "tsdown": "^0.22.0",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "files": [
     "dist",
@@ -76,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/css/styles.css

@@ -398,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

@@ -236,10 +236,6 @@
         storedSectionState = JSON.parse(localStorage.getItem(SIDEBAR_STORAGE_KEY) || '{}');
       } catch (e) { storedSectionState = {}; }
 
-      const activeSidebarLink = document.querySelector('.nav-sidebar__item--active');
-      const activeSection = activeSidebarLink ? activeSidebarLink.closest('.nav-sidebar__section--collapsible') : null;
-      const defaultOpenSection = activeSection || collapsibleSections[0];
-
       const setSectionOpen = (section, toggle, open) => {
         toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
         section.classList.toggle('nav-sidebar__section--collapsed', !open);
@@ -255,7 +251,7 @@
 
         const key = 'section-' + idx;
         const hasStored = Object.prototype.hasOwnProperty.call(storedSectionState, key);
-        const isOpen = hasStored ? !!storedSectionState[key] : section === defaultOpenSection;
+        const isOpen = hasStored ? !!storedSectionState[key] : true;
         setSectionOpen(section, toggle, isOpen);
 
         toggle.addEventListener('click', () => {
@@ -324,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');