docula 1.12.0 → 1.14.0

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;
@@ -153,6 +154,10 @@ type DoculaChangelogEntry = {
   previewImage?: string;
   urlPath: string;
   lastModified: string;
+  description?: string;
+  keywords?: string[];
+  ogTitle?: string;
+  ogDescription?: string;
 };
 type DoculaData = {
   siteUrl: string;
@@ -175,6 +180,13 @@ type DoculaData = {
   openApiSpecs?: DoculaOpenApiSpecEntry[];
   changelogEntries?: DoculaChangelogEntry[];
   hasReadme?: boolean;
+  readmeContent?: string;
+  readmeMetadata?: {
+    description?: string;
+    keywords?: string[];
+    ogTitle?: string;
+    ogDescription?: string;
+  };
   themeMode?: string;
   cookieAuth?: {
     loginUrl: string;
@@ -271,7 +283,7 @@ type DoculaCacheOptions = {
 type DoculaAIOptions = {
   provider: string;
   model?: string;
-  apiKey: string;
+  apiKey?: string;
 };
 declare class DoculaOptions {
   /**
@@ -345,9 +357,10 @@ declare class DoculaOptions {
    */
   autoUpdateIgnores: boolean;
   /**
-   * When true, automatically copies the project root README.md into the site
-   * directory if one does not already exist. The package.json name field is
-   * used to prepend a title heading when the README lacks one.
+   * When true, automatically renders the project root README.md as the home
+   * page if no README exists in the site directory. The README is read in
+   * place and never copied into the site directory. The package.json name
+   * field is used to prepend a title heading when the README lacks one.
    */
   autoReadme: boolean;
   /**
@@ -436,12 +449,16 @@ 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;
   build(): Promise<void>;
   validateOptions(options: DoculaOptions): void;
-  autoReadme(): Promise<void>;
+  autoReadme(): Promise<{
+    sourcePath: string;
+    content: string;
+  } | undefined>;
   getGithubData(githubPath: string): Promise<GithubData>;
   getTemplates(templatePath: string, hasDocuments: boolean, hasChangelog?: boolean): Promise<DoculaTemplates>;
   getTemplateFile(path: string, name: string): Promise<string | undefined>;

package/dist/docula.js

@@ -12,7 +12,7 @@ import { blue, bold, cyan, dim, gray, green, magenta, red, white, yellow } from
 import { CacheableNet } from "@cacheable/net";
 import os from "node:os";
 //#region package.json
-var version = "1.12.0";
+var version = "1.14.0";
 var package_default = {
 	name: "docula",
 	version,
@@ -69,36 +69,33 @@ 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.69",
+		"@ai-sdk/google": "^3.0.63",
+		"@ai-sdk/openai": "^3.0.53",
+		"@cacheable/net": "^2.0.7",
+		"ai": "^6.0.164",
 		"colorette": "^2.0.20",
-		"ecto": "^4.8.3",
-		"feed": "^5.2.0",
-		"hashery": "^1.5.1",
+		"ecto": "^4.8.4",
+		"hashery": "^2.0.0",
 		"jiti": "^2.6.1",
 		"serve-handler": "^6.1.7",
 		"update-notifier": "^7.3.1",
-		"writr": "^6.1.0"
+		"writr": "^6.1.1"
 	},
 	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.12",
+		"@playwright/test": "^1.59.1",
+		"@types/node": "^25.6.0",
 		"@types/serve-handler": "^6.1.4",
 		"@types/update-notifier": "^6.0.8",
-		"@vitest/coverage-v8": "^4.1.0",
-		"dotenv": "^17.3.1",
+		"@vitest/coverage-v8": "^4.1.4",
+		"dotenv": "^17.4.2",
 		"postject": "1.0.0-alpha.6",
 		"rimraf": "^6.1.3",
-		"tsdown": "^0.21.7",
+		"tsdown": "^0.21.9",
 		"tsx": "^4.21.0",
-		"typescript": "^5.9.3",
-		"vitest": "^4.1.0"
+		"typescript": "^6.0.2",
+		"vitest": "^4.1.4"
 	},
 	files: [
 		"dist",
@@ -161,13 +158,13 @@ function saveAIMetadataCache(sitePath, cache) {
 * Check if a document needs AI enrichment for OG/meta fields.
 */
 function needsDocumentEnrichment(doc) {
-	return !doc.description || doc.keywords.length === 0 || !doc.ogTitle || !doc.ogDescription;
+	return !doc.description || doc.keywords.length === 0 || !doc.ogDescription;
 }
 /**
 * Check if a changelog entry needs AI enrichment.
 */
 function needsChangelogEnrichment(entry) {
-	return !entry.title || !entry.preview;
+	return !entry.preview || !entry.description || !entry.keywords?.length || !entry.ogDescription;
 }
 /**
 * Enrich documents with AI-generated metadata for OG/meta tags.
@@ -183,9 +180,13 @@ async function enrichDocuments(documents, model, hash, console, cache) {
 			const bodyHash = hash.toHashSync(doc.content);
 			const cached = cache[bodyHash];
 			if (cached) {
-				enriched[i] = applyMetadataToDocument(doc, cached);
-				logDocumentMetadata(console, doc.title || doc.documentPath, cached, true);
-				continue;
+				const applied = applyMetadataToDocument(doc, cached);
+				if (!needsDocumentEnrichment(applied)) {
+					enriched[i] = applied;
+					logDocumentMetadata(console, doc.title || doc.documentPath, cached, true);
+					continue;
+				}
+				delete cache[bodyHash];
 			}
 			if (doc.content.trim().length < 10) continue;
 			const metadata = await new Writr$1(doc.content, {
@@ -210,14 +211,19 @@ async function enrichChangelogEntries(entries, model, hash, console, cache) {
 	const enriched = [...entries];
 	for (let i = 0; i < enriched.length; i++) {
 		const entry = enriched[i];
+		/* v8 ignore next -- @preserve */
 		if (!needsChangelogEnrichment(entry)) continue;
 		try {
 			const bodyHash = hash.toHashSync(entry.content);
 			const cached = cache[bodyHash];
 			if (cached) {
-				enriched[i] = applyMetadataToChangelog(entry, cached);
-				logChangelogMetadata(console, entry.title || entry.slug, cached, true);
-				continue;
+				const applied = applyMetadataToChangelog(entry, cached);
+				if (!needsChangelogEnrichment(applied)) {
+					enriched[i] = applied;
+					logChangelogMetadata(console, entry.title || entry.slug, cached, true);
+					continue;
+				}
+				delete cache[bodyHash];
 			}
 			if (entry.content.trim().length < 10) continue;
 			const metadata = await new Writr$1(entry.content, {
@@ -235,6 +241,45 @@ async function enrichChangelogEntries(entries, model, hash, console, cache) {
 	return enriched;
 }
 /**
+* Enrich the site README with AI-generated metadata for OG/meta tags.
+* Accepts the README content directly (from doculaData.readmeContent or
+* by reading sitePath/README.md). Returns mapped metadata or undefined
+* if content is missing, too small, or enrichment fails.
+*/
+async function enrichReadme(content, model, hash, console, cache) {
+	if (!content) return;
+	try {
+		if (content.trim().length < 10) return;
+		const bodyHash = hash.toHashSync(content);
+		const cached = cache[bodyHash];
+		if (cached) {
+			logDocumentMetadata(console, "README", cached, true);
+			return {
+				description: cached.description,
+				keywords: cached.keywords,
+				ogTitle: cached.title,
+				ogDescription: cached.description
+			};
+		}
+		const metadata = await new Writr$1(content, {
+			...writrOptions$6,
+			ai: { model }
+		}).ai?.getMetadata();
+		if (!metadata) return;
+		cache[bodyHash] = metadata;
+		logDocumentMetadata(console, "README", metadata, false);
+		return {
+			description: metadata.description,
+			keywords: metadata.keywords,
+			ogTitle: metadata.title,
+			ogDescription: metadata.description
+		};
+	} catch (error) {
+		console.warn(`AI enrichment failed for README: ${error.message}`);
+		return;
+	}
+}
+/**
 * Log AI-generated metadata for a document.
 */
 function truncate(value, max = 60) {
@@ -248,7 +293,6 @@ function logDocumentMetadata(console, name, metadata, fromCache) {
 	console.info(`AI enriched: ${name}`);
 	if (metadata.description) console.log(white(`  description: ${truncate(metadata.description)}`));
 	if (metadata.keywords?.length) console.log(white(`  keywords: ${truncate(metadata.keywords.join(", "))}`));
-	if (metadata.title) console.log(white(`  ogTitle: ${truncate(metadata.title)}`));
 }
 /**
 * Log AI-generated metadata for a changelog entry.
@@ -259,8 +303,9 @@ function logChangelogMetadata(console, name, metadata, fromCache) {
 		return;
 	}
 	console.info(`AI enriched changelog: ${name}`);
-	if (metadata.title) console.log(white(`  title: ${truncate(metadata.title)}`));
 	if (metadata.preview || metadata.summary) console.log(white(`  preview: ${truncate(metadata.preview || metadata.summary || "")}`));
+	if (metadata.description) console.log(white(`  description: ${truncate(metadata.description)}`));
+	if (metadata.keywords?.length) console.log(white(`  keywords: ${truncate(metadata.keywords.join(", "))}`));
 }
 /**
 * Apply AI-generated metadata to a document, filling only missing fields.
@@ -270,7 +315,7 @@ function applyMetadataToDocument(doc, metadata) {
 		...doc,
 		description: doc.description || metadata.description || "",
 		keywords: doc.keywords.length > 0 ? doc.keywords : metadata.keywords ?? [],
-		ogTitle: doc.ogTitle ?? metadata.title,
+		ogTitle: doc.ogTitle ?? (doc.title || void 0),
 		ogDescription: doc.ogDescription ?? metadata.description
 	};
 }
@@ -280,8 +325,11 @@ function applyMetadataToDocument(doc, metadata) {
 function applyMetadataToChangelog(entry, metadata) {
 	return {
 		...entry,
-		title: entry.title || metadata.title || "",
-		preview: entry.preview || metadata.preview || metadata.summary || ""
+		preview: entry.preview || metadata.preview || metadata.summary || "",
+		description: entry.description || metadata.description || void 0,
+		keywords: entry.keywords?.length ? entry.keywords : metadata.keywords ?? [],
+		ogTitle: entry.ogTitle ?? (entry.title || void 0),
+		ogDescription: entry.ogDescription ?? metadata.description
 	};
 }
 //#endregion
@@ -328,10 +376,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 ?? "",
@@ -745,7 +796,7 @@ function resolveJsonLd(pageType, data, pageUrl, pageData) {
 				"@context": "https://schema.org",
 				"@type": "BlogPosting",
 				headline: pageData.title,
-				description: pageData?.preview ?? pageData?.description ?? "",
+				description: pageData?.description ?? pageData?.preview ?? "",
 				url,
 				publisher: {
 					"@type": "Organization",
@@ -754,6 +805,7 @@ function resolveJsonLd(pageType, data, pageUrl, pageData) {
 			};
 			if (pageData?.date) schema.datePublished = pageData.date;
 			if (pageData?.previewImage) schema.image = pageData.previewImage;
+			if (pageData?.keywords) schema.keywords = pageData.keywords;
 			break;
 	}
 	/* v8 ignore next 3 -- @preserve */
@@ -1041,6 +1093,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,
@@ -1067,19 +1135,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) {
@@ -1089,7 +1167,7 @@ function recordsEqual(a, b) {
 	for (const key of keysA) if (a[key] !== b[key]) return false;
 	return true;
 }
-function hasAssetsChanged(hash, sitePath, previousAssets) {
+function hasAssetsChanged(hash, sitePath, previousAssets, autoReadme) {
 	for (const file of [
 		"favicon.ico",
 		"logo.svg",
@@ -1104,6 +1182,14 @@ function hasAssetsChanged(hash, sitePath, previousAssets) {
 			if (previousAssets[file] !== fileHash) return true;
 		} else if (previousAssets[file]) return true;
 	}
+	const siteReadmeExists = fs.existsSync(path.join(sitePath, "README.md"));
+	if (autoReadme === true && !siteReadmeExists || previousAssets.__autoReadme !== void 0) {
+		const rootReadmePath = path.join(process.cwd(), "README.md");
+		if (fs.existsSync(rootReadmePath)) {
+			const currentRootHash = hashFile(hash, rootReadmePath);
+			if (previousAssets.__autoReadme !== currentRootHash) return true;
+		} else if (previousAssets.__autoReadme !== void 0) return true;
+	}
 	const publicPath = path.join(sitePath, "public");
 	if (fs.existsSync(publicPath)) {
 		const publicHashes = hashSourceFiles(hash, publicPath);
@@ -1254,6 +1340,10 @@ function parseChangelogEntry(filePath, options) {
 	});
 	const previewImage = matterData.previewImage;
 	const draft = matterData.draft === true;
+	const description = matterData.description || void 0;
+	const keywords = Array.isArray(matterData.keywords) ? matterData.keywords : void 0;
+	const ogTitle = matterData.ogTitle || void 0;
+	const ogDescription = matterData.ogDescription || void 0;
 	return {
 		title: matterData.title ?? fileName,
 		date: dateString,
@@ -1267,7 +1357,11 @@ function parseChangelogEntry(filePath, options) {
 		draft,
 		previewImage,
 		urlPath: `${buildUrlPath(options.baseUrl, options.changelogPath, slug)}/index.html`,
-		lastModified: fs.statSync(filePath).mtime.toISOString().split("T")[0]
+		lastModified: fs.statSync(filePath).mtime.toISOString().split("T")[0],
+		description,
+		keywords,
+		ogTitle,
+		ogDescription
 	};
 }
 function generateChangelogPreview(markdown, maxLength = 500, mdx = false) {
@@ -2427,9 +2521,10 @@ var DoculaOptions = class {
 	*/
 	autoUpdateIgnores = true;
 	/**
-	* When true, automatically copies the project root README.md into the site
-	* directory if one does not already exist. The package.json name field is
-	* used to prepend a title heading when the README lacks one.
+	* When true, automatically renders the project root README.md as the home
+	* page if no README exists in the site directory. The README is read in
+	* place and never copied into the site directory. The package.json name
+	* field is used to prepend a title heading when the README lacks one.
 	*/
 	autoReadme = true;
 	/**
@@ -2670,6 +2765,7 @@ var DoculaBuilder = class {
 	_console;
 	_hash = new Hashery();
 	onReleaseChangelog;
+	onAutoReadme;
 	get console() {
 		return this._console;
 	}
@@ -2697,14 +2793,16 @@ var DoculaBuilder = class {
 		const currentChangelogHashes = hashSourceFiles(this._hash, `${this.options.sitePath}/changelog`);
 		const currentAssetHashes = {};
 		if (validManifest && fs.existsSync(this.options.output) && validManifest.templateHash === currentTemplateHash && recordsEqual(validManifest.docs, currentDocHashes) && recordsEqual(validManifest.changelog, currentChangelogHashes)) {
-			if (!hasAssetsChanged(this._hash, this.options.sitePath, validManifest.assets)) {
+			if (!hasAssetsChanged(this._hash, this.options.sitePath, validManifest.assets, this.options.autoReadme)) {
 				this._console.success("No changes detected, skipping build");
 				return;
 			}
 		}
 		const cachedDocs = validManifest ? loadCachedDocuments(this.options.sitePath) : /* @__PURE__ */ new Map();
 		const cachedChangelog = validManifest ? loadCachedChangelog(this.options.sitePath) : /* @__PURE__ */ new Map();
-		await this.autoReadme();
+		await fs.promises.mkdir(this.options.sitePath, { recursive: true });
+		const autoReadmeResult = await this.autoReadme();
+		const siteReadmeExists = !autoReadmeResult && fs.existsSync(path.join(this.options.sitePath, "README.md"));
 		const doculaData = {
 			siteUrl: this.options.siteUrl,
 			siteTitle: this.options.siteTitle,
@@ -2714,7 +2812,8 @@ var DoculaBuilder = class {
 			output: this.options.output,
 			githubPath: this.options.githubPath,
 			sections: this.options.sections,
-			hasReadme: fs.existsSync(`${this.options.sitePath}/README.md`),
+			hasReadme: siteReadmeExists || autoReadmeResult !== void 0,
+			readmeContent: autoReadmeResult?.content,
 			themeMode: this.options.themeMode,
 			cookieAuth: this.options.cookieAuth,
 			headerLinks: this.options.headerLinks,
@@ -2732,8 +2831,8 @@ var DoculaBuilder = class {
 			editPageUrl: this.options.editPageUrl,
 			openGraph: this.options.openGraph
 		};
-		const readmePath = `${this.options.sitePath}/README.md`;
-		if (doculaData.hasReadme) currentAssetHashes["README.md"] = hashFile(this._hash, readmePath);
+		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) => ({
 			name: spec.name,
 			url: isRemoteUrl(spec.url) ? spec.url : buildUrlPath(this.options.apiPath, spec.url),
@@ -2797,7 +2896,7 @@ var DoculaBuilder = class {
 		});
 		doculaData.changelogEntries = allChangelogEntries;
 		doculaData.hasChangelog = allChangelogEntries.length > 0 && hasChangelogTemplate;
-		/* v8 ignore next 19 -- @preserve */
+		/* v8 ignore next 40 -- @preserve */
 		if (this._options.ai) {
 			const aiModel = await createAIModel(this._options.ai);
 			if (aiModel) {
@@ -2805,6 +2904,7 @@ var DoculaBuilder = class {
 				const aiCache = loadAIMetadataCache(this._options.sitePath);
 				doculaData.documents = await enrichDocuments(doculaData.documents, aiModel, this._hash, this._console, aiCache);
 				doculaData.changelogEntries = await enrichChangelogEntries(doculaData.changelogEntries, aiModel, this._hash, this._console, aiCache);
+				if (doculaData.hasReadme && !doculaData.hasDocuments) doculaData.readmeMetadata = await enrichReadme(doculaData.readmeContent ?? (siteReadmeExists ? fs.readFileSync(`${this._options.sitePath}/README.md`, "utf8") : void 0), aiModel, this._hash, this._console, aiCache);
 				saveAIMetadataCache(this._options.sitePath, aiCache);
 			}
 		}
@@ -2941,8 +3041,17 @@ var DoculaBuilder = class {
 				if (packageJson.name && typeof packageJson.name === "string") readmeContent = `# ${packageJson.name}\n\n${readmeContent}`;
 			} catch {}
 		}
-		await fs.promises.mkdir(this._options.sitePath, { recursive: true });
-		await fs.promises.writeFile(siteReadmePath, readmeContent, "utf8");
+		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
+		};
 	}
 	async getGithubData(githubPath) {
 		const paths = githubPath.split("/");
@@ -3016,11 +3125,14 @@ var DoculaBuilder = class {
 			let content;
 			if (!data.hasDocuments) content = await this.buildReadmeSection(data);
 			const announcement = await this.buildAnnouncementSection(data);
+			const readmeMeta = data.readmeMetadata;
 			const indexContent = await this._ecto.renderFromFile(indexTemplate, {
 				...data,
 				content,
 				announcement,
-				...this.resolveOpenGraphData(data, "/"),
+				description: readmeMeta?.description ?? data.siteDescription,
+				keywords: readmeMeta?.keywords,
+				...this.resolveOpenGraphData(data, "/", readmeMeta),
 				jsonLd: this.resolveJsonLd("home", data, "/")
 			}, data.templatePath);
 			await fs.promises.writeFile(indexPath, indexContent, "utf8");
@@ -3051,7 +3163,8 @@ var DoculaBuilder = class {
 	}
 	async buildReadmeSection(data) {
 		let htmlReadme = "";
-		if (fs.existsSync(`${data.sitePath}/README.md`)) htmlReadme = await new Writr$1(fs.readFileSync(`${data.sitePath}/README.md`, "utf8"), writrOptions).render();
+		if (data.readmeContent !== void 0) htmlReadme = await new Writr$1(data.readmeContent.replace(/^\s*#\s+[^\r\n]*[\r\n]*/, ""), writrOptions).render();
+		else if (fs.existsSync(`${data.sitePath}/README.md`)) htmlReadme = await new Writr$1(fs.readFileSync(`${data.sitePath}/README.md`, "utf8"), writrOptions).render();
 		return htmlReadme;
 	}
 	async buildAnnouncementSection(data) {
@@ -3317,6 +3430,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;
 	}
@@ -3417,12 +3532,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.12.0",
+  "version": "1.14.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",
@@ -40,36 +40,33 @@
     "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.69",
+    "@ai-sdk/google": "^3.0.63",
+    "@ai-sdk/openai": "^3.0.53",
+    "@cacheable/net": "^2.0.7",
+    "ai": "^6.0.164",
     "colorette": "^2.0.20",
-    "ecto": "^4.8.3",
-    "feed": "^5.2.0",
-    "hashery": "^1.5.1",
+    "ecto": "^4.8.4",
+    "hashery": "^2.0.0",
     "jiti": "^2.6.1",
     "serve-handler": "^6.1.7",
     "update-notifier": "^7.3.1",
-    "writr": "^6.1.0"
+    "writr": "^6.1.1"
   },
   "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.12",
+    "@playwright/test": "^1.59.1",
+    "@types/node": "^25.6.0",
     "@types/serve-handler": "^6.1.4",
     "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.1.0",
-    "dotenv": "^17.3.1",
+    "@vitest/coverage-v8": "^4.1.4",
+    "dotenv": "^17.4.2",
     "postject": "1.0.0-alpha.6",
     "rimraf": "^6.1.3",
-    "tsdown": "^0.21.7",
+    "tsdown": "^0.21.9",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   },
   "files": [
     "dist",

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

@@ -68,12 +68,11 @@ body {
   gap: 12px;
 }
 
-.logo-link { display: flex; align-items: center; gap: 8px; text-decoration: none; color: var(--fg); }
+.logo-link { display: flex !important; align-items: center !important; text-decoration: none !important; color: var(--fg) !important; font-size: 18px !important; font-weight: 600 !important; }
 .logo__img {
   height: 75px;
   width: auto;
 }
-.logo__text { font-size: 18px; font-weight: 600; }
 
 .theme-button {
   border: 1px solid transparent;
@@ -290,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;
 }
@@ -773,6 +810,36 @@ pre:hover .copy-code-btn { opacity: 1; }
   color: #92400e;
 }
 
+.changelog-tag-added {
+  background-color: rgba(140, 220, 0, 0.15);
+  color: #4a7a00;
+}
+
+.changelog-tag-improved {
+  background-color: rgba(59, 130, 246, 0.15);
+  color: #1d4ed8;
+}
+
+.changelog-tag-fixed {
+  background-color: rgba(245, 158, 11, 0.15);
+  color: #b45309;
+}
+
+.changelog-tag-removed {
+  background-color: rgba(239, 68, 68, 0.15);
+  color: #b91c1c;
+}
+
+.changelog-tag-deprecated {
+  background-color: rgba(156, 163, 175, 0.15);
+  color: #4b5563;
+}
+
+.changelog-tag-security {
+  background-color: rgba(168, 85, 247, 0.15);
+  color: #6d28d9;
+}
+
 .changelog-entry-title::after {
   content: "";
   position: absolute;

package/templates/modern/includes/header-bar.hbs

@@ -6,7 +6,6 @@
       </button>
       <a href="{{#if homeUrl}}{{homeUrl}}{{else}}{{baseUrl}}/{{/if}}" class="logo-link">
         <img alt="{{siteTitle}}" class="logo__img" src="{{baseUrl}}/logo.svg">
-        <span class="logo__text">{{siteTitle}}</span>
       </a>
       <nav class="header-bottom__nav">
         {{#if hasDocuments}}

package/templates/modern/includes/scripts.hbs

@@ -227,6 +227,48 @@
       }
     });
 
+    // 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 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);
+      };
+
+      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] : section === defaultOpenSection;
+        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) => {

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>