TechArticle

Wiki Programmatic API

Infobox

description
Stable Deno/TypeScript and npm entry points for validating, building, and querying a wiki.

The Deno/TypeScript engine is the single Wiki implementation. Use its in-process API for Deno and TypeScript applications. The npm package exposes a runtime/bootstrap API that locates the Deno runtime and builds the wiki command; it does not export a Wiki class. The wiki CLI remains the primary user surface.

See Design Philosophies for the CLI/library boundary. RDF/XML input remains supported; RDF/XML output is explicitly deferred from the Deno cutover.

Native Deno library

The Deno library is published as @wazoo/wiki on JSR, with src/wiki/mod.ts as its public entrypoint.

import { Wiki } from "jsr:@wazoo/wiki";

const wiki = Wiki.load("docs/wiki.yml");

Wiki.load accepts a config path or a directory containing wiki.yml / wiki.yaml. The optional wikiInputs setting overrides wiki.input; installed, read-only sources are then included as part of the corpus.

Validation reports

Wiki.check and Wiki.lint are asynchronous and return Promise<AuditReport> values. Each report has ok, errors, and warnings; applyStrict() promotes warnings to errors. When enabled, lint.heading_levels uses the in-process ESLint Markdown rule engine; route-aware links, CURIE resolution, and the remaining Wiki policies stay in Wiki.

const lintReport = await wiki.lint(undefined, { strict: true });
const report = await wiki.check(undefined, { strict: true });
const [lintErrors, lintWarnings] = lintReport.messages();
const [errors, warnings] = report.messages();
if (!lintReport.ok || !report.ok) {
  console.error(
    [...lintErrors, ...lintWarnings, ...errors, ...warnings].join("\n"),
  );
}

Pass a list of document paths as the first argument to scope an operation:

const report = await wiki.check(["docs/wiki/Getting_Started.md"]);

Guarded edits

Wiki.edit() validates a batch of page changes against the wiki's shapes, routes, and links and, with apply, writes every file or none. Conflicts and rejections come back in the report rather than as exceptions, so a caller can re-read, repair, and retry; a malformed edit throws EditUsageError. Wiki.show() returns one page as the engine reads it, including the hash an op passes as expect, and Wiki.refs() lists the pages linking to and from it. See wiki edit for the edit format, validation scope, and report.

const page = await wiki.show("wiki/Budget_Ledger.md");
const report = await wiki.edit({
  ops: [{
    op: "patch",
    path: "wiki/Budget_Ledger.md",
    expect: page.hash,
    target: { heading: "Change log" },
    mode: "append",
    content: "- 2026-10-10 — Added the Neon plan.",
  }],
}, { apply: true });
if (report.status === "conflict") {
  // Someone changed the page since `show`: re-read and rebuild the edit.
}

Query and graph access

const results = await wiki.query(
  "SELECT ?name WHERE { ?person <https://schema.org/name> ?name }",
  { format: "json" },
);

const graph = await wiki.graph();
const dataset = await wiki.dataset();

query returns the chosen result format as a string. graph() returns the inferred union graph by default; dataset() exposes named graphs for source provenance. Options support inference, reload, and disk-cache control.

Build and export

const built = await wiki.build("_site", {
  baseUrl: "/wiki",
  urlStyle: "dir",
});
if (!built.ok) throw new Error(built.error_message ?? "Build failed");

const exported = await wiki.export(undefined, { format: "json-ld" });
if (!exported.ok) {
  throw new Error(exported.error_message ?? "Export failed");
}

The library also exposes formatting, inline SPARQL rendering, link analysis and repair, source management, local serving, and project scaffolding. Its generated TSDoc reference is on JSR.

The wazootech-wiki npm package: command only

The npm package publishes the wiki command and nothing else. It bundles the Deno runtime, so npm users need neither system Python nor a separate Deno installation; Node.js 18 or newer is the only requirement.

npm install -g wazootech-wiki
wiki -c docs/wiki.yml check --strict

Why there is no npm Wiki class

This package previously exported a Wiki SDK whose every method spawned the CLI and returned an exit code plus captured output strings. That was a second, weaker path to work the library already does in process: a subprocess boundary discards the typed reports that make embedding worthwhile, and it forced TS and Node users to treat the library as a program to be invoked rather than code to be called.

TypeScript callers embed the library (above). Callers in languages that cannot embed JavaScript use the command, and a generated client for those languages is planned work.

Deferred RDF/XML output

The engine parses RDF/XML from .rdf and .xml wiki inputs. RDF/XML serialization is deferred from the initial Deno cutover: export -f xml returns an explicit unsupported-format error, and an RDF/XML Accept request to the SPARQL service returns 406 Not Acceptable. The engine never substitutes a different serialization.

Backlinks