@staticbolt/docs 0.0.1-beta.2 → 0.0.1-beta.4

package/README.md

@@ -33,7 +33,7 @@ export default defineConfig({
     }),
 
     plugins.htmlLayoutPlugin({ tags: ["layout", "part", "icon"] }),
-    theme.HtmlCodeBlockPlugin({ rehypeExpressiveCodeOptions }),
+    theme.htmlCodeBlockPlugin({ rehypeExpressiveCodeOptions }),
     theme.katexFontsPlugin(),
     theme.pagefindPlugin(),
     theme.llmsPlugin({ siteUrl: "https://example.com" }),
@@ -96,6 +96,7 @@ Copy this as `sources/layouts/document.layout.html` and edit the names:
       src="@staticbolt/docs/parts/document/document.part.html"
       title="My Project"
     >
+      <slot name="sidebar" slot="sidebar"></slot>
       <part slot="icons" src="@parts/social-icons/social-icons.part.html"></part>
       <slot />
     </part>
@@ -107,17 +108,17 @@ Copy this as `sources/layouts/document.layout.html` and edit the names:
 
 To change the page structure, copy `node_modules/@staticbolt/docs/sources/parts/document/document.part.html` into the project and point the layout at the copy; it references the other parts by package path, so it works as is.
 
-| Part                  | Role                                                                                         |
-| --------------------- | -------------------------------------------------------------------------------------------- |
-| `document`            | The whole page. `title`, `minHeading`, `maxHeading`, `mermaid`, slot `icons`, default slot.  |
-| `header`              | Takes `title`. Slot `icons` for the social links.                                            |
-| `sidebar`             | Filled by `contentPlugin`. Slot `icons` for the social links.                                |
-| `table-of-content`    | `-desktop` takes `minHeading` and `maxHeading`, `-mobile` none.                              |
-| `pagination-links`    | Previous/next links read from the sidebar.                                                   |
-| `callouts`            | Build-time script turning collapsible callouts into accordions.                              |
-| `mermaid`             | Renders ` ```mermaid ` fences. Removes itself from pages without. Needs `mermaid` installed. |
-| `color-scheme-switch` | Already inside header and sidebar.                                                           |
-| `badge`               | Used by the sidebar for `data.badgeText` / `data.badgeVariant`.                              |
+| Part                  | Role                                                                                                                         |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `document`            | The whole page. `title`, `minHeading`, `maxHeading`, `mermaid`, slots `sidebar` and `icons`, default slot.                   |
+| `header`              | Takes `title`. Slot `icons` for the social links.                                                                            |
+| `sidebar`             | Default slot for the tree, filled by `contentPlugin` through the layout's `sidebar` slot. Slot `icons` for the social links. |
+| `table-of-content`    | `-desktop` takes `minHeading` and `maxHeading`, `-mobile` none.                                                              |
+| `pagination-links`    | Previous/next links read from the sidebar.                                                                                   |
+| `callouts`            | Build-time script turning collapsible callouts into accordions.                                                              |
+| `mermaid`             | Renders ` ```mermaid ` fences. Removes itself from pages without. Needs `mermaid` installed.                                 |
+| `color-scheme-switch` | Already inside header and sidebar.                                                                                           |
+| `badge`               | Used by the sidebar for `data.badgeText` / `data.badgeVariant`.                                                              |
 
 ## Styles
 
@@ -145,4 +146,5 @@ Any `--sb-*` variable from `global.css` can be overridden the same way.
 ## Overriding a part
 
 Copy it from `node_modules/@staticbolt/docs/sources/parts/` into the project and point the layout at the copy.
-For the sidebar parts pass the copy through `contentPlugin`'s `sidebarLayout`, `directoryLayout`, or `linkLayout`.
+For the folder and link parts pass the copy through `contentPlugin`'s `directoryLayout` or `linkLayout`.
+A layout of your own has to forward the `sidebar` slot down to the sidebar part, as the one above does.

package/lib/index.d.mts

@@ -5,7 +5,6 @@ import { Root } from "hast";
 import { LanguageRegistration } from "shiki";
 import { Plugin as Plugin$1 } from "unified";
 import { Root as Root$1 } from "mdast";
