docula 1.12.0 → 1.13.0

package/dist/docula.d.ts

@@ -153,6 +153,10 @@ type DoculaChangelogEntry = {
   previewImage?: string;
   urlPath: string;
   lastModified: string;
+  description?: string;
+  keywords?: string[];
+  ogTitle?: string;
+  ogDescription?: string;
 };
 type DoculaData = {
   siteUrl: string;
@@ -175,6 +179,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 +282,7 @@ type DoculaCacheOptions = {
 type DoculaAIOptions = {
   provider: string;
   model?: string;
-  apiKey: string;
+  apiKey?: string;
 };
 declare class DoculaOptions {
   /**
@@ -345,9 +356,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;
   /**
@@ -441,7 +453,10 @@ declare class DoculaBuilder {
   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.13.0";
 var package_default = {
 	name: "docula",
 	version,
@@ -161,13 +161,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 +183,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 +214,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 +244,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 +296,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 +306,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 +318,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 +328,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
@@ -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 */
@@ -1089,7 +1141,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 +1156,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 +1314,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 +1331,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 +2495,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;
 	/**
@@ -2697,14 +2766,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 +2785,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 +2804,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 +2869,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 +2877,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 +3014,10 @@ 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");
+		return {
+			sourcePath: cwdReadmePath,
+			content: readmeContent
+		};
 	}
 	async getGithubData(githubPath) {
 		const paths = githubPath.split("/");
@@ -3016,11 +3091,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 +3129,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docula",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Beautiful Website for Your Projects",
   "type": "module",
   "main": "./dist/docula.js",

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;
@@ -773,6 +772,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}}