@zudojs/docs 0.0.1 → 1.0.0

package/dist/frontmatter/frontmatter.serializer.js

@@ -1,26 +1,49 @@
 /**
  * Frontmatter serializer — converts metadata back to YAML-like format.
+ *
+ * Every value is quoted when it could otherwise be misread by the
+ * parser (newlines, `:`/`#`, leading list markers, surrounding
+ * whitespace, or text that looks like a number/boolean/null), so
+ * `parseFrontmatter(serializeFrontmatter(m, c))` round-trips `m`.
  */
 const FRONTMATTER_DELIMITER = "---";
+/** Keys that are never written. */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** Valid frontmatter key syntax (must match the parser). */
+const KEY_PATTERN = /^[A-Za-z_][\w.-]*$/;
 /**
  * Serializes metadata back into a frontmatter string.
+ *
+ * Nested plain objects are written as a one-level mapping; other
+ * non-scalar values (Dates, class instances) are written as their
+ * JSON/ISO representation in quotes. Keys that are not valid
+ * frontmatter keys are skipped.
  */
 export function serializeFrontmatter(metadata, content) {
     const lines = [FRONTMATTER_DELIMITER];
     for (const [key, value] of Object.entries(metadata)) {
         if (value === undefined || value === null)
             continue;
+        if (!isSerializableKey(key))
+            continue;
         if (Array.isArray(value)) {
             lines.push(`${key}:`);
             for (const item of value) {
-                lines.push(`  - ${item}`);
+                lines.push(`  - ${formatScalar(item)}`);
             }
         }
-        else if (typeof value === "boolean") {
-            lines.push(`${key}: ${value ? "true" : "false"}`);
+        else if (isPlainObject(value)) {
+            lines.push(`${key}:`);
+            for (const [subKey, subValue] of Object.entries(value)) {
+                if (subValue === undefined || subValue === null)
+                    continue;
+                if (!isSerializableKey(subKey))
+                    continue;
+                lines.push(`  ${subKey}: ${formatScalar(subValue)}`);
+            }
         }
         else {
-            lines.push(`${key}: ${value}`);
+            lines.push(`${key}: ${formatScalar(value)}`);
         }
     }
     lines.push(FRONTMATTER_DELIMITER);
@@ -28,4 +51,66 @@ export function serializeFrontmatter(metadata, content) {
     lines.push(content);
     return lines.join("\n");
 }
+/** Formats a single scalar, quoting whenever the parser could misread it. */
+export function formatScalar(value) {
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? String(value) : quote(String(value));
+    }
+    if (typeof value === "string") {
+        return needsQuotes(value) ? quote(value) : value;
+    }
+    if (value instanceof Date) {
+        return quote(Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString());
+    }
+    if (value === null || value === undefined)
+        return quote("");
+    try {
+        return quote(JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        return quote(String(value));
+    }
+}
+function needsQuotes(value) {
+    if (value === "")
+        return true;
+    if (value !== value.trim())
+        return true;
+    if (/[\n\r\t"'\\]/.test(value))
+        return true;
+    if (/(^|\s)#/.test(value))
+        return true;
+    if (/:(\s|$)/.test(value))
+        return true;
+    if (/^[-?[\]{}*&!|>%@`,]/.test(value))
+        return true;
+    if (value === "true" || value === "false")
+        return true;
+    if (value === "null" || value === "~")
+        return true;
+    if (/^-?(0|[1-9]\d*)(\.\d+)?$/.test(value))
+        return true;
+    return false;
+}
+function quote(value) {
+    return ('"' +
+        value
+            .replace(/\\/g, "\\\\")
+            .replace(/"/g, '\\"')
+            .replace(/\n/g, "\\n")
+            .replace(/\r/g, "\\r")
+            .replace(/\t/g, "\\t") +
+        '"');
+}
+function isSerializableKey(key) {
+    return !FORBIDDEN_KEYS.has(key) && KEY_PATTERN.test(key);
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 //# sourceMappingURL=frontmatter.serializer.js.map

package/dist/frontmatter/frontmatter.types.d.ts

@@ -8,8 +8,17 @@ export interface ParsedFrontmatter {
     readonly metadata: FrontmatterMetadata;
     readonly content: string;
 }
+/** Scalar value produced by the frontmatter parser. */
+export type FrontmatterScalar = string | number | boolean | null;
+/** Any value the frontmatter parser can produce for a key. */
+export type FrontmatterValue = FrontmatterScalar | readonly FrontmatterScalar[] | Readonly<Record<string, FrontmatterScalar>>;
 /**
  * Metadata extracted from frontmatter.
+ *
+ * The named keys below are always returned with the declared type
+ * (`version: 1.0` parses to the string `"1.0"`, `tags` items are
+ * strings). Unknown keys receive the parser's best-effort scalar,
+ * list, or one-level mapping.
  */
 export interface FrontmatterMetadata {
     readonly title?: string;
@@ -21,6 +30,6 @@ export interface FrontmatterMetadata {
     readonly deprecated?: boolean;
     readonly deprecatedMessage?: string;
     readonly visibility?: string;
-    readonly [key: string]: unknown;
+    readonly [key: string]: FrontmatterValue | undefined;
 }
 //# sourceMappingURL=frontmatter.types.d.ts.map

package/dist/frontmatter/index.d.ts

@@ -4,5 +4,5 @@
  * YAML frontmatter parsing and serialization for markdown documentation.
  */
 export { parseFrontmatter, serializeFrontmatter } from "./frontmatter.core.js";
-export type { ParsedFrontmatter, FrontmatterMetadata, } from "./frontmatter.core.js";
+export type { ParsedFrontmatter, FrontmatterMetadata, FrontmatterScalar, FrontmatterValue, } from "./frontmatter.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/generator/generator.types.d.ts

@@ -1,11 +1,29 @@
 /**
  * Type definitions for documentation generators.
  */
+import type { DocumentationSanitizer } from "../docsTypes/index.js";
+import type { DocumentVisibilityFilter } from "../registry/registry.core.js";
 /**
  * Options for markdown generation.
  */
 export interface MarkdownGeneratorOptions {
     readonly includeFrontmatter?: boolean;
     readonly includeMeta?: boolean;
+    /**
+     * Applied to `html` and `mdx` content before it is emitted. Markdown
+     * and structured content are not passed through the sanitizer.
+     */
+    readonly sanitizer?: DocumentationSanitizer;
+}
+/**
+ * Options for JSON index generation.
+ */
+export interface IndexGeneratorOptions {
+    /**
+     * Which documents to include. Defaults to `"CLIENT"` so that
+     * `visibility: "SERVER"` documents never reach a client-side index
+     * unless explicitly requested with `"ALL"` or `"SERVER"`.
+     */
+    readonly visibility?: DocumentVisibilityFilter;
 }
 //# sourceMappingURL=generator.types.d.ts.map

package/dist/generator/generatorJson.core.d.ts

@@ -2,12 +2,17 @@
  * JSON output generation for documentation documents.
  */
 import type { DocumentationDocument } from "../docsTypes/index.js";
+import type { IndexGeneratorOptions } from "./generator.types.js";
 /**
- * Generates a JSON representation of a document.
+ * Generates a JSON representation of a document, including its
+ * `visibility`, `deprecated` and `deprecatedMessage` fields.
  */
 export declare function generateJSON(document: DocumentationDocument): Record<string, unknown>;
 /**
- * Generates a JSON index for an entire registry of documents.
+ * Generates a JSON index for a set of documents.
+ *
+ * By default only client-visible documents are included (see
+ * `IndexGeneratorOptions.visibility`).
  */
-export declare function generateIndex(documents: readonly DocumentationDocument[]): Record<string, unknown>[];
+export declare function generateIndex(documents: readonly DocumentationDocument[], options?: IndexGeneratorOptions): Record<string, unknown>[];
 //# sourceMappingURL=generatorJson.core.d.ts.map

package/dist/generator/generatorJson.core.js

@@ -1,8 +1,10 @@
 /**
  * JSON output generation for documentation documents.
  */
+import { matchesVisibility } from "../registry/registry.core.js";
 /**
- * Generates a JSON representation of a document.
+ * Generates a JSON representation of a document, including its
+ * `visibility`, `deprecated` and `deprecatedMessage` fields.
  */
 export function generateJSON(document) {
     return {
@@ -13,6 +15,7 @@ export function generateJSON(document) {
         tags: document.tags,
         version: document.version,
         status: document.status,
+        visibility: document.visibility,
         deprecated: document.deprecated,
         deprecatedMessage: document.deprecatedMessage,
         content: document.content,
@@ -20,10 +23,16 @@ export function generateJSON(document) {
     };
 }
 /**
- * Generates a JSON index for an entire registry of documents.
+ * Generates a JSON index for a set of documents.
+ *
+ * By default only client-visible documents are included (see
+ * `IndexGeneratorOptions.visibility`).
  */
-export function generateIndex(documents) {
-    return documents.map((doc) => ({
+export function generateIndex(documents, options = {}) {
+    const filter = options.visibility ?? "CLIENT";
+    return documents
+        .filter((doc) => matchesVisibility(doc, filter))
+        .map((doc) => ({
         id: doc.id,
         title: doc.title,
         description: doc.description,
@@ -31,6 +40,9 @@ export function generateIndex(documents) {
         tags: doc.tags,
         version: doc.version,
         status: doc.status,
+        visibility: doc.visibility,
+        deprecated: doc.deprecated,
+        deprecatedMessage: doc.deprecatedMessage,
     }));
 }
 //# sourceMappingURL=generatorJson.core.js.map

package/dist/generator/generatorMarkdown.core.d.ts

@@ -5,6 +5,10 @@ import type { DocumentationDocument } from "../docsTypes/index.js";
 import type { MarkdownGeneratorOptions } from "./generator.types.js";
 /**
  * Generates a markdown string from a document.
+ *
+ * Frontmatter values are quoted whenever they could be misread
+ * (newlines, `:`/`#`, leading `-`), so untrusted titles, descriptions
+ * and tags cannot inject metadata keys or terminate the block.
  */
 export declare function generateMarkdown(document: DocumentationDocument, options?: MarkdownGeneratorOptions): string;
 //# sourceMappingURL=generatorMarkdown.core.d.ts.map

package/dist/generator/generatorMarkdown.core.js

@@ -1,33 +1,47 @@
 /**
  * Markdown output generation for documentation documents.
  */
+import { formatScalar } from "../frontmatter/frontmatter.serializer.js";
 import { nodesToMarkdown } from "./generatorMarkdownNodes.js";
 /**
  * Generates a markdown string from a document.
+ *
+ * Frontmatter values are quoted whenever they could be misread
+ * (newlines, `:`/`#`, leading `-`), so untrusted titles, descriptions
+ * and tags cannot inject metadata keys or terminate the block.
  */
 export function generateMarkdown(document, options = {}) {
-    const { includeFrontmatter = true, includeMeta = false } = options;
+    const { includeFrontmatter = true, includeMeta = false, sanitizer } = options;
     const lines = [];
     if (includeFrontmatter) {
         lines.push("---");
-        lines.push(`title: ${document.title}`);
+        lines.push(`title: ${formatScalar(document.title)}`);
         if (document.description) {
-            lines.push(`description: ${document.description}`);
+            lines.push(`description: ${formatScalar(document.description)}`);
         }
         if (document.category) {
-            lines.push(`category: ${document.category}`);
+            lines.push(`category: ${formatScalar(document.category)}`);
         }
         if (document.tags && document.tags.length > 0) {
             lines.push("tags:");
             for (const tag of document.tags) {
-                lines.push(`  - ${tag}`);
+                lines.push(`  - ${formatScalar(tag)}`);
             }
         }
         if (document.version) {
-            lines.push(`version: ${document.version}`);
+            lines.push(`version: ${formatScalar(document.version)}`);
         }
         if (document.status) {
-            lines.push(`status: ${document.status}`);
+            lines.push(`status: ${formatScalar(document.status)}`);
+        }
+        if (document.visibility) {
+            lines.push(`visibility: ${formatScalar(document.visibility)}`);
+        }
+        if (document.deprecated !== undefined) {
+            lines.push(`deprecated: ${formatScalar(document.deprecated)}`);
+        }
+        if (document.deprecatedMessage) {
+            lines.push(`deprecatedMessage: ${formatScalar(document.deprecatedMessage)}`);
         }
         lines.push("---");
         lines.push("");
@@ -36,17 +50,19 @@ export function generateMarkdown(document, options = {}) {
         lines.push("> **DEPRECATED:**");
         if (document.deprecatedMessage) {
             lines.push(">");
-            lines.push(`> ${document.deprecatedMessage}`);
+            for (const line of document.deprecatedMessage.split(/\r?\n/)) {
+                lines.push(`> ${line}`);
+            }
         }
         lines.push("");
     }
-    lines.push(contentToMarkdown(document.content));
+    lines.push(contentToMarkdown(document.content, sanitizer));
     if (includeMeta && document.metadata) {
         lines.push("");
         lines.push("---");
         lines.push("");
         if (document.metadata.owner) {
-            lines.push(`**Owner:** ${document.metadata.owner}`);
+            lines.push(`**Owner:** ${escapeInline(document.metadata.owner)}`);
         }
         if (document.metadata.updatedAt) {
             lines.push(`**Updated:** ${document.metadata.updatedAt.toISOString()}`);
@@ -57,16 +73,19 @@ export function generateMarkdown(document, options = {}) {
 /**
  * Converts content to markdown string.
  */
-function contentToMarkdown(content) {
+function contentToMarkdown(content, sanitizer) {
     switch (content.type) {
         case "markdown":
             return content.value;
         case "html":
-            return content.value;
         case "mdx":
-            return content.value;
+            return sanitizer ? sanitizer.sanitize(content.value) : content.value;
         case "structured":
             return nodesToMarkdown(content.nodes);
     }
 }
+/** Collapses newlines so a value cannot break out of its line. */
+function escapeInline(value) {
+    return value.replace(/\r?\n/g, " ");
+}
 //# sourceMappingURL=generatorMarkdown.core.js.map

package/dist/generator/generatorMarkdownNodes.d.ts

@@ -1,9 +1,29 @@
 /**
  * Converts structured AST nodes to markdown strings.
+ *
+ * Every value is escaped for the position it is written to, so
+ * untrusted node content cannot break out of a table, code fence,
+ * heading or link.
  */
 import type { DocumentationNode } from "../docsTypes/index.js";
 /**
  * Converts a list of documentation nodes to markdown.
+ *
+ * @throws {TypeError} for node types that are not part of `DocumentationNode`.
  */
 export declare function nodesToMarkdown(nodes: readonly DocumentationNode[]): string;
+/** Clamps a heading level to 1–6 (non-integers become 1). */
+export declare function clampHeadingLevel(level: number): number;
+/**
+ * Returns a backtick fence longer than any backtick run in `value`,
+ * so the code block cannot be closed early by its own content.
+ */
+export declare function fenceFor(value: string): string;
+/**
+ * Keeps only the first whitespace-delimited token of the language and
+ * only characters that are safe on a fence info line.
+ */
+export declare function sanitizeLanguage(language: string | undefined): string;
+/** Escapes `|` and newlines so a value stays inside its table cell. */
+export declare function tableCell(value: string): string;
 //# sourceMappingURL=generatorMarkdownNodes.d.ts.map

package/dist/generator/generatorMarkdownNodes.js

@@ -1,64 +1,134 @@
 /**
  * Converts structured AST nodes to markdown strings.
+ *
+ * Every value is escaped for the position it is written to, so
+ * untrusted node content cannot break out of a table, code fence,
+ * heading or link.
  */
+const CALLOUT_LABELS = {
+    note: "NOTE",
+    warning: "WARNING",
+    tip: "TIP",
+    danger: "DANGER",
+};
 /**
  * Converts a list of documentation nodes to markdown.
+ *
+ * @throws {TypeError} for node types that are not part of `DocumentationNode`.
  */
 export function nodesToMarkdown(nodes) {
     const lines = [];
     for (const node of nodes) {
         switch (node.type) {
-            case "heading":
-                lines.push(`${"#".repeat(node.level)} ${node.value}`);
+            case "heading": {
+                const level = clampHeadingLevel(node.level);
+                lines.push(`${"#".repeat(level)} ${singleLine(node.value)}`);
                 lines.push("");
                 break;
+            }
             case "paragraph":
                 lines.push(node.value);
                 lines.push("");
                 break;
-            case "code":
-                lines.push("```" + (node.language ?? ""));
+            case "code": {
+                const fence = fenceFor(node.value);
+                lines.push(fence + sanitizeLanguage(node.language));
                 lines.push(node.value);
-                lines.push("```");
+                lines.push(fence);
                 lines.push("");
                 break;
+            }
             case "list":
                 for (let i = 0; i < node.items.length; i++) {
                     const prefix = node.ordered ? `${i + 1}. ` : "- ";
-                    lines.push(`${prefix}${node.items[i]}`);
+                    lines.push(`${prefix}${listItem(node.items[i] ?? "")}`);
                 }
                 lines.push("");
                 break;
             case "link":
-                lines.push(`[${node.value}](${node.href})`);
+                lines.push(`[${escapeLinkText(node.value)}](${escapeLinkHref(node.href)})`);
                 lines.push("");
                 break;
             case "table": {
-                lines.push("| " + node.headers.join(" | ") + " |");
+                lines.push("| " + node.headers.map(tableCell).join(" | ") + " |");
                 lines.push("| " + node.headers.map(() => "---").join(" | ") + " |");
                 for (const row of node.rows) {
-                    lines.push("| " + row.join(" | ") + " |");
+                    lines.push("| " + row.map(tableCell).join(" | ") + " |");
                 }
                 lines.push("");
                 break;
             }
             case "quote":
-                lines.push(`> ${node.value}`);
+                for (const line of node.value.split(/\r?\n/)) {
+                    lines.push(`> ${line}`);
+                }
                 lines.push("");
                 break;
             case "callout": {
-                const labels = {
-                    note: "NOTE",
-                    warning: "WARNING",
-                    tip: "TIP",
-                    danger: "DANGER",
-                };
-                lines.push(`> **${labels[node.kind] ?? node.kind.toUpperCase()}:** ${node.value}`);
+                const label = CALLOUT_LABELS[node.kind] ?? singleLine(String(node.kind)).toUpperCase();
+                const [first = "", ...rest] = node.value.split(/\r?\n/);
+                lines.push(`> **${label}:** ${first}`);
+                for (const line of rest) {
+                    lines.push(`> ${line}`);
+                }
                 lines.push("");
                 break;
             }
+            default: {
+                const unknown = node;
+                throw new TypeError(`Unknown documentation node type "${String(unknown.type)}".`);
+            }
         }
     }
     return lines.join("\n");
 }
+/** Clamps a heading level to 1–6 (non-integers become 1). */
+export function clampHeadingLevel(level) {
+    if (!Number.isInteger(level))
+        return 1;
+    return Math.min(6, Math.max(1, level));
+}
+/**
+ * Returns a backtick fence longer than any backtick run in `value`,
+ * so the code block cannot be closed early by its own content.
+ */
+export function fenceFor(value) {
+    let longest = 0;
+    for (const run of value.match(/`+/g) ?? []) {
+        longest = Math.max(longest, run.length);
+    }
+    return "`".repeat(Math.max(3, longest + 1));
+}
+/**
+ * Keeps only the first whitespace-delimited token of the language and
+ * only characters that are safe on a fence info line.
+ */
+export function sanitizeLanguage(language) {
+    if (!language)
+        return "";
+    const first = language.trim().split(/\s+/)[0] ?? "";
+    return first.replace(/[^\w+#.-]/g, "");
+}
+/** Escapes `|` and newlines so a value stays inside its table cell. */
+export function tableCell(value) {
+    return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
+}
+function singleLine(value) {
+    return value.replace(/\r?\n/g, " ");
+}
+function listItem(value) {
+    return value.replace(/\r?\n/g, "\n  ");
+}
+function escapeLinkText(value) {
+    // Backslash first: escaping it after the brackets would turn the escapes we
+    // just added back into a literal backslash plus an unescaped bracket.
+    return singleLine(value)
+        .replace(/\\/g, "\\\\")
+        .replace(/\[/g, "\\[")
+        .replace(/\]/g, "\\]");
+}
+function escapeLinkHref(href) {
+    const clean = href.replace(/[\r\n]/g, "");
+    return /[\s()]/.test(clean) ? `<${clean.replace(/[<>]/g, "")}>` : clean;
+}
 //# sourceMappingURL=generatorMarkdownNodes.js.map

package/dist/generator/index.d.ts

@@ -4,7 +4,7 @@
  * Output generators — markdown and JSON for documentation.
  */
 export { generateMarkdown } from "./generatorMarkdown.core.js";
-export { nodesToMarkdown } from "./generatorMarkdownNodes.js";
+export { nodesToMarkdown, clampHeadingLevel, fenceFor, sanitizeLanguage, tableCell, } from "./generatorMarkdownNodes.js";
 export { generateJSON, generateIndex } from "./generatorJson.core.js";
-export type { MarkdownGeneratorOptions } from "./generator.types.js";
+export type { MarkdownGeneratorOptions, IndexGeneratorOptions, } from "./generator.types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/generator/index.js

@@ -4,6 +4,6 @@
  * Output generators — markdown and JSON for documentation.
  */
 export { generateMarkdown } from "./generatorMarkdown.core.js";
-export { nodesToMarkdown } from "./generatorMarkdownNodes.js";
+export { nodesToMarkdown, clampHeadingLevel, fenceFor, sanitizeLanguage, tableCell, } from "./generatorMarkdownNodes.js";
 export { generateJSON, generateIndex } from "./generatorJson.core.js";
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -16,4 +16,5 @@ export * from "./navigation/index.js";
 export * from "./examples/index.js";
 export * from "./generator/index.js";
 export * from "./utils/index.js";
+export * from "./errors/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -25,4 +25,6 @@ export * from "./examples/index.js";
 export * from "./generator/index.js";
 // Utils
 export * from "./utils/index.js";
+// Errors (re-exported from @zudojs/errors)
+export * from "./errors/index.js";
 //# sourceMappingURL=index.js.map

package/dist/navigation/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Navigation tree utilities — breadcrumbs, flattening, sibling resolution.
  */
-export { getBreadcrumbs, flattenNavigation, findNavigationItem, getSiblings, } from "./navigation.core.js";
+export { getBreadcrumbs, flattenNavigation, findNavigationItem, getSiblings, getAdjacent, } from "./navigation.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/navigation/index.js

@@ -3,5 +3,5 @@
  *
  * Navigation tree utilities — breadcrumbs, flattening, sibling resolution.
  */
-export { getBreadcrumbs, flattenNavigation, findNavigationItem, getSiblings, } from "./navigation.core.js";
+export { getBreadcrumbs, flattenNavigation, findNavigationItem, getSiblings, getAdjacent, } from "./navigation.core.js";
 //# sourceMappingURL=index.js.map

package/dist/navigation/navigation.core.d.ts

@@ -3,23 +3,42 @@
  *
  * Provides breadcrumb generation, tree flattening, and
  * link resolution for documentation navigation structures.
+ *
+ * Every walker tolerates shared or cyclic nodes (a node is visited at
+ * most once) and stops at `MAX_NAVIGATION_DEPTH`, so malformed trees
+ * never overflow the stack.
  */
 import type { DocumentationBreadcrumb, DocumentationNavigationItem } from "../docsTypes/index.js";
+/** Maximum nesting depth any walker will descend. */
+export declare const MAX_NAVIGATION_DEPTH = 64;
+type Nodes = readonly DocumentationNavigationItem[];
 /**
  * Generates breadcrumbs for a given document ID
- * by walking the navigation tree.
+ * by walking the navigation tree. Intermediate section nodes keep
+ * their `documentId` when they have one, so section landing pages
+ * stay linkable.
  */
-export declare function getBreadcrumbs(documentId: string, items: readonly DocumentationNavigationItem[]): readonly DocumentationBreadcrumb[];
+export declare function getBreadcrumbs(documentId: string, items: Nodes): readonly DocumentationBreadcrumb[];
 /**
  * Flattens a navigation tree into a list of all document IDs in order.
+ * A document referenced more than once appears once, at its first position.
  */
-export declare function flattenNavigation(items: readonly DocumentationNavigationItem[]): readonly string[];
+export declare function flattenNavigation(items: Nodes): readonly string[];
 /**
  * Finds a navigation item by document ID.
  */
-export declare function findNavigationItem(documentId: string, items: readonly DocumentationNavigationItem[]): DocumentationNavigationItem | undefined;
+export declare function findNavigationItem(documentId: string, items: Nodes): DocumentationNavigationItem | undefined;
+/**
+ * Gets sibling document IDs for a given document (the other documents
+ * at the same navigation level, excluding the document itself).
+ */
+export declare function getSiblings(documentId: string, items: Nodes): readonly string[];
 /**
- * Gets sibling document IDs for a given document.
+ * Gets the previous and next document IDs at the same navigation level.
  */
-export declare function getSiblings(documentId: string, items: readonly DocumentationNavigationItem[]): readonly string[];
+export declare function getAdjacent(documentId: string, items: Nodes): {
+    readonly previous?: string;
+    readonly next?: string;
+};
+export {};
 //# sourceMappingURL=navigation.core.d.ts.map