-import { Node } from "unist";
 //#region plugins/code-block-plugin.d.ts
 interface HtmlCodeBlockPlugin {
   /**
@@ -21,7 +20,7 @@ interface HtmlCodeBlockPlugin {
  * replaces the tag with a syntax highlighted code block. Use the `lang` attribute to set the language, and the other attributes
  * for the rest of the expressive-code metadata.
  */
-declare function HtmlCodeBlockPlugin(options?: HtmlCodeBlockPlugin): Plugin;
+declare function htmlCodeBlockPlugin(options?: HtmlCodeBlockPlugin): Plugin;
 //#endregion
 //#region plugins/collapsible-plugin.d.ts
 interface CollapsiblePluginOptions {
@@ -161,38 +160,15 @@ interface ContentPluginOptions {
    * @default true
    */
   collapsed?: boolean;
-  /** Defines the layout name/path to be used for markdown files. */
+  /**
+   * Defines the layout name/path to be used for markdown files.\
+   * The sidebar tree goes into the layout's `sidebar` slot, so every layout listed here has to carry a `<slot name="sidebar">`,
+   * or forward one to the part that does.
+   */
   layouts: {
     default: string;
     [key: string]: string;
   };
-  /** The layout into which the generated sidebar HTML will be injected. */
-  sidebarLayout?: {
-    /**
-     * Path to the layout file.
-     *
-     * @default the theme's `sidebar.part.html`
-     */
-    path?: string;
-    /**
-     * The custom-element tag name used for this layout.
-     *
-     * If omitted, the tag name will be auto extracted from the layout path
-     */
-    tag?: string;
-    /**
-     * The attribute on the layout tag that holds the source path.
-     *
-     * @default "src"
-     */
-    sourceAttribute?: string;
-    /**
-     * The slot name into which the sidebar is inserted.
-     *
-     * @default "sidebar"
-     */
-    slotName?: string;
-  };
   /** The layout used to render a collapsible directory node. */
   directoryLayout?: {
     /**
@@ -293,6 +269,25 @@ interface LlmsPluginOptions {
   title?: string;
   /** One-line summary quoted under the heading. */
   summary?: string;
+  /**
+   * Glob patterns for the pages to list.
+   *
+   * @default ["pages/**\/*.md"]
+   */
+  include?: string[];
+  /**
+   * Glob patterns to leave out.
+   *
+   * @default [ ]
+   */
+  exclude?: string[];
+  /**
+   * Path of the pair of files, relative to the output directory and without the extension: `"llms"` writes `llms.txt` and
+   * `llms-full.txt`. Give each plugin a path of its own when a site runs more than one.
+   *
+   * @default "llms"
+   */
+  output?: string;
 }
 /**
  * Writes `llms.txt` and `llms-full.txt`, plus a copy of every page's markdown beside its HTML.
@@ -381,6 +376,6 @@ interface PagefindPluginOptions {
 declare function pagefindPlugin({ glob }?: PagefindPluginOptions): Plugin;
 //#endregion
 //#region plugins/wrap-table.d.ts
-declare function wrapTables(): (tree: Node) => void;
+declare function wrapTables(): (tree: Root) => void;
 //#endregion
-export { CollapsiblePluginOptions, HtmlCodeBlockPlugin, PersistentCache, RemarkObsidianCommentsOptions, cachedRehypeExpressiveCode, contentPlugin, ecCachePlugin, ecCacheSalt, htmlWithTypeScriptScripts, katexFontsPlugin, llmsPlugin, normalizeTitle, pagefindPlugin, pluginCollapsible, rehypeMermaidFence, remarkObsidianComments, remarkObsidianTags, sha1, wrapTables };
+export { CollapsiblePluginOptions, HtmlCodeBlockPlugin, PersistentCache, RemarkObsidianCommentsOptions, cachedRehypeExpressiveCode, contentPlugin, ecCachePlugin, ecCacheSalt, htmlCodeBlockPlugin, htmlWithTypeScriptScripts, katexFontsPlugin, llmsPlugin, normalizeTitle, pagefindPlugin, pluginCollapsible, rehypeMermaidFence, remarkObsidianComments, remarkObsidianTags, sha1, wrapTables };

package/lib/plugins.mjs

@@ -5,13 +5,12 @@ import { ExpressiveCodeBlock } from "expressive-code";
 import { toHtml } from "hast-util-to-html";
 import rehypeExpressiveCode, { createRenderer } from "rehype-expressive-code";
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, globSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, globSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import yaml from "yaml";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { visit } from "unist-util-visit";
 import * as pagefind from "pagefind";
-import { selectAll } from "hast-util-select";
 //#region plugins/ec-cache.ts
 /**
 * Persistent cross-build caches for expressive-code rendering.
@@ -119,7 +118,7 @@ function cachedRehypeExpressiveCode(options) {
 * replaces the tag with a syntax highlighted code block. Use the `lang` attribute to set the language, and the other attributes
 * for the rest of the expressive-code metadata.
 */
-function HtmlCodeBlockPlugin(options = {}) {
+function htmlCodeBlockPlugin(options = {}) {
 	const tag = options.tagName ?? "code-block";
 	let renderCache;
 	let diskCache;
@@ -417,11 +416,6 @@ function prepareOptions(options) {
 	const icons = options.icons ?? "";
 	const publish = options.publish ?? true;
 	const collapsed = options.collapsed ?? true;
-	const sidebarLayout = options.sidebarLayout ?? {};
-	sidebarLayout.path ??= themeSidebarPart("sidebar.part.html");
-	sidebarLayout.tag ??= path.basename(sidebarLayout.path).split(".")[1];
-	sidebarLayout.sourceAttribute ??= "src";
-	sidebarLayout.slotName ??= "sidebar";
 	const directoryLayout = options.directoryLayout ?? {};
 	directoryLayout.path ??= themeSidebarPart("directory.part.html");
 	directoryLayout.tag ??= path.basename(directoryLayout.path).split(".")[1];
@@ -439,7 +433,6 @@ function prepareOptions(options) {
 		icons,
 		publish,
 		collapsed,
-		sidebarLayout,
 		directoryLayout,
 		linkLayout
 	};
@@ -500,51 +493,6 @@ function parseSidebarFrontmatter(file) {
 	};
 }
 //#endregion
-//#region plugins/content-plugin/render-tree.ts
-/** `<icon>` source for a node, `undefined` when the project has no icons directory or the node no icon. */
-function iconSource(icons, icon) {
-	if (!icons || !icon) return;
-	return `${icons.replace(/\/$/, "")}/${icon}.icon.html`;
-}
-function renderDirectory(directory, items, { directoryLayout, customizations, icons }) {
-	const customization = customizations[directory.realPath];
-	const data = {
-		title: customization?.label ?? directory.title,
-		collapsed: customization?.collapsed ?? directory.collapsed,
-		...customization?.data,
-		iconSrc: iconSource(icons, customization?.data?.icon)
-	};
-	return `<li class="sidebar-list-item">
-            <${directoryLayout.tag} dataJson='${escapeAttributeValue(JSON.stringify(data))}' ${directoryLayout.sourceAttribute}="${directoryLayout.path}">
-              <ul class="sidebar-list">${items}</ul>
-            </${directoryLayout.tag}>
-          </li>`;
-}
-function renderLink(link, { linkLayout, customizations, icons }) {
-	const customization = customizations[link.realPath];
-	const data = {
-		title: customization?.label ?? link.title,
-		fullTitle: link.pageTitle ?? link.title,
-		href: encodeURIComponent(link.filePath),
-		...customization?.data,
-		iconSrc: iconSource(icons, customization?.data?.icon)
-	};
-	return `<li class="sidebar-list-item">
-            <${linkLayout.tag} dataJson='${escapeAttributeValue(JSON.stringify(data))}' ${linkLayout.sourceAttribute}="${linkLayout.path}"></${linkLayout.tag}>
-          </li>`;
-}
-function renderTree(items, options) {
-	let tree = "";
-	for (const item of items) {
-		if (isItem(item)) {
-			tree += renderLink(item, options);
-			continue;
-		}
-		tree += renderDirectory(item, renderTree(item.items, options), options);
-	}
-	return tree;
-}
-//#endregion
 //#region plugins/content-plugin/generate-tree.ts
 function getOrCreateDirectory(tree, title, realPath, collapsed) {
 	let directory = tree.find((entry) => "items" in entry && entry.title === title);
@@ -610,7 +558,7 @@ function generateTree(options) {
 		const fileNameWithoutExtension = path.parse(fileName).name;
 		const title = fileNameWithoutExtension === "index" && directories.length === 0 ? "Home" : normalizeTitle(fileNameWithoutExtension);
 		const pathAsLink = fileNameWithoutExtension === "index" ? path.dirname(file) : path.join(path.dirname(file), fileNameWithoutExtension);
-		const href = path.relative(path.dirname(options.sidebarLayout.path), pathAsLink) + "/";
+		const href = this.resolver.aliasPath(pathAsLink) + "/";
 		currentTree.push({
 			title,
 			filePath: href,
@@ -620,48 +568,126 @@ function generateTree(options) {
 	}
 	applyOrdering(autoGenerated, options.customizations);
 	return {
-		tree: `<ul class="sidebar-list" slot="${options.sidebarLayout.slotName}">${renderTree(autoGenerated, options)}</ul>`,
+		tree: autoGenerated,
 		notPublished
 	};
 }
 //#endregion
+//#region plugins/content-plugin/render-tree.ts
+/** `<icon>` source for a node, `undefined` when the project has no icons directory or the node no icon. */
+function iconSource(icons, icon) {
+	if (!icons || !icon) return;
+	return `${icons.replace(/\/$/, "")}/${icon}.icon.html`;
+}
+function renderDirectory(directory, items, { directoryLayout, customizations, icons }) {
+	const customization = customizations[directory.realPath];
+	const data = {
+		title: customization?.label ?? directory.title,
+		collapsed: customization?.collapsed ?? directory.collapsed,
+		...customization?.data,
+		iconSrc: iconSource(icons, customization?.data?.icon)
+	};
+	return `<li class="sidebar-list-item">
+            <${directoryLayout.tag} dataJson='${escapeAttributeValue(JSON.stringify(data))}' ${directoryLayout.sourceAttribute}="${directoryLayout.path}">
+              <ul class="sidebar-list">${items}</ul>
+            </${directoryLayout.tag}>
+          </li>`;
+}
+function renderLink(link, { linkLayout, customizations, icons }) {
+	const customization = customizations[link.realPath];
+	const data = {
+		title: customization?.label ?? link.title,
+		fullTitle: link.pageTitle ?? link.title,
+		href: encodeURIComponent(link.filePath),
+		...customization?.data,
+		iconSrc: iconSource(icons, customization?.data?.icon)
+	};
+	return `<li class="sidebar-list-item">
+            <${linkLayout.tag} dataJson='${escapeAttributeValue(JSON.stringify(data))}' ${linkLayout.sourceAttribute}="${linkLayout.path}"></${linkLayout.tag}>
+          </li>`;
+}
+function renderTree(items, options) {
+	let tree = "";
+	for (const item of items) {
+		if (isItem(item)) {
+			tree += renderLink(item, options);
+			continue;
+		}
+		tree += renderDirectory(item, renderTree(item.items, options), options);
+	}
+	return tree;
+}
+//#endregion
 //#region plugins/content-plugin/content-plugin.ts
-/**
-* Turns an alias, a package specifier, or an absolute path into the path the build works with: relative to the project root when
-* the file lives inside it, absolute otherwise.
-*/
+/** Turns an alias, a package specifier, or an absolute path into a path relative to the project root. */
 function locate(source) {
 	const aliased = this.resolver.resolveAlias(source);
 	if (aliased) return aliased;
 	const resolved = path.isAbsolute(source) ? source : this.resolver.resolve(source, path.join(this.root, "index.html"))?.path;
-	if (!resolved) return source;
-	const relative = path.relative(this.root, resolved);
-	return relative.startsWith("..") ? resolved : relative;
+	return resolved ? path.relative(this.root, resolved) : source;
+}
+/** The layout's empty `<slot name="sidebar">`, with the attributes around the name captured for the `slot` it forwards to. */
+const slotRegex = /<slot\b([^>]*)\bname\s*=\s*["']sidebar["']([^>]*?)(\/>|>\s*<\/slot\s*>)/g;
+/** The tree in place of the slot, sent to the same slot of the part below when the slot was forwarding to one. */
+function fillSlot(content, tree) {
+	return content.replace(slotRegex, (_, before, after) => {
+		const target = /\bslot\s*=\s*["']([^"']*)["']/.exec(`${before} ${after}`)?.[1];
+		return `<ul class="sidebar-list"${target ? ` slot="${target}"` : ""}>${tree}</ul>`;
+	});
 }
 function contentPlugin(options) {
 	const prepared = prepareOptions(options);
-	const slotRegex = new RegExp(String.raw`<slot\s+name\s*=\s*['"]sidebar['"]\s*(\/>|>\s*<\/\s*slot\s*>)`, "g");
 	let tree = "";
 	let notPublished = /* @__PURE__ */ new Set();
-	let sidebarRealPath = "";
+	/**
+	* The layouts this instance serves through `read`, each the file it is read from with the tree in its `sidebar` slot.
+	*
+	* @key served path, relative to the root
+	* @value the layout file it is a copy of
+	*/
+	const served = /* @__PURE__ */ new Map();
+	const isInScope = (relativePath, root) => {
+		return path.isPathMatch(relativePath, {
+			include: prepared.include,
+			ignore: prepared.exclude,
+			root
+		});
+	};
+	const generate = (app) => {
+		const result = generateTree.call(app, prepared);
+		return {
+			tree: renderTree(result.tree, prepared),
+			notPublished: result.notPublished
+		};
+	};
 	return {
 		name: "content-plugin",
 		setup() {
-			for (const key in prepared.layouts) prepared.layouts[key] = locate.call(this, prepared.layouts[key]);
-			prepared.sidebarLayout.path = locate.call(this, prepared.sidebarLayout.path);
-			sidebarRealPath = realpathSync(path.resolve(this.root, prepared.sidebarLayout.path));
-			const sidebarDirectory = path.dirname(path.resolve(this.root, prepared.sidebarLayout.path));
-			const directoryLayoutPath = path.resolve(this.root, locate.call(this, prepared.directoryLayout.path));
-			prepared.directoryLayout.path = path.relative(sidebarDirectory, directoryLayoutPath);
-			const linkLayoutPath = path.resolve(this.root, locate.call(this, prepared.linkLayout.path));
-			prepared.linkLayout.path = path.relative(sidebarDirectory, linkLayoutPath);
+			const instance = (this.pluginData.contentPluginInstances ?? 0) + 1;
+			this.pluginData.contentPluginInstances = instance;
+			for (const key in prepared.layouts) {
+				const original = locate.call(this, prepared.layouts[key]);
+				if (instance === 1) {
+					served.set(original, original);
+					continue;
+				}
+				const [name, ...rest] = path.basename(original).split(".");
+				const copy = path.join(path.dirname(original), [
+					name,
+					`content-${instance}`,
+					...rest
+				].join("."));
+				served.set(copy, original);
+				this.resolver.files.add(path.resolve(this.root, copy));
+				prepared.layouts[key] = copy;
+			}
 			for (const pathKey in prepared.customizations) {
 				const resolvedPath = this.resolver.resolveAlias(pathKey);
 				if (!resolvedPath) continue;
 				prepared.customizations[resolvedPath] = prepared.customizations[pathKey];
 				delete prepared.customizations[pathKey];
 			}
-			({tree, notPublished} = generateTree.call(this, prepared));
+			({tree, notPublished} = generate(this));
 			for (const file of notPublished) {
 				this.entryPoints.delete(file);
 				this.entryPoints.delete(`./${file}`);
@@ -672,37 +698,30 @@ function contentPlugin(options) {
 		},
 		read(absolutePath) {
 			const relativePath = path.relative(this.root, absolutePath);
-			if (path.basename(absolutePath) === path.basename(sidebarRealPath) && realpathSync(absolutePath) === sidebarRealPath) return readFileSync(absolutePath, "utf8").replace(slotRegex, tree);
-			if (path.extname(relativePath) !== ".md") return;
-			if (!path.isPathMatch(relativePath, {
-				include: prepared.include,
-				ignore: prepared.exclude,
-				root: this.root
-			})) return;
+			const original = served.get(relativePath);
+			if (original) return fillSlot(readFileSync(path.resolve(this.root, original), "utf8"), tree);
+			if (path.extname(relativePath) !== ".md" || !isInScope(relativePath, this.root)) return;
 			const pageContent = readFileSync(absolutePath, "utf8");
 			const frontMatterBlock = pageContent.match(/^---\n(.*?)\n---/s);
 			const frontMatter = {
 				layout: "default",
 				...frontMatterBlock ? yaml.parse(frontMatterBlock[1]) : {}
 			};
-			const layoutPath = prepared.layouts[frontMatter.layout] ?? prepared.layouts.default;
-			frontMatter.layout = path.relative(path.dirname(relativePath), layoutPath);
+			const layout = prepared.layouts[frontMatter.layout] ?? prepared.layouts.default;
+			frontMatter.layout = served.has(layout) ? path.relative(path.dirname(absolutePath), path.resolve(this.root, layout)) : layout;
 			for (const key in frontMatter) if (key === "publish" || key.startsWith("sidebar.")) delete frontMatter[key];
 			const body = frontMatterBlock ? pageContent.slice(frontMatterBlock[0].length) : pageContent;
 			return `---\n${yaml.stringify(frontMatter)}\n---\n${body}`;
 		},
 		onFileEvent(_, id) {
-			if (!path.isPathMatch(id, {
-				include: prepared.include,
-				ignore: prepared.exclude,
-				root: this.root
-			})) return;
-			const result = generateTree.call(this, prepared);
+			for (const [copy, original] of served) if (original === id && copy !== id) this.watcher?.emit("change", copy);
+			if (!isInScope(id, this.root)) return;
+			const result = generate(this);
 			notPublished = result.notPublished;
 			if (tree === result.tree) return;
 			this.log.info("Re-generating sidebar tree");
 			tree = result.tree;
-			this.watcher?.emit("change", prepared.sidebarLayout.path);
+			for (const layout of served.keys()) this.watcher?.emit("change", layout);
 		}
 	};
 }
@@ -755,14 +774,14 @@ const markdownLink = /\[([^\]]+)\]\([^)]*\)/g;
 * needs no link-following. Nothing is curated by hand.
 */
 function llmsPlugin(options = {}) {
-	const { siteUrl, title = "Documentation", summary } = options;
+	const { siteUrl, title = "Documentation", summary, include = ["pages/**/*.md"], exclude = [], output = "llms" } = options;
 	return {
 		name: "llms",
 		async postBuild() {
 			if (!siteUrl) return;
 			const origin = siteUrl.replace(/\/+$/, "");
 			const isBuilt = (file) => Boolean(this.findMetadata({ id: file }) ?? this.findMetadata({ id: `./${file}` }));
-			const entries = await collectPages(this.root, isBuilt);
+			const entries = await collectPages(this.root, isBuilt, include, exclude);
 			if (entries.length === 0) return;
 			for (const entry of entries) {
 				const target = join(this.outdir, entry.route, "index.md");
@@ -787,24 +806,30 @@ function llmsPlugin(options = {}) {
 					manifest.push(`- [${entry.title}](${url})${entry.description ? `: ${entry.description}` : ""}`);
 				}
 			}
-			await writeFile(join(this.outdir, "llms.txt"), manifest.join("\n") + "\n", "utf8");
+			const manifestFile = `${output}.txt`;
+			const fullFile = `${output}-full.txt`;
+			await mkdir(dirname(join(this.outdir, manifestFile)), { recursive: true });
+			await writeFile(join(this.outdir, manifestFile), manifest.join("\n") + "\n", "utf8");
 			const full = [[
 				...heading,
 				"",
-				`> Every document from ${origin}/llms.txt inlined in full, so no links need following.`
+				`> Every document from ${origin}/${manifestFile} inlined in full, so no links need following.`
 			].join("\n"), ...entries.map((entry) => {
 				const source = `${origin}/${entry.route}${entry.route ? "/" : ""}index.md`;
 				return `${demoteHeadings(entry.document, entry.title)}\n\nSource: ${source}`;
 			})].join("\n\n---\n\n") + "\n";
-			await writeFile(join(this.outdir, "llms-full.txt"), rewriteAliases(full, origin), "utf8");
+			await writeFile(join(this.outdir, fullFile), rewriteAliases(full, origin), "utf8");
 			const kilobytes = Math.round(Buffer.byteLength(full) / 1024);
-			this.log.success(`Wrote llms.txt (${entries.length} links) and llms-full.txt (${kilobytes} KB).`);
+			this.log.success(`Wrote ${manifestFile} (${entries.length} links) and ${fullFile} (${kilobytes} KB).`);
 		}
 	};
 }
 /** Pages the build produced, so anything the markdown plugin dropped (`publish: false`) stays out of the llms files too. */
-async function collectPages(root, isBuilt) {
-	const files = globSync("pages/**/*.md", { cwd: root }).map((file) => file.replaceAll("\\", "/")).filter((file) => isBuilt(file)).toSorted(byDepthThenPath);
+async function collectPages(root, isBuilt, include, exclude) {
+	const files = globSync(include, {
+		cwd: root,
+		exclude
+	}).map((file) => file.replaceAll("\\", "/")).filter((file) => isBuilt(file)).toSorted(byDepthThenPath);
 	const entries = [];
 	for (const file of files) {
 		const document = clean(await readFile(join(root, file), "utf8"));
@@ -890,6 +915,13 @@ function byDepthThenPath(a, b) {
 }
 //#endregion
 //#region plugins/mermaid-fence.ts
+/** The sole `<code>` child of a `<pre>`, ignoring the whitespace some serialisers insert, or nothing when the shape differs. */
+function onlyCodeChild(node) {
+	const children = node.children.filter((child) => !(child.type === "text" && child.value.trim() === ""));
+	const [child] = children;
+	if (children.length !== 1 || child.type !== "element" || child.tagName !== "code") return;
+	return child;
+}
 /**
 * Rehype plugin: converts fenced mermaid code blocks into <pre class="mermaid"> elements.
 *
@@ -900,60 +932,21 @@ function byDepthThenPath(a, b) {
 const rehypeMermaidFence = () => {
 	return (tree) => {
 		visit(tree, "element", (node) => {
-			if (!isPreElement(node)) return;
-			const codeElement = findSingleCodeChild(node);
-			if (codeElement === null) return;
-			if (!hasMermaidLanguageClass(codeElement)) return;
-			const mermaidSource = extractTextContent(codeElement);
-			if (mermaidSource === null) return;
+			if (node.tagName !== "pre") return;
+			const code = onlyCodeChild(node);
+			if (!code) return;
+			const className = code.properties?.className;
+			if (!(Array.isArray(className) ? className : [className]).some((name) => String(name) === "language-mermaid")) return;
+			const text = code.children.filter((child) => child.type === "text");
+			if (text.length === 0) return;
 			node.properties = { className: ["mermaid"] };
 			node.children = [{
 				type: "text",
-				value: mermaidSource
+				value: text.map((child) => child.value).join("")
 			}];
 		});
 	};
 };
-function isPreElement(node) {
-	return node.tagName === "pre";
-}
-/** Returns the sole <code> child of a <pre>, or null if the structure doesn't match (e.g. multiple children, wrong tag). */
-function findSingleCodeChild(preNode) {
-	const nonWhitespaceChildren = [];
-	for (const child of preNode.children) {
-		if (child.type === "text" && child.value.trim() === "") continue;
-		nonWhitespaceChildren.push(child);
-	}
-	if (nonWhitespaceChildren.length !== 1) return null;
-	const [onlyChild] = nonWhitespaceChildren;
-	if (onlyChild.type !== "element") return null;
-	if (onlyChild.tagName !== "code") return null;
-	return onlyChild;
-}
-/**
-* Returns true when the element's className list contains "language-mermaid". Handles both string and array forms that hast
-* allows.
-*/
-function hasMermaidLanguageClass(codeElement) {
-	const rawClassName = codeElement.properties?.className;
-	if (rawClassName === void 0 || rawClassName === null) return false;
-	const classNames = Array.isArray(rawClassName) ? rawClassName : [String(rawClassName)];
-	for (const className of classNames) if (className === "language-mermaid") return true;
-	return false;
-}
-/**
-* Concatenates all text-node descendants of an element. Returns null when there are no text nodes (empty code block is valid →
-* ""). A <code> block produced by remark-rehype always has exactly one Text child, but we handle edge cases defensively.
-*/
-function extractTextContent(element) {
-	let content = "";
-	let found = false;
-	for (const child of element.children) if (child.type === "text") {
-		content += child.value;
-		found = true;
-	}
-	return found ? content : null;
-}
 //#endregion
 //#region plugins/obsidian-comments.ts
 const commentPattern = /(?<!\\)%%[\s\S]*?(?<!\\)%%/g;
@@ -1108,18 +1101,17 @@ function pagefindPlugin({ glob = "**/*.html" } = {}) {
 //#region plugins/wrap-table.ts
 function wrapTables() {
 	return (tree) => {
-		const tables = selectAll("table", tree);
-		for (const table of tables) visit(tree, table, (node, index, parent) => {
-			if (!parent || typeof index !== "number") return;
-			const wrapper = {
+		visit(tree, "element", (node, index, parent) => {
+			if (node.tagName !== "table" || !parent || typeof index !== "number") return;
+			parent.children[index] = {
 				type: "element",
 				tagName: "div",
 				properties: { class: "table-wrapper" },
 				children: [node]
 			};
-			parent.children[index] = wrapper;
+			return "skip";
 		});
 	};
 }
 //#endregion
-export { HtmlCodeBlockPlugin, PersistentCache, cachedRehypeExpressiveCode, contentPlugin, ecCachePlugin, ecCacheSalt, htmlWithTypeScriptScripts, katexFontsPlugin, llmsPlugin, normalizeTitle, pagefindPlugin, pluginCollapsible, rehypeMermaidFence, remarkObsidianComments, remarkObsidianTags, sha1, wrapTables };
+export { PersistentCache, cachedRehypeExpressiveCode, contentPlugin, ecCachePlugin, ecCacheSalt, htmlCodeBlockPlugin, htmlWithTypeScriptScripts, katexFontsPlugin, llmsPlugin, normalizeTitle, pagefindPlugin, pluginCollapsible, rehypeMermaidFence, remarkObsidianComments, remarkObsidianTags, sha1, wrapTables };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staticbolt/docs",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.4",
   "description": "Documentation theme for staticbolt: layout parts, styles, and plugins shared by every docs site.",
   "author": "Ahmed ALABSI",
   "license": "MIT",
@@ -66,7 +66,6 @@
     "@pagefind/component-ui": "^1.5.2",
     "@xt0rted/expressive-code-file-icons": "^1.0.0",
     "expressive-code": "^0.42.0",
-    "hast-util-select": "^6.0.2",
     "hast-util-to-html": "^9.0.5",
     "pagefind": "^1.5.2",
     "rehype-expressive-code": "^0.42.0",
@@ -76,7 +75,14 @@
   },
   "overrides": {
     "expressive-code": "^0.42.0",
-    "@expressive-code/core": "^0.42.0"
+    "@expressive-code/core": "^0.42.0",
+    "d3-array": "^3.2.4",
+    "d3-shape": "^3.2.0",
+    "d3-path": "^3.1.0",
+    "internmap": "^2.0.3",
+    "marked": "^18.0.11",
+    "cose-base": "^2.2.0",
+    "layout-base": "^2.0.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/sources/parts/callouts/callouts.part.html

@@ -2,8 +2,8 @@
 <script type="application/x-typescript" build-time>
   for (const callout of document.querySelectorAll("details.callout")) {
     const accordion = document.createElement("sv-accordion");
-    accordion.setAttribute("data-callout", callout.getAttribute("data-callout"));
-    accordion.setAttribute("class", callout.getAttribute("class"));
+    accordion.setAttribute("data-callout", callout.getAttribute("data-callout") || "");
+    accordion.setAttribute("class", callout.getAttribute("class") || "");
     accordion.setAttribute("heading-level", "none");
 
     if (callout.hasAttribute("open")) {

package/sources/parts/color-scheme-switch/color-scheme-switch.part.html

@@ -77,12 +77,7 @@
 
       document.addEventListener("DOMContentLoaded", onReady, { once: true, passive: true });
 
-      /**
-       * @param {() => void} update
-       * @param {number} x
-       * @param {number} y
-       */
-      async function viewTransition(update, x, y) {
+      async function viewTransition(update: () => void, x: number, y: number) {
         if (!document.startViewTransition || matchMedia("(prefers-reduced-motion: reduce)").matches) {
           update();
           return;

package/sources/parts/document/document.part.html

@@ -5,6 +5,7 @@
   @attr maxHeading - Highest heading level in the table of contents. Default 3.
   @attr mermaid - Present to render mermaid fences. Needs the mermaid package.
   @slot - The page content.
+  @slot sidebar - The sidebar tree, filled in by contentPlugin through the layout.
   @slot logo - Rendered before the title in the header link.
   @slot icons - Links rendered in the header and the sidebar footer.
 -->
@@ -21,6 +22,7 @@
 
 <div class="markdown-layout">
   <part src="@staticbolt/docs/parts/sidebar/sidebar.part.html">
+    <slot name="sidebar"></slot>
     <slot name="icons" slot="icons"></slot>
   </part>
 

package/sources/parts/pagination-links/pagination-links.part.html

@@ -29,11 +29,11 @@
   // ::: Get current link and populate previous/next links :::
   import { join, dirname, normalize } from "node:path";
 
-  const paginationPrev = document.querySelector(".pagination-link-prev");
-  const paginationPrevTitle = paginationPrev.querySelector(".link-title");
+  const paginationPrev = document.querySelector(".pagination-link-prev")!;
+  const paginationPrevTitle = paginationPrev.querySelector(".link-title")!;
 
-  const paginationNext = document.querySelector(".pagination-link-next");
-  const paginationNextTitle = paginationNext.querySelector(".link-title");
+  const paginationNext = document.querySelector(".pagination-link-next")!;
+  const paginationNextTitle = paginationNext.querySelector(".link-title")!;
 
   // You can find `.sidebar` in the documentation layout
   const navigationLinks = document.querySelectorAll(".sidebar a.sidebar-link");
@@ -50,7 +50,7 @@
     const previousLink = navigationLinks[linkIndex - 1];
     if (previousLink) {
       const prevHref = previousLink.getAttribute("href");
-      paginationPrev.setAttribute("href", prevHref);
+      paginationPrev.setAttribute("href", prevHref || "#");
 
       const prevTitle = previousLink.getAttribute("data-title") || previousLink.textContent;
       paginationPrevTitle.textContent = prevTitle;
@@ -62,7 +62,7 @@
     const nextLink = navigationLinks[linkIndex + 1];
     if (nextLink) {
       const nextHref = nextLink.getAttribute("href");
-      paginationNext.setAttribute("href", nextHref);
+      paginationNext.setAttribute("href", nextHref || "#");
 
       const nextTitle = nextLink.getAttribute("data-title") || nextLink.textContent;
       paginationNextTitle.textContent = nextTitle;

package/sources/parts/sidebar/sidebar.part.html

@@ -1,6 +1,6 @@
 <div class="sidebar">
   <nav aria-label="Sidebar navigation">
-    <slot name="sidebar"></slot>
+    <slot></slot>
   </nav>
 
   <div class="sidebar-footer">
@@ -22,7 +22,7 @@
   const navigationLinks = document.querySelectorAll(".sidebar a");
   const currentFile = normalize(__filepath);
 
-  for (const [linkIndex, link] of navigationLinks.entries()) {
+  for (const [, link] of navigationLinks.entries()) {
     const linkPath = join(dirname(__filepath), link.attributes.href, "index.html");
     if (linkPath !== currentFile) continue;
 
@@ -43,8 +43,10 @@
 
 <!-- ::: Persist sidebar navigation state across page loads. ::: -->
 <script type="application/x-typescript">
+  import type { Accordion } from "@staticview/ui/accordion";
+
   (() => {
-    const accordions = document.querySelectorAll<HTMLDivElement>(".sidebar-accordion");
+    const accordions = document.querySelectorAll<Accordion>(".sidebar-accordion");
 
     // ::: Restore the accordion's previous open state. :::
     try {
@@ -67,7 +69,7 @@
 
     // ::: Save accordion open state when toggled. :::
     const accordionToggleHandler = () => {
-      const state = {};
+      const state: Record<string, boolean> = {};
 
       for (const [accordionIndex, accordion] of accordions.entries()) {
         state[accordionIndex] = accordion.opened;
@@ -81,7 +83,8 @@
     }
 
     // ::: Restore sidebar scroll position. :::
-    const sidebar = document.querySelector(".sidebar");
+    const sidebar = document.querySelector<HTMLElement>(".sidebar");
+    if (!sidebar) return;
 
     const onReady = () => {
       // First rAF: end of current task, second rAF: after first paint
@@ -97,7 +100,7 @@
 
     // ::: Save sidebar scroll position. :::
     const sidebarScrollHandler = () => {
-      sessionStorage.setItem("sidebar-scroll", sidebar.scrollTop);
+      sessionStorage.setItem("sidebar-scroll", String(sidebar.scrollTop));
     };
 
     sidebar.addEventListener("scroll", sidebarScrollHandler, { passive: true });

package/sources/parts/table-of-content/table-of-content-desktop.part.html

@@ -71,17 +71,18 @@
     const links = document.querySelectorAll(".toc-list a");
 
     // Mobile TOC current title
-    const currentTitle = document.querySelector(".toc-current-title");
+    const currentTitle = document.querySelector<HTMLElement>(".toc-current-title");
 
     const headings = Array.from(links)
-      .map(a => document.getElementById(a.getAttribute("href").slice(1)))
-      .filter(Boolean);
+      .map(a => document.getElementById(a.getAttribute("href")?.slice(1) ?? ""))
+      .filter(Boolean) as HTMLElement[];
 
-    function setActive(id) {
+    function setActive(id: string) {
       for (const link of links) {
         const active = link.getAttribute("href") === "#" + id;
         link.classList.toggle("active", active);
-        if (active) {
+
+        if (active && currentTitle) {
           currentTitle.textContent = link.textContent;
         }
       }
@@ -90,8 +91,8 @@
     function update() {
       if (!headings.length) return;
 
-      let scrollPaddingTop = getComputedStyle(document.documentElement).getPropertyValue("scroll-padding-top");
-      scrollPaddingTop = parseFloat(scrollPaddingTop.replace("px", "").trim());
+      const scrollPaddingTopStyle = getComputedStyle(document.documentElement).getPropertyValue("scroll-padding-top");
+      let scrollPaddingTop = parseFloat(scrollPaddingTopStyle.replace("px", "").trim());
       scrollPaddingTop = !isFinite(scrollPaddingTop) ? 50 : scrollPaddingTop + 2;
 
       let active = headings[0];

package/sources/parts/table-of-content/table-of-content-mobile.part.html

@@ -13,12 +13,16 @@
 
 <!-- ::: Close the accordion when a link is clicked ::: -->
 <script type="application/x-typescript" module>
-  const tocAccordion = document.querySelector(".toc-accordion");
+  import type { Accordion } from "@staticview/ui/accordion";
+
+  const tocAccordion = document.querySelector<Accordion>(".toc-accordion");
   const tocLinks = document.querySelectorAll(".toc-accordion a");
 
   for (const link of tocLinks) {
     link.addEventListener("click", () => {
-      tocAccordion.opened = false;
+      if (tocAccordion) {
+        tocAccordion.opened = false;
+      }
     });
   }
 </script>