nimbus-docs 0.1.6 → 0.1.8

package/dist/index.js

@@ -1,5 +1,5 @@
-import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-DnAP-j89.js";
-import { t as withStrictKeys } from "./strict-keys-BiXiT3pq.js";
+import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-B7o0k3TA.js";
+import { i as toRouteKey, n as isAbsoluteUrl, r as toBrowserHref, t as withStrictKeys } from "./strict-keys-fbKKxxKL.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import fs from "node:fs";
@@ -162,112 +162,6 @@ function canonicalEntryUrl(prefix, entryId) {
 	return `${prefix}/${slug}`;
 }
 
-//#endregion
-//#region src/_internal/url.ts
-/**
-* Internal URL helpers — one shape for matching, one shape for rendering.
-*
-* Static hosts that serve `page/index.html` (Astro's default `build.format:
-* "directory"`) canonicalize to a trailing-slash URL. If framework helpers
-* emit slashless hrefs, every sidebar click costs a 307 redirect before
-* Astro's client router can pick up the page. The fix splits href shape
-* into two forms:
-*
-*   - `toRouteKey(href)` — slashless canonical form. Used wherever the
-*     framework compares paths for identity (active sidebar state,
-*     prev/next lookup, validation against the indexed route set).
-*
-*   - `toBrowserHref(href)` — what we emit into `<a href>` / `<link>` for
-*     HTML document routes. Adds a trailing slash so the URL matches the
-*     directory-index page the host serves directly.
-*
-* Asset URLs (`.md`, `.png`, `.txt`, …), external URLs, and anchor-only
-* hrefs are returned unchanged by `toBrowserHref` — they aren't HTML
-* document routes and adding a slash would break them.
-*
-* Keep these out of the public API: starter components consume hrefs the
-* framework already shaped. Authors don't (and shouldn't) call these
-* directly.
-*/
-/**
-* True for hrefs that point off-site — anything with a URI scheme
-* (`https:`, `mailto:`, `data:`, …) or a protocol-relative `//cdn.…`
-* prefix. Bare relative paths like `"cli"` and `"./foo"` are NOT external
-* — they resolve against the current page and the framework shouldn't
-* second-guess them.
-*/
-function isAbsoluteUrl(href) {
-	return /^([a-z][a-z0-9+\-.]*:|\/\/)/i.test(href);
-}
-/**
-* Detect whether the final path segment looks like a file (has an
-* extension). HTML document routes don't carry an extension under
-* `build.format: "directory"`; assets like `/og/card.png`,
-* `/llms.txt`, and `/cli/index.md` do.
-*
-* Conservative: only treats short, ASCII-letter-only extensions as files,
-* so paths with dots inside a segment (`/v1.2/foo`, version slugs) still
-* count as document routes.
-*/
-function hasFileExtension(pathname) {
-	const lastSegment = pathname.slice(pathname.lastIndexOf("/") + 1);
-	const dot = lastSegment.lastIndexOf(".");
-	if (dot <= 0) return false;
-	const ext = lastSegment.slice(dot + 1);
-	return ext.length > 0 && ext.length <= 6 && /^[a-zA-Z0-9]+$/.test(ext);
-}
-/** Split an href into `[pathname, suffix]` where `suffix` is the `?…#…` tail. */
-function splitSuffix(href) {
-	const queryAt = href.indexOf("?");
-	const hashAt = href.indexOf("#");
-	const cutAt = queryAt === -1 ? hashAt : hashAt === -1 ? queryAt : Math.min(queryAt, hashAt);
-	if (cutAt === -1) return [href, ""];
-	return [href.slice(0, cutAt), href.slice(cutAt)];
-}
-/**
-* Slashless canonical form for path comparisons.
-*
-*   /cli           → /cli
-*   /cli/          → /cli
-*   /cli/?x=1#y    → /cli
-*   /              → /
-*   /guides/setup/ → /guides/setup
-*
-* Strips query and hash so callers can compare two hrefs that differ only
-* in their tail. Root stays `"/"` — that's identity, not a trailing-slash
-* artifact.
-*/
-function toRouteKey(href) {
-	const [pathname] = splitSuffix(href);
-	if (pathname.length <= 1) return pathname || "/";
-	return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
-}
-/**
-* Trailing-slash form for browser-facing hrefs to HTML document routes.
-* Preserves query and hash; root, external URLs, anchor-only hrefs, and
-* asset URLs (paths with a file extension) are returned unchanged.
-*
-*   /cli              → /cli/
-*   /cli/             → /cli/
-*   /cli#install      → /cli/#install
-*   /cli?v=1          → /cli/?v=1
-*   /                 → /
-*   /og/card.png      → /og/card.png        (asset, unchanged)
-*   /cli/index.md     → /cli/index.md       (asset, unchanged)
-*   https://x.com/a   → https://x.com/a     (external, unchanged)
-*   #anchor           → #anchor             (anchor-only, unchanged)
-*/
-function toBrowserHref(href) {
-	if (isAbsoluteUrl(href)) return href;
-	if (href.startsWith("#") || href.startsWith("?")) return href;
-	if (!href.startsWith("/")) return href;
-	const [pathname, suffix] = splitSuffix(href);
-	if (pathname === "/") return href;
-	if (hasFileExtension(pathname)) return href;
-	if (pathname.endsWith("/")) return href;
-	return `${pathname}/${suffix}`;
-}
-
 //#endregion
 //#region src/_internal/sidebar.ts
 const sortKeyByItem = /* @__PURE__ */ new WeakMap();
