@zudojs/docs

OVERVIEW

Documentation usually lives in loose Markdown files. Nothing checks that two pages do not share a name, that every link points somewhere real, or that the sidebar only lists pages that exist. Problems show up when a reader clicks a dead link.

@zudojs/docs gives each page a stable ID and a plain object shape. You put those objects in a registry (a lookup table keyed by ID), run the validators over them, and then generate Markdown or a JSON index for whatever site tool you use.

The package has no opinion about how you render pages. It does not include a web server, a Markdown-to-HTML converter, or a search engine. It only models, checks, and exports.

INSTALLATION

Install the package. It pulls in @zudojs/errors on its own; nothing else is required.

QUICK START

This example creates two pages, stores them in a registry, checks them, and prints a JSON index.

Nothing is written to disk. generateIndex returns plain objects; you decide where they go (a file, an HTTP response, a search tool).

DOCUMENTS

A document is one page of documentation described as a plain object. Every document has three required fields: an id, a title, and content. Everything else is optional.

IDs are dot-separated, like guides.http.routing. Each segment may contain letters, digits, _ and -. Titles can change later; IDs should not, because links and navigation point at them.

Three ways to build one

createDocument takes the full options object. The other two are shortcuts for the most common content types.

The returned object is a deep-frozen copy. Changing your original options afterwards does not change the document, and trying to assign to the document throws in strict mode.

Content types

The content field is an object with a type. Four types are accepted.

Optional fields

REGISTRY

A registry is a lookup table that holds documents by ID. It refuses duplicates, so two pages can never claim the same ID. It also stores a frozen copy of each document, so editing your original object later has no effect on what is stored.

This example registers two pages, tries a duplicate, and then queries the registry.

Methods

FRONTMATTER

Frontmatter is a block of key: value lines at the top of a Markdown file, fenced by --- on its own line above and below. It is how Markdown files usually carry a title, tags and similar metadata.

parseFrontmatter splits a raw file into the metadata and the rest of the text. serializeFrontmatter does the reverse.

The serializer added quotes around Notes: draft because a bare colon would confuse the parser. Anything you serialize parses back to the same values.

What the parser understands

• → key: value where the value is a string, a number (10, -1, 1.5), true/false, or null.
• → Quoted strings, in double or single quotes. A quoted value is never turned into a number or a boolean.
• → A list: tags: followed by indented - item lines.
• → One level of nesting: author: followed by indented name: value lines.
• → # comments outside quotes are dropped.

The named keys title, description, category, version, status, deprecatedMessage and visibility always come back as strings, and tags is always an array of strings (tags: http → ["http"], tags: → []). Unknown keys get the parser's best guess.

VALIDATION

Validators look at documents and report problems without throwing. Each one returns a ValidationResult: { valid, issues }. Every issue has a severity of "error" or "warning", a short code, a message, and usually a documentId.

valid is false only when at least one issue is an error. Warnings never make a result invalid, so read issues if you want to see them.

validateAll runs every check in one call. Pass a navigation tree as the second argument to have it checked too.

The broken link is only a warning, so on its own it would not have made valid false. The navigation entry pointing at a page that does not exist is an error.

The individual validators

NAVIGATION

A navigation tree is an array of { title, documentId?, children? } items, nested as deep as you like. It is kept separate from the documents, so you can reorder a sidebar without touching any page.

The helpers answer common questions about the tree: where am I, what is next, what else is at this level.

getAdjacent only looks at the same level. For "reference", which is alone at the top level, it returns {}. A document ID that is not in the tree gives an empty breadcrumb list, an empty sibling list, and undefined from findNavigationItem.

GENERATORS

Generators turn documents into output you can hand to another tool. There are three: generateMarkdown for one page, generateJSON for one page as a plain object, and generateIndex for a list of page summaries without content.

This example generates Markdown with frontmatter, then builds an index that hides a server-only page.

Options

CODE EXAMPLES

A DocumentationExample is a code snippet with an id, a language and the code itself, plus an optional title and description. You can check one is complete and render it as a Markdown code block.

validateExample returns { valid, errors } with plain strings, not ValidationIssue objects. exampleToJSON(example) gives you a plain object with the same five fields.

UTILITIES

Small pure functions for IDs, links and Markdown text. They are the same helpers the validators use internally.

Headings inside fenced code blocks are ignored by extractTitleFromMarkdown and extractHeadings, so a # comment in a shell example does not become a title.

API REFERENCE

Everything below is exported from @zudojs/docs.

Functions

Classes

Types

Errors

All error classes are defined in @zudojs/errors and re-exported here so one import is enough.

Constants

Navigation walkers stop at a depth of 64 and report deeper trees as NAVIGATION_CYCLE; that limit is internal and not exported.

COMMON MISTAKES

• Using a file path as an ID → createDocument({ id: "guides/http" }) throws DocumentValidationError because / is not allowed. → Convert it first: documentIdFromPath("guides/http.md") gives "guides.http".
• Treating valid: true as "no issues" → Broken links and orphan pages are warnings, so the result stays valid and they go unnoticed. → Log or fail on result.issues.length > 0 when you want a strict build.
• Passing an array of documents to validateLinks → It expects a Set of IDs as the second argument, so every link is reported as broken. → Use registry.idSet() or new Set(docs.map((d) => d.id)).
• Expecting generateIndex to list every page → Pages with visibility: "SERVER" are missing because the default filter is "CLIENT". → Pass { visibility: "ALL" } when you want all of them.
• Editing a document after registering it → The registry stores a frozen copy, so the edit is ignored or throws in strict mode. → Build a new document and call delete(id) then register(doc).
• Registering the same ID twice → DuplicateDocumentError is thrown and registerAll stops part-way. → Check registry.has(id) first, or run validateNoDuplicateIds on the array before registering.

RELATED PACKAGES

• @zudojs/errors — defines every error class this package throws or re-exports. Reach for it when you build your own error types.
• @zudojs/openapi — describes HTTP APIs as OpenAPI documents. Pair it with this package when the API reference should sit next to hand-written guides.
• @zudojs/schema — validates data shapes. Use it to check frontmatter metadata against a schema before turning it into documents.
• zudojs-cli — zudojs add docs installs this package into a project.

COMPLETE EXPORT INDEX

Every name @zudojs/docs exports from its package root at v1.0.3 — 103 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.