@zudojs/docs

Documentation infrastructure with structured document model, registry, validation, navigation, frontmatter parsing, and markdown/JSON generation.

Documentation: zudojs.oyinlola.site/docs/packages-docs · For AI agents: Markdown version, llms.txt

Installation

npm install @zudojs/docs

Quick Start

import {
  createDocumentRegistry,
  createMarkdownDocument,
  validateAll,
  generateIndex,
} from "@zudojs/docs";

const registry = createDocumentRegistry();

registry.register(
  createMarkdownDocument(
    "getting-started",
    "Getting Started",
    "# Getting Started\n\nWelcome to Zudojs...",
    { category: "introduction", tags: ["intro"] },
  ),
);

// Or build the document object yourself
registry.register({
  id: "guides.http.routing",
  title: "HTTP Routing",
  content: { type: "markdown", value: "# Routing\n\n..." },
});

const result = validateAll(registry.getAll());
if (!result.valid) {
  console.error(result.issues);
}

const index = generateIndex(registry.getAll()); // SERVER-only docs excluded

Features

• Document model with frontmatter (parseFrontmatter / serializeFrontmatter round-trip safely; tags always parses to a string array, and the body keeps its indentation)
• Document registry and discovery (DuplicateDocumentError on duplicate IDs, deep-frozen copies)
• Navigation tree helpers (breadcrumbs, siblings, previous/next, cycle-safe walkers)
• Markdown and JSON generation with escaping for untrusted content: structured text is HTML-escaped and links are limited to http, https, mailto, tel, ftp and ftps (others are written as plain text)
• Fail-closed visibility filtering: only an unset or exactly "CLIENT" visibility reaches a client index
• stripMarkdown and link validation run in linear time on untrusted input
• Document, link and navigation validation with a single valid rule (errors only); javascript: and other non-allow-listed link schemes are UNSAFE_LINK errors in every link form — inline [x](…) (including targets with parentheses or a title), reference definitions [x]: …, raw <a href="…"> and <scheme:…> autolinks
• BROKEN_LINK and NAVIGATION_ORPHAN_DOCUMENT are warnings by default; pass { brokenLinkSeverity: "error", orphanSeverity: "error" } to validateAll (or brokenLinkSeverity to validateLinks) to fail on dead links or unreachable documents
• createDocument({ …, strict: true }) rejects an unknown category, status or visibility at creation instead of leaving it to validateDocument; documents never carry explicit undefined keys
• getAdjacent(id, nav, { scope: "tree" }) walks previous/next across section boundaries in reading order (the default stays within one level)
• Documentation error classes re-exported from @zudojs/errors

Use Cases

• API documentation
• User guides
• Knowledge bases
• Documentation sites