@@ -307,18 +201,44 @@ function joinHref(hrefPrefix, entryId) {
 	return toBrowserHref(canonicalEntryUrl(hrefPrefix.replace(/\/$/, ""), entryId));
 }
 function createLink(entry, currentPath, hrefPrefix = "") {
-	const href = joinHref(hrefPrefix, entry.id);
+	const internalHref = joinHref(hrefPrefix, entry.id);
 	const badge = entry.data.draft ? entry.data.sidebar?.badge ?? {
 		text: "Draft",
 		variant: "warning"
 	} : entry.data.sidebar?.badge;
+	const label = entry.data.sidebar?.label ?? entry.data.title;
+	const order = entry.data.sidebar?.order ?? Number.MAX_VALUE;
+	const externalLink = entry.data.external_link;
+	if (externalLink) {
+		if (isAbsoluteUrl(externalLink)) {
+			const ext = {
+				type: "external",
+				label,
+				href: externalLink,
+				badge,
+				order
+			};
+			sortKeyByItem.set(ext, entry.id);
+			return ext;
+		}
+		const link = {
+			type: "link",
+			label,
+			href: toBrowserHref(externalLink),
+			isCurrent: false,
+			badge,
+			order
+		};
+		sortKeyByItem.set(link, entry.id);
+		return link;
+	}
 	const link = {
 		type: "link",
-		label: entry.data.sidebar?.label ?? entry.data.title,
-		href,
-		isCurrent: toRouteKey(currentPath) === toRouteKey(href),
+		label,
+		href: internalHref,
+		isCurrent: toRouteKey(currentPath) === toRouteKey(internalHref),
 		badge,
-		order: entry.data.sidebar?.order ?? Number.MAX_VALUE
+		order
 	};
 	sortKeyByItem.set(link, entry.id);
 	return link;
@@ -329,8 +249,13 @@ function buildFilesystemTree(entries, currentPath, directory, hrefPrefix = "") {
 	function buildLevel(parentPath) {
 		const result = [];
 		const groupsAtLevel = /* @__PURE__ */ new Map();
+		if (directory && parentPath === directory) {
+			const dirIndex = byId.get(directory);
+			if (dirIndex) result.push(createLink(dirIndex, currentPath, hrefPrefix));
+		}
 		for (const entry of scoped) {
 			if (entry.id === "index") continue;
+			if (entry.id === directory) continue;
 			const id = entry.id;
 			const relativeTo = directory ?? "";
 			const relativeId = relativeTo ? id === relativeTo ? "" : id.slice(relativeTo.length + 1) : id;
@@ -375,26 +300,40 @@ function buildFilesystemTree(entries, currentPath, directory, hrefPrefix = "") {
 		for (const [groupPath, group] of groupsAtLevel) {
 			const nestedChildren = buildLevel(groupPath);
 			group.children = [...group.children, ...nestedChildren].sort(sortSidebarItems);
-			if (group.children.length > 0) {
-				const minChildOrder = Math.min(...group.children.map((item) => item.order));
-				group.order = Math.min(group.order, minChildOrder);
-			}
+			if (group.order === Number.MAX_VALUE && group.children.length > 0) group.order = Math.min(...group.children.map((item) => item.order));
 		}
 		return result.sort(sortSidebarItems);
 	}
 	function createGroupFromEntry(dirPath, indexEntry, currentPath, _byId) {
 		const dirSegment = dirPath.split("/").pop();
-		const groupLabel = indexEntry?.data.sidebar?.label ?? formatLabel(dirSegment);
+		const groupConfig = indexEntry?.data.sidebar?.group;
+		const groupLabel = groupConfig?.label ?? indexEntry?.data.sidebar?.label ?? indexEntry?.data.title ?? formatLabel(dirSegment);
 		const groupOrder = indexEntry?.data.sidebar?.order ?? Number.MAX_VALUE;
-		const children = [];
-		if (indexEntry) children.push(createLink(indexEntry, currentPath, hrefPrefix));
+		const groupBadge = groupConfig?.badge ?? indexEntry?.data.sidebar?.badge;
+		let indexHref;
+		let indexIsCurrent = false;
+		let indexIsExternal = false;
+		if (indexEntry) {
+			const externalLink = indexEntry.data.external_link;
+			if (externalLink !== void 0) if (isAbsoluteUrl(externalLink)) {
+				indexHref = externalLink;
+				indexIsExternal = true;
+			} else indexHref = toBrowserHref(externalLink);
+			else {
+				indexHref = joinHref(hrefPrefix, indexEntry.id);
+				indexIsCurrent = toRouteKey(currentPath) === toRouteKey(indexHref);
+			}
+		}
 		const group = {
 			type: "group",
 			label: groupLabel,
 			order: groupOrder,
-			badge: indexEntry?.data.sidebar?.badge,
-			children,
-			_indexId: indexEntry?.id
+			badge: groupBadge,
+			children: [],
+			_indexId: indexEntry?.id,
+			indexHref,
+			indexIsCurrent: indexIsCurrent || void 0,
+			indexIsExternal: indexIsExternal || void 0
 		};
 		sortKeyByItem.set(group, dirPath);
 		return group;
@@ -494,45 +433,80 @@ function resolveConfigItems(configItems, entriesByCollection, primaryCollection,
 * Return only the children of the top-level group containing the current
 * page. Falls back to the full tree if the current page isn't inside any
 * group (e.g. a top-level link, or a path that doesn't resolve).
+*
+* Under structural separation the group's landing page lives on
+* `indexHref` rather than in `children`. When the active group has a
+* landing, we prepend a synthetic link (or external item) for it so
+* the section landing remains reachable from the scoped rail — without
+* this, on `/api/` the rail shows `/api/users`, `/api/orders`, … but
+* the section's own overview page would be missing from the rail.
 */
 function scopeToCurrentSection(items, currentPath) {
 	if (!currentPath.split("/").filter(Boolean)[0]) return items;
 	for (const item of items) if (item.type === "group") {
-		if (hasActivePage(item, currentPath)) return item.children;
+		if (hasActivePage(item, currentPath)) {
+			if (!item.indexHref) return item.children;
+			return [item.indexIsExternal ? {
+				type: "external",
+				label: item.label,
+				href: item.indexHref,
+				badge: item.badge,
+				order: Number.NEGATIVE_INFINITY
+			} : {
+				type: "link",
+				label: item.label,
+				href: item.indexHref,
+				isCurrent: item.indexIsCurrent === true,
+				badge: item.badge,
+				order: Number.NEGATIVE_INFINITY
+			}, ...item.children];
+		}
 	}
 	return items;
 }
 function hasActivePage(item, currentPath) {
 	if (item.type === "link") return item.isCurrent === true;
 	if (item.type === "external") return false;
+	if (item.indexIsCurrent === true) return true;
 	return item.children.some((child) => hasActivePage(child, currentPath));
 }
 /**
-* Derive one section per top-level group in the sidebar tree. Used by
-* `Header.astro` to render the section tab strip. Caller must pass the
-* *un-scoped* tree (the result of `buildSidebarTree`, not `getSidebar`);
-* otherwise only the current section's children are visible and the
-* derivation collapses to a single item.
+* Derive one section per top-level group in the sidebar tree, scoped
+* to *cross-collection* navigation. Used by `Header.astro` to render
+* the section tab strip.
+*
+* Filter rule: only groups whose `_prefix` is set become sections. The
+* `_prefix` field is populated exclusively by `autogenerate: { collection: <non-primary> }`
+* config items (see `resolveConfigItems`). This is the structural
+* signal that the group represents a *separate collection mounted at a
+* URL prefix* — e.g. `Components` mounted at `/components/` —
+* rather than a sub-directory of the primary docs collection.
+*
+* Why this matters: under the previous unconditional behavior, every
+* top-level group in the sidebar (including `wip/`, `lab/`, and other
+* docs-collection subdirectories) was promoted to a header tab. The
+* header rail is meant for "other collections" navigation, not for
+* sub-sections of the default collection — those belong in the
+* sidebar's own collapsible tree.
+*
+* Caller must pass the *un-scoped* tree (the result of
+* `buildSidebarTree`, not `getSidebar`); otherwise only the current
+* section's children are visible and the derivation collapses to a
+* single item.
 */
 function deriveSidebarSections(items) {
 	return items.flatMap((item) => {
 		if (item.type !== "group") return [];
-		const links = flattenLinks(item.children);
+		if (!item._prefix) return [];
+		const links = flattenSidebar(item.children);
 		if (links.length === 0) return [];
 		return [{
 			label: item.label,
-			href: toBrowserHref(item._prefix ?? links[0].href),
+			href: toBrowserHref(item._prefix),
 			isActive: links.some((link) => link.isCurrent === true)
 		}];
 	});
 }
-/** Depth-first walk; collect every internal link descendant. */
-function flattenLinks(items) {
-	const out = [];
-	for (const item of items) if (item.type === "link") out.push(item);
-	else if (item.type === "group") out.push(...flattenLinks(item.children));
-	return out;
-}
 /**
 * Build the un-scoped sidebar tree from config + content entries.
 *
@@ -557,11 +531,54 @@ function buildSidebarTree(entriesByCollection, primaryCollection, currentPath, c
 	else items = buildFilesystemTree(primaryEntries, currentPath, void 0, primaryPrefix);
 	const pooledEntries = Object.values(entriesByCollection).flat();
 	items = processHideChildren(items, pooledEntries);
+	if (config?.overviewLabel) {
+		const label = typeof config.overviewLabel === "string" ? config.overviewLabel : "Overview";
+		items = applyOverviewLabel(items, label);
+	}
+	if (config?.defaultCollapsed) applyDefaultCollapsed(items);
+	return items;
+}
+/**
+* Walk every group and stamp `collapsed: true` where no explicit value
+* was set. Used by the `sidebar.defaultCollapsed` opt-in. Recurses into
+* nested children so a deeply-structured tree collapses at every level.
+*/
+function applyDefaultCollapsed(items) {
+	for (const item of items) if (item.type === "group") {
+		if (item.collapsed === void 0) item.collapsed = true;
+		applyDefaultCollapsed(item.children);
+	}
+}
+/**
+* @deprecated Effective no-op under structural separation. Pre-2026
+* Nimbus rendered the group's index as the first child link and used
+* this to rename that link to "Overview". The index is now exposed via
+* `SidebarGroupItem.indexHref` (the group label IS the link), so there's
+* no first-child index to rename. The function is kept so older configs
+* that set `sidebar.overviewLabel` don't blow up; future major can drop it.
+*
+* Renamed only when the first link IS the group's index (matched via the
+* `sortKeyByItem` WeakMap) — under structural separation that condition
+* never holds, so this silently returns the input unchanged.
+*/
+function applyOverviewLabel(items, label) {
+	for (const item of items) if (item.type === "group") {
+		if (item._indexId) {
+			const firstLink = item.children.find((child) => child.type === "link");
+			if (firstLink && sortKeyByItem.get(firstLink) === item._indexId) firstLink.label = label;
+		}
+		applyOverviewLabel(item.children, label);
+	}
 	return items;
 }
 /**
-* Process hideChildren: replace groups whose index has hideChildren=true
-* with a single link to the index page.
+* Process `sidebar.hideChildren: true` on a group's index entry:
+* replace the entire group with a single flat link to the index page.
+*
+* Under structural separation the group already exposes its landing
+* page via `indexHref` and never adds the index as a child, so this
+* function reads `indexHref` directly when collapsing — no need to
+* search through `children` for an index link that isn't there.
 */
 function processHideChildren(items, entries) {
 	const entryById = /* @__PURE__ */ new Map();
@@ -573,18 +590,25 @@ function processHideChildren(items, entries) {
 				result.push(item);
 				continue;
 			}
-			if (item._indexId) {
+			if (item._indexId && item.indexHref) {
 				if (entryById.get(item._indexId)?.data.sidebar?.hideChildren) {
-					const indexKey = toRouteKey(canonicalEntryUrl("", item._indexId));
-					const indexLink = item.children.find((c) => c.type === "link" && toRouteKey(c.href) === indexKey);
-					if (indexLink) {
-						const link = {
-							...indexLink,
-							label: item.label
-						};
-						result.push(link);
-						continue;
-					}
+					const replacement = item.indexIsExternal ? {
+						type: "external",
+						label: item.label,
+						href: item.indexHref,
+						badge: item.badge,
+						order: item.order
+					} : {
+						type: "link",
+						label: item.label,
+						href: item.indexHref,
+						isCurrent: item.indexIsCurrent === true,
+						badge: item.badge,
+						order: item.order
+					};
+					sortKeyByItem.set(replacement, item._indexId);
+					result.push(replacement);
+					continue;
 				}
 			}
 			item.children = process(item.children);
@@ -618,11 +642,33 @@ function collectSidebarCollectionRefs(items) {
 	walk(items);
 	return [...found];
 }
-/** Flatten sidebar tree into a list of links (for pagination) */
+/**
+* Flatten sidebar tree into a list of links (for pagination).
+*
+* Groups with a landing page (`indexHref` set; structural-separation
+* model) contribute a synthetic link at the group's position so that
+* `getPrevNext` includes the directory-index page in the prev/next
+* walk. Without this, navigating *to* or *from* a group's index page
+* skips it entirely (e.g. on `/api/`, "prev" jumps over the section
+* landing to the previous group's last child).
+*
+* External landing pages (`indexIsExternal`) are excluded — they're
+* off-site destinations, not part of the in-site pagination ring.
+*/
 function flattenSidebar(items) {
 	const flat = [];
 	for (const item of items) if (item.type === "link") flat.push(item);
-	else if (item.type === "group") flat.push(...flattenSidebar(item.children));
+	else if (item.type === "group") {
+		if (item.indexHref && !item.indexIsExternal) flat.push({
+			type: "link",
+			label: item.label,
+			href: item.indexHref,
+			isCurrent: item.indexIsCurrent === true,
+			badge: item.badge,
+			order: item.order
+		});
+		flat.push(...flattenSidebar(item.children));
+	}
 	return flat;
 }
 function formatLabel(segment) {
@@ -969,6 +1015,131 @@ async function getLastUpdatedFromGit(filePath) {
 	return result;
 }
 
+//#endregion
+//#region src/_internal/admonition-transform.ts
+/** Built-in MyST / Docusaurus / CF admonition types and their Aside mapping. */
+const BUILTIN_TYPES = {
+	note: "note",
+	info: "note",
+	tip: "tip",
+	caution: "caution",
+	warning: "caution",
+	important: "caution",
+	danger: "danger"
+};
+/**
+* Transform a single MDX source string. Idempotent — running the
+* transform twice produces the same output as running it once.
+*/
+function transformAdmonitions(source, options = {}) {
+	const typeMap = {
+		...BUILTIN_TYPES,
+		...options.typeAliases ?? {}
+	};
+	const { frontmatter, body, bodyOffset: _ } = splitFrontmatter(source);
+	const { stashed, restore } = stashCodeBlocks(body);
+	return frontmatter + restore(stashed.replace(ADMONITION_PATTERN, (match, rawType, rawTitle, rawContent) => {
+		const aside = typeMap[String(rawType).toLowerCase()];
+		if (!aside) return match;
+		const title = typeof rawTitle === "string" ? rawTitle.trim() : "";
+		const content = String(rawContent).trim();
+		return `\n\n<Aside type="${aside}"${title ? ` title=${JSON.stringify(title)}` : ""}>\n\n${content}\n\n</Aside>\n\n`;
+	}));
+}
+/**
+* Match `:::type[optional title] body :::` with non-greedy body.
+*
+* Components:
+*   - `:::`           literal opener
+*   - `([a-zA-Z]+)`   type token (captured, case-insensitive lookup at use site)
+*   - `(?:\[(...)\])?` optional bracketed title; brackets stripped from capture
+*   - `\s+|\n`        at least one whitespace before content (avoids matching
+*                      `:::foo:::` directly)
+*   - `([\s\S]*?)`    non-greedy body, may span newlines
+*   - `\n?\s*:::`     closer, possibly with leading whitespace
+*
+* Non-greedy body + global flag means adjacent admonitions don't merge
+* (the engine finds the *nearest* `:::` closer for each opener).
+*/
+const ADMONITION_PATTERN = /:::([a-zA-Z]+)(?:\[([^\]]*)\])?[ \t]*(?:\n|[ \t]+)([\s\S]*?)\n?[ \t]*:::/g;
+function splitFrontmatter(source) {
+	const match = source.match(/^---\n[\s\S]*?\n---\n?/);
+	if (!match) return {
+		frontmatter: "",
+		body: source,
+		bodyOffset: 0
+	};
+	return {
+		frontmatter: match[0],
+		body: source.slice(match[0].length),
+		bodyOffset: match[0].length
+	};
+}
+/**
+* Replace fenced code blocks with opaque placeholders so the admonition
+* regex doesn't reach `:::` tokens inside code samples. The `restore()`
+* function reinstates the originals after the transform.
+*
+* Order matters: stash the longest fence flavors first (``` and ~~~)
+* so the placeholders themselves don't get re-stashed. Inline backtick
+* code spans are NOT stashed — a `:::` inside a single-line `code` span
+* is rare and would have to be on the same line as both fences anyway.
+*/
+function stashCodeBlocks(body) {
+	const blocks = [];
+	const PLACEHOLDER = "\0NIMBUS_CODEBLOCK_";
+	const PLACEHOLDER_END = "\0";
+	const stashed = body.replace(/```[\s\S]*?```|~~~[\s\S]*?~~~/g, (match) => {
+		const index = blocks.length;
+		blocks.push(match);
+		return `${PLACEHOLDER}${index}${PLACEHOLDER_END}`;
+	});
+	function restore(src) {
+		return src.replace(new RegExp(`${PLACEHOLDER}(\\d+)${PLACEHOLDER_END}`, "g"), (_match, index) => blocks[Number(index)] ?? "");
+	}
+	return {
+		stashed,
+		restore
+	};
+}
+
+//#endregion
+//#region src/_internal/admonition-vite-plugin.ts
+/**
+* Vite plugin: intercept `.mdx` (and `.md`) loads under the project's
+* content directories, rewrite `:::admonition` directives to `<Aside>`
+* components, hand the transformed source to the next loader in the
+* chain. Sits in front of @astrojs/mdx and Sätteri.
+*
+* `enforce: "pre"` is load-bearing — the MDX integration's own transform
+* registers without an `enforce` and runs in the default mid-pipeline
+* slot. Pre-stage runs before that, so by the time MDX parses the file,
+* the directive syntax has already been rewritten to JSX.
+*
+* Scope is restricted to the project's content directories so we don't
+* touch unrelated `.md` files in `node_modules/` or vendored MDX.
+*/
+function admonitionPlugin(options) {
+	const normalizedDirs = options.contentDirs.map((d) => path.resolve(d));
+	return {
+		name: "nimbus-docs:admonitions",
+		enforce: "pre",
+		transform(code, id) {
+			const [pathOnly] = id.split("?", 1);
+			if (!pathOnly) return null;
+			if (!pathOnly.endsWith(".mdx") && !pathOnly.endsWith(".md")) return null;
+			const absolute = path.resolve(pathOnly);
+			if (!normalizedDirs.some((dir) => absolute === dir || absolute.startsWith(dir + path.sep))) return null;
+			if (options.skip?.(absolute)) return null;
+			if (!code.includes(":::")) return null;
+			return {
+				code: transformAdmonitions(code, { typeAliases: options.typeAliases }),
+				map: null
+			};
+		}
+	};
+}
+
 //#endregion
 //#region src/_internal/parse-components-registry.ts
 /**
@@ -1764,7 +1935,7 @@ function parseImports(body) {
 * inside code samples doesn't trip the validator.
 */
 function stripCodeBlocks(body) {
-	return body.replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length)).replace(/~~~[\s\S]*?~~~/g, (m) => " ".repeat(m.length)).replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length));
+	return body.replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length)).replace(/~~~[\s\S]*?~~~/g, (m) => " ".repeat(m.length)).replace(/`[^`\n]*`/g, (m) => " ".repeat(m.length)).replace(/=\s*"[^"\n]*"/g, (m) => "=" + " ".repeat(m.length - 1)).replace(/=\s*'[^'\n]*'/g, (m) => "=" + " ".repeat(m.length - 1));
 }
 /**
 * Find PascalCase JSX-like tags. Matches `<Capital...` at the start of
@@ -1811,8 +1982,11 @@ const headElementSchema = z.object({
 		"meta",
 		"link",
 		"script",
-		"style"
-	]),
+		"style",
+		"title",
+		"noscript",
+		"base"
+	], { error: "head element \"tag\" must be one of: meta, link, script, style, title, noscript, base" }),
 	attrs: z.record(z.string(), z.string()).default({}),
 	content: z.string().optional()
 });
@@ -2409,22 +2583,38 @@ function nimbus(rawConfig, options = {}) {
 				}
 				integrationsToAdd.push(mdx(options.mdx ?? {}));
 				if (options.sitemap !== false && Boolean(config.site)) integrationsToAdd.push(sitemap());
+				const admonitionVitePlugins = [];
+				if (options.admonitions !== false) {
+					const admoOpts = typeof options.admonitions === "object" ? options.admonitions : {};
+					const projectRoot = fileURLToPath(astroConfig.root);
+					const contentDirs = (admoOpts.contentDirs ?? ["src/content"]).map((d) => path.isAbsolute(d) ? d : path.join(projectRoot, d));
+					admonitionVitePlugins.push(admonitionPlugin({
+						contentDirs,
+						typeAliases: admoOpts.typeAliases,
+						skip: admoOpts.skip
+					}));
+				}
 				updateConfig({
 					...config.site ? { site: config.site } : {},
 					integrations: integrationsToAdd,
 					markdown: {
-						processor: satteri(),
+						processor: options.markdown?.processor ?? satteri(),
 						shikiConfig: {
 							themes: {
 								light: "github-light",
 								dark: "github-dark"
 							},
 							defaultColor: false,
-							transformers: defaultCodeTransformers()
+							transformers: defaultCodeTransformers(),
+							langAlias: {
+								curl: "bash",
+								console: "bash",
+								shellsession: "shellscript"
+							}
 						}
 					},
 					...versionRedirects.length > 0 ? { redirects: Object.fromEntries(versionRedirects.map(({ from, to }) => [from, to])) } : {},
-					vite: { plugins: [virtualConfigPlugin(config, {
+					vite: { plugins: [...admonitionVitePlugins, virtualConfigPlugin(config, {
 						indexedCollections,
 						versionAlternates
 					})] }