mdsvr 2.4.0 → 2.5.0

package/dist/seo/extract.js

@@ -0,0 +1,159 @@
+/**
+ * Content extraction helpers for SEO metadata.
+ * (Moved from renderer/markdown.ts; description extraction is wired so it
+ * actually runs, and tightened to ~160 chars.)
+ */
+function stripFrontmatter(content) {
+    return content.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
+}
+function stripFencedCode(content) {
+    return content
+        .replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1\s*$/gm, "")
+        .replace(/(`{3,}|~{3,})[\s\S]*?\1/g, "");
+}
+function decodeEntities(text) {
+    const entities = {
+        "&": "&",
+        "&lt;": "<",
+        "&gt;": ">",
+        "&quot;": '"',
+        "&#39;": "'",
+        "&#x27;": "'",
+        "&nbsp;": " ",
+    };
+    return text.replace(/&(amp|lt|gt|quot|nbsp|#39|#x27);/g, (m) => entities[m] || m);
+}
+/** Strip inline markdown/HTML so only plain text remains. */
+function cleanInline(text) {
+    return decodeEntities(text
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images → alt text
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links → text
+        .replace(/\[([^\]]+)\]\[[^\]]*\]/g, "$1") // ref links → text
+        .replace(/<[^>]+>/g, "") // HTML tags
+        .replace(/(\*\*|__)(.*?)\1/g, "$2") // bold
+        .replace(/\*([^*]+)\*/g, "$1") // italic
+        // _italic_ — only at word boundaries so SNAKE_CASE identifiers survive
+        .replace(/(^|\W)_([^_]+)_(?=\W|$)/g, "$1$2")
+        .replace(/~~([^~]+)~~/g, "$1") // strikethrough
+        .replace(/`([^`]+)`/g, "$1") // inline code
+        .replace(/\s+/g, " ")
+        .trim());
+}
+/**
+ * Whether a trimmed line can never begin a meaningful paragraph
+ * (headings, lists, tables, blockquotes, HTML, MDX statements, nav links).
+ */
+function isSkippableLine(line) {
+    if (/^#{1,6}\s/.test(line))
+        return true; // heading
+    if (/^>/.test(line))
+        return true; // blockquote
+    if (/^[-*_]{3,}$/.test(line))
+        return true; // horizontal rule
+    if (/^[-*+]\s/.test(line))
+        return true; // bullet list
+    if (/^\d+\.\s/.test(line))
+        return true; // ordered list
+    if (/^\|/.test(line))
+        return true; // table row
+    const c = line[0];
+    if (c === "`" || c === "~")
+        return true; // fence remnants
+    if (c === "<")
+        return true; // HTML block/tag line
+    if (c === "!")
+        return true; // image
+    if (c === "[")
+        return true; // bare link / link reference (nav-like)
+    if (c === ":" || c === "{" || c === "}" || c === "=")
+        return true; // containers/MDX
+    if (/^(import|export)\s/.test(line))
+        return true; // MDX statements
+    if (/^\/\//.test(line))
+        return true; // JS-style comments
+    return false;
+}
+/** Truncate on a word boundary near `soft`, never exceeding `hard`. */
+function truncate(text, soft, hard) {
+    if (text.length <= soft)
+        return text;
+    const window = text.slice(0, soft);
+    const boundary = window.lastIndexOf(" ");
+    let out = boundary > 40 ? window.slice(0, boundary) : text.slice(0, hard - 3);
+    if (out.length > hard - 3)
+        out = out.slice(0, hard - 3);
+    return `${out.trimEnd()}...`;
+}
+/**
+ * Extract the first H1 heading from markdown content (for SEO title fallback).
+ */
+export function extractFirstHeading(content) {
+    const body = stripFencedCode(stripFrontmatter(content));
+    const match = body.match(/^#[ \t]+(.+?)[ \t]*#*[ \t]*$/m);
+    return match ? cleanInline(match[1]) || null : null;
+}
+/** Descriptions shorter than this are treated as degenerate — keep scanning. */
+const MIN_DESCRIPTION_LENGTH = 40;
+/**
+ * Whether a line is a bare label like `**Làm gì:**` or `Functional:` —
+ * markdown emphasis that cleans to a short colon-terminated string.
+ */
+function isLabelOnly(line) {
+    const text = cleanInline(line);
+    return (text.length > 0 &&
+        text.length <= MIN_DESCRIPTION_LENGTH &&
+        text.endsWith(":"));
+}
+/**
+ * Extract the first meaningful paragraph from markdown content
+ * (for the meta description fallback). Skips frontmatter, code blocks,
+ * headings, HTML, comments, and nav-like lines; drops label-only lines;
+ * requires ~40 chars of real prose (shorter paragraphs are kept only as a
+ * last resort); collapses whitespace; cuts at ~160 chars on a word
+ * boundary (hard cap 200).
+ */
+export function extractFirstParagraph(content) {
+    let body = stripFrontmatter(content);
+    body = stripFencedCode(body);
+    body = body.replace(/<!--[\s\S]*?-->/g, "");
+    let fallback = null;
+    let paraLines = [];
+    // Evaluate the accumulated paragraph: returns a qualifying description,
+    // records a shorter candidate as fallback, or null if the block is empty.
+    const flush = () => {
+        if (paraLines.length === 0)
+            return null;
+        const kept = paraLines.filter((l) => !isLabelOnly(l));
+        paraLines = [];
+        const text = cleanInline(kept.join(" "));
+        if (!text)
+            return null;
+        if (text.length >= MIN_DESCRIPTION_LENGTH)
+            return truncate(text, 160, 200);
+        if (!fallback || text.length > fallback.length)
+            fallback = text;
+        return null;
+    };
+    for (const rawLine of body.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || isSkippableLine(line)) {
+            const result = flush();
+            if (result)
+                return result;
+            continue;
+        }
+        paraLines.push(line);
+    }
+    const result = flush();
+    return result ?? (fallback ? truncate(fallback, 160, 200) : null);
+}
+/**
+ * Extract SEO data (title + description) from markdown content.
+ */
+export function extractSeoData(content) {
+    return {
+        title: extractFirstHeading(content),
+        description: extractFirstParagraph(content),
+    };
+}
+//# sourceMappingURL=extract.js.map

package/dist/seo/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/seo/extract.ts"],"names":[],"mappings":"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"}

package/dist/seo/index.d.ts

@@ -0,0 +1,5 @@
+export { normalizeUrlPath, normalizeBasePath, buildPageUrl, buildSiteUrl, toAbsoluteAssetUrl, } from "./url.js";
+export { extractFirstHeading, extractFirstParagraph, extractSeoData, } from "./extract.js";
+export { resolveSeoData, formatPageTitle, type SeoData, type SeoAuthor, type SeoBreadcrumb, type PageKind, type ResolveSeoInput, } from "./metadata.js";
+export { buildJsonLd } from "./jsonld.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/seo/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seo/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/seo/index.js

@@ -0,0 +1,5 @@
+export { normalizeUrlPath, normalizeBasePath, buildPageUrl, buildSiteUrl, toAbsoluteAssetUrl, } from "./url.js";
+export { extractFirstHeading, extractFirstParagraph, extractSeoData, } from "./extract.js";
+export { resolveSeoData, formatPageTitle, } from "./metadata.js";
+export { buildJsonLd } from "./jsonld.js";
+//# sourceMappingURL=index.js.map

package/dist/seo/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/seo/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,eAAe,GAMhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/seo/jsonld.d.ts

@@ -0,0 +1,15 @@
+import type { Settings } from "../settings/index.js";
+import type { SeoData } from "./metadata.js";
+/**
+ * Build the JSON-LD `<script>` tag for a page.
+ *
+ * - Homepage → `WebSite`
+ * - Document pages → `Article`
+ * - Nested routes → `BreadcrumbList`
+ *
+ * Fields are only emitted when real data exists (no invented dates).
+ * Returns an empty string when `seo.structuredData` is off or there is
+ * nothing worth emitting.
+ */
+export declare function buildJsonLd(seo: SeoData, settings: Settings): string;
+//# sourceMappingURL=jsonld.d.ts.map

package/dist/seo/jsonld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonld.d.ts","sourceRoot":"","sources":["../../src/seo/jsonld.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA0EpE"}

package/dist/seo/jsonld.js

@@ -0,0 +1,93 @@
+import { buildPageUrl, buildSiteUrl, toAbsoluteAssetUrl } from "./url.js";
+/**
+ * Build the JSON-LD `<script>` tag for a page.
+ *
+ * - Homepage → `WebSite`
+ * - Document pages → `Article`
+ * - Nested routes → `BreadcrumbList`
+ *
+ * Fields are only emitted when real data exists (no invented dates).
+ * Returns an empty string when `seo.structuredData` is off or there is
+ * nothing worth emitting.
+ */
+export function buildJsonLd(seo, settings) {
+    if (!settings.seo.structuredData)
+        return "";
+    const graph = [];
+    if (seo.kind !== "generic" && seo.urlPath === "/") {
+        const site = {
+            "@type": "WebSite",
+            name: settings.site.title || seo.title,
+        };
+        const url = buildSiteUrl(settings);
+        if (url)
+            site.url = url;
+        const description = seo.description || settings.site.description;
+        if (description)
+            site.description = description;
+        // Sitelinks search box — client-side search reads the `q` query param.
+        if (settings.search.enabled && url) {
+            site.potentialAction = {
+                "@type": "SearchAction",
+                target: {
+                    "@type": "EntryPoint",
+                    urlTemplate: `${url.replace(/\/+$/, "")}/?q={search_term_string}`,
+                },
+                "query-input": "required name=search_term_string",
+            };
+        }
+        graph.push(site);
+    }
+    else if (seo.kind === "document" && seo.type === "article") {
+        const article = {
+            "@type": "Article",
+            headline: seo.title,
+        };
+        if (seo.description)
+            article.description = seo.description;
+        if (seo.absoluteUrl)
+            article.url = seo.absoluteUrl;
+        if (seo.image) {
+            const image = toAbsoluteAssetUrl(seo.image, settings);
+            if (image)
+                article.image = image;
+        }
+        if (seo.author) {
+            article.author = {
+                "@type": seo.author.type,
+                name: seo.author.name,
+                ...(seo.author.url ? { url: seo.author.url } : {}),
+            };
+        }
+        if (seo.datePublished)
+            article.datePublished = seo.datePublished;
+        if (seo.dateModified)
+            article.dateModified = seo.dateModified;
+        graph.push(article);
+    }
+    if (seo.breadcrumbs.length > 1) {
+        graph.push({
+            "@type": "BreadcrumbList",
+            itemListElement: seo.breadcrumbs.map((crumb, i) => {
+                const item = {
+                    "@type": "ListItem",
+                    position: i + 1,
+                    name: crumb.name,
+                };
+                const url = buildPageUrl(crumb.urlPath, settings);
+                if (url)
+                    item.item = url;
+                return item;
+            }),
+        });
+    }
+    if (graph.length === 0)
+        return "";
+    // `<\/` escaping prevents a literal `</script>` from breaking the tag.
+    const json = JSON.stringify({
+        "@context": "https://schema.org",
+        "@graph": graph,
+    }).replace(/<\//g, "<\\/");
+    return `<script type="application/ld+json">${json}</script>`;
+}
+//# sourceMappingURL=jsonld.js.map

package/dist/seo/jsonld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonld.js","sourceRoot":"","sources":["../../src/seo/jsonld.ts"],"names":[],"mappings":"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"}

package/dist/seo/metadata.d.ts

@@ -0,0 +1,60 @@
+import type { Settings } from "../settings/index.js";
+import type { NavItem } from "../template/sidebar.js";
+export type PageKind = "document" | "directory" | "generic";
+export interface SeoAuthor {
+    name: string;
+    url?: string;
+    type: "Person" | "Organization";
+}
+export interface SeoBreadcrumb {
+    name: string;
+    urlPath: string;
+}
+export interface SeoData {
+    /** Resolved page title (before `seo.titleTemplate`). */
+    title: string;
+    description?: string;
+    image?: string;
+    /** Pixel dimensions, set only for generated OG images (known size). */
+    imageWidth?: number;
+    imageHeight?: number;
+    /** Absolute canonical URL, or null when no `site.baseUrl` is configured. */
+    absoluteUrl: string | null;
+    /** Normalized trailing-slash route. */
+    urlPath: string;
+    type: "website" | "article";
+    kind: PageKind;
+    datePublished?: string;
+    dateModified?: string;
+    author?: SeoAuthor;
+    noIndex: boolean;
+    /** Home → ancestors → current page (empty when disabled or at root). */
+    breadcrumbs: SeoBreadcrumb[];
+    /** Root-relative sitemap URL, or null when it should not be advertised. */
+    sitemapUrl: string | null;
+}
+export interface ResolveSeoInput {
+    frontmatter?: Record<string, unknown>;
+    /** Raw markdown/MDX source for description auto-extraction. */
+    content?: string;
+    /** Display title resolved by the caller (frontmatter → H1 → filename). */
+    title: string;
+    urlPath?: string;
+    kind?: PageKind;
+    settings: Settings;
+    sidebar?: NavItem[];
+    isStaticExport?: boolean;
+}
+/**
+ * Apply `seo.titleTemplate` to a page title. When the template is unset,
+ * defaults to `"<title> | <site title>"` (or the bare title when the site
+ * has no title).
+ */
+export declare function formatPageTitle(pageTitle: string, settings: Settings): string;
+/**
+ * Resolve all SEO metadata for a page from frontmatter, content, and
+ * settings. Centralizes the frontmatter → extracted → site-defaults chain
+ * so templates and generators share one source of truth.
+ */
+export declare function resolveSeoData(input: ResolveSeoInput): SeoData;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/seo/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/seo/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAMtD,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,cAAc,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAyDD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAa7E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAsF9D"}

package/dist/seo/metadata.js

@@ -0,0 +1,144 @@
+import { getOgImageUrl } from "../og/index.js";
+import { OG_WIDTH, OG_HEIGHT } from "../og/template.js";
+import { extractFirstParagraph } from "./extract.js";
+import { buildPageUrl, normalizeBasePath, normalizeUrlPath } from "./url.js";
+function str(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const s = value.trim();
+    return s || undefined;
+}
+function toIsoDate(value) {
+    if (value == null || value === "")
+        return undefined;
+    const d = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(d.getTime()) ? undefined : d.toISOString().split("T")[0];
+}
+function resolveAuthor(author) {
+    if (typeof author === "string") {
+        const name = author.trim();
+        return name ? { name, type: "Person" } : undefined;
+    }
+    if (author && typeof author === "object") {
+        const obj = author;
+        const name = str(obj.name);
+        if (!name)
+            return undefined;
+        const type = obj.type === "Organization" ? "Organization" : "Person";
+        return { name, url: str(obj.url), type };
+    }
+    return undefined;
+}
+function humanizeSegment(segment) {
+    let decoded = segment;
+    try {
+        decoded = decodeURIComponent(segment);
+    }
+    catch {
+        // Keep the raw segment when it is not valid percent-encoding
+    }
+    return decoded
+        .replace(/^\d+\./, "")
+        .replace(/[-_]/g, " ")
+        .replace(/\.\w+$/, "")
+        .trim()
+        .replace(/^\w/, (c) => c.toUpperCase());
+}
+function findNavTitle(items, urlPath) {
+    const target = urlPath.replace(/\/+$/, "") || "/";
+    for (const item of items) {
+        const href = item.href.replace(/\/+$/, "") || "/";
+        if (href === target)
+            return item.title;
+        if (item.children) {
+            const found = findNavTitle(item.children, urlPath);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * Apply `seo.titleTemplate` to a page title. When the template is unset,
+ * defaults to `"<title> | <site title>"` (or the bare title when the site
+ * has no title).
+ */
+export function formatPageTitle(pageTitle, settings) {
+    if (settings.seo.titleTemplate != null) {
+        return settings.seo.titleTemplate.replace("%s", pageTitle);
+    }
+    // Default: "<title> | <site title>"; skip the suffix when it would
+    // duplicate the site title (e.g. homepage H1 == site.title).
+    if (!settings.site.title ||
+        pageTitle.trim().toLowerCase() === settings.site.title.trim().toLowerCase()) {
+        return pageTitle;
+    }
+    return `${pageTitle} | ${settings.site.title}`;
+}
+/**
+ * Resolve all SEO metadata for a page from frontmatter, content, and
+ * settings. Centralizes the frontmatter → extracted → site-defaults chain
+ * so templates and generators share one source of truth.
+ */
+export function resolveSeoData(input) {
+    const { frontmatter = {}, content = "", title, settings, sidebar = [], isStaticExport = false, } = input;
+    const kind = input.kind ?? "document";
+    const urlPath = normalizeUrlPath(input.urlPath ?? "/");
+    const resolvedTitle = str(frontmatter.seoTitle) ?? title;
+    const description = str(frontmatter.description) ??
+        (content ? extractFirstParagraph(content) : null) ??
+        (settings.site.description || undefined);
+    const isHome = urlPath === "/";
+    const type = kind === "document" && !isHome ? "article" : "website";
+    let image = str(frontmatter.image);
+    let generatedOg = false;
+    if (!image && isStaticExport && settings.seo.og?.enabled) {
+        image = getOgImageUrl(urlPath, settings.generate.basePath || "", settings.seo.og.imageFormat);
+        generatedOg = true;
+    }
+    image ??= settings.seo.defaultImage;
+    const author = resolveAuthor(frontmatter.author) ??
+        (settings.site.author?.name
+            ? {
+                name: settings.site.author.name,
+                url: settings.site.author.url,
+                type: "Organization",
+            }
+            : undefined);
+    const breadcrumbs = [];
+    if (settings.navigation.breadcrumbs && !isHome && kind !== "generic") {
+        breadcrumbs.push({ name: "Home", urlPath: "/" });
+        const segments = urlPath.split("/").filter(Boolean);
+        let acc = "";
+        segments.forEach((segment, i) => {
+            acc += `/${segment}`;
+            const isLast = i === segments.length - 1;
+            const name = isLast
+                ? resolvedTitle
+                : (findNavTitle(sidebar, acc) ?? humanizeSegment(segment));
+            breadcrumbs.push({ name, urlPath: `${acc}/` });
+        });
+    }
+    const sitemapUrl = settings.seo.generateSitemap && !(isStaticExport && !settings.site.baseUrl)
+        ? `${normalizeBasePath(settings.generate.basePath)}/sitemap.xml`
+        : null;
+    return {
+        title: resolvedTitle,
+        description,
+        image,
+        imageWidth: generatedOg ? OG_WIDTH : undefined,
+        imageHeight: generatedOg ? OG_HEIGHT : undefined,
+        absoluteUrl: buildPageUrl(urlPath, settings),
+        urlPath,
+        type,
+        kind,
+        datePublished: toIsoDate(frontmatter.datePublished ?? frontmatter.date),
+        dateModified: toIsoDate(frontmatter.dateModified ?? frontmatter.updated ?? frontmatter.lastmod),
+        author,
+        noIndex: (frontmatter.noindex ?? frontmatter.noIndex) === true ||
+            (kind === "directory" && settings.seo.noIndexDirectoryPages),
+        breadcrumbs,
+        sitemapUrl,
+    };
+}
+//# sourceMappingURL=metadata.js.map

package/dist/seo/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/seo/metadata.ts"],"names":[],"mappings":"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"}

package/dist/seo/url.d.ts

@@ -0,0 +1,27 @@
+import type { Settings } from "../settings/index.js";
+/**
+ * Normalize a documentation route to its canonical form:
+ * leading `/`, trailing `/`, index/readme file names collapsed to the
+ * directory URL, `.md`/`.mdx` extensions stripped, `index.html` collapsed,
+ * and every path segment percent-encoded.
+ */
+export declare function normalizeUrlPath(urlPath: string): string;
+/** Normalize `generate.basePath` to `"/base"` form (empty when unset). */
+export declare function normalizeBasePath(basePath: string | undefined): string;
+/**
+ * Build the absolute URL for a documentation route.
+ * Returns `null` when no absolute base is available (`site.baseUrl`
+ * or an explicit request `origin`).
+ */
+export declare function buildPageUrl(urlPath: string, settings: Settings, origin?: string): string | null;
+/** Absolute site root URL (baseUrl + basePath + `/`), or `null`. */
+export declare function buildSiteUrl(settings: Settings, origin?: string): string | null;
+/**
+ * Resolve an image/asset reference to an absolute URL.
+ * Absolute http(s) URLs pass through. Site-relative paths are resolved
+ * against `site.baseUrl` + `generate.basePath` (a path that already starts
+ * with basePath is not prefixed twice). Returns `null` when the input is a
+ * relative path and no absolute base is configured.
+ */
+export declare function toAbsoluteAssetUrl(pathOrUrl: string, settings: Settings, origin?: string): string | null;
+//# sourceMappingURL=url.d.ts.map

package/dist/seo/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/seo/url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAItE;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAIf;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI/E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,GAAG,IAAI,CAef"}

package/dist/seo/url.js

@@ -0,0 +1,76 @@
+/**
+ * Normalize a documentation route to its canonical form:
+ * leading `/`, trailing `/`, index/readme file names collapsed to the
+ * directory URL, `.md`/`.mdx` extensions stripped, `index.html` collapsed,
+ * and every path segment percent-encoded.
+ */
+export function normalizeUrlPath(urlPath) {
+    let p = (urlPath || "/").split("?")[0].split("#")[0];
+    if (!p.startsWith("/"))
+        p = `/${p}`;
+    const segments = p.split("/").filter((s) => s.length > 0 && s !== ".");
+    const last = segments[segments.length - 1];
+    if (last) {
+        if (/^(readme|index)\.(md|mdx|html)$/i.test(last)) {
+            segments.pop();
+        }
+        else if (/\.(md|mdx)$/i.test(last)) {
+            segments[segments.length - 1] = last.replace(/\.(md|mdx)$/i, "");
+        }
+    }
+    const encoded = segments.map((s) => encodeURIComponent(s));
+    return `/${encoded.join("/")}${encoded.length ? "/" : ""}`;
+}
+/** Normalize `generate.basePath` to `"/base"` form (empty when unset). */
+export function normalizeBasePath(basePath) {
+    const bp = (basePath || "").trim();
+    if (!bp || bp === "/")
+        return "";
+    return `/${bp.replace(/^\/+|\/+$/g, "")}`;
+}
+function resolveBase(settings, origin) {
+    return (settings.site.baseUrl || origin || "").replace(/\/+$/, "");
+}
+/**
+ * Build the absolute URL for a documentation route.
+ * Returns `null` when no absolute base is available (`site.baseUrl`
+ * or an explicit request `origin`).
+ */
+export function buildPageUrl(urlPath, settings, origin) {
+    const base = resolveBase(settings, origin);
+    if (!base)
+        return null;
+    return `${base}${normalizeBasePath(settings.generate.basePath)}${normalizeUrlPath(urlPath)}`;
+}
+/** Absolute site root URL (baseUrl + basePath + `/`), or `null`. */
+export function buildSiteUrl(settings, origin) {
+    const base = resolveBase(settings, origin);
+    if (!base)
+        return null;
+    return `${base}${normalizeBasePath(settings.generate.basePath)}/`;
+}
+/**
+ * Resolve an image/asset reference to an absolute URL.
+ * Absolute http(s) URLs pass through. Site-relative paths are resolved
+ * against `site.baseUrl` + `generate.basePath` (a path that already starts
+ * with basePath is not prefixed twice). Returns `null` when the input is a
+ * relative path and no absolute base is configured.
+ */
+export function toAbsoluteAssetUrl(pathOrUrl, settings, origin) {
+    if (/^https?:\/\//i.test(pathOrUrl))
+        return pathOrUrl;
+    const siteUrl = buildSiteUrl(settings, origin);
+    if (!siteUrl)
+        return null;
+    let p = pathOrUrl.replace(/^\.\//, "").replace(/^\/+/, "");
+    const bp = normalizeBasePath(settings.generate.basePath).replace(/^\//, "");
+    if (bp && p.startsWith(`${bp}/`))
+        p = p.slice(bp.length + 1);
+    const encoded = p
+        .split("/")
+        .filter(Boolean)
+        .map(encodeURIComponent)
+        .join("/");
+    return `${siteUrl}${encoded}`;
+}
+//# sourceMappingURL=url.js.map

package/dist/seo/url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/seo/url.ts"],"names":[],"mappings":"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"}