DocumentationREST APIAPI Reference

Reference

Agent

Types for the doxahq agent documentation structure: pages, sections, and the full site plan

Overview

@doxahq/agent is the shared Doxa documentation-generation agent. It plans and writes documentation pages for a project. This page covers the public types that the package exports from its root entry point, @doxahq/agent. These types describe the documentation structure that the agent proposes: a DocumentationStructure contains DocSection groups, and each section contains DocPage entries.

Use these types when your code builds, reads, or validates a documentation plan. You do not need them to generate a site from the Doxa dashboard. For that workflow, see Generations and Doxabot Instructions.

Install

bash
npm install @doxahq/agent

The package publishes TypeScript declarations alongside its JavaScript output, so you do not need a separate @types package.

Version:

This page documents version 0.1.1 of @doxahq/agent. The package also declares two subpath entry points, @doxahq/agent/adapters/node and @doxahq/agent/structure. This page covers only the root entry point.

Import

typescript
import type {
  DocPage,
  DocSection,
  DocumentationStructure,
} from "@doxahq/agent";

All three exports are types. Import them with import type so that no runtime code is loaded.

DocumentationStructure

The planned structure of a documentation site.

typescript
interface DocumentationStructure {
  sections: DocSection[];
}
FieldTypeRequiredDescription
sectionsDocSection[]YesThe sections of the site.

DocSection

A section that groups documentation pages.

typescript
interface DocSection {
  id: string;
  title: string;
  pages: DocPage[];
  default?: boolean;
}
FieldTypeRequiredDescription
idstringYesIdentifier of the section. Keep it unique within the structure.
titlestringYesHuman-readable section title.
pagesDocPage[]YesPages in the section. Pages are always direct children of a section.
defaultbooleanNoWhen true, the section is the rootless default section. Set this on exactly one section.

The writer stores the pages of the default section under default/. The docs renderer reads them from that location and falls back to the legacy rootless layout.

DocPage

A documentation page.

typescript
interface DocPage {
  id: string;
  title: string;
  description: string;
  group?: string;
  sourceEvidence?: SourceEvidence[];
  collectionId?: string;
  collectionItemId?: string;
  audience?: "consumer" | "maintainer" | "reference";
  navVisibility?: "visible" | "hidden";
  canonicalRoute?: string;
  allowedInternalTerms?: string[];
  reference?: PageReferenceMetadata;
}
FieldTypeRequiredDescription
idstringYesIdentifier of the page. Keep it unique within the structure.
titlestringYesPage title.
descriptionstringYesShort summary of the page.
groupstringNoNavigation group inside the section. It affects presentation only.
sourceEvidenceSourceEvidence[]NoSource files and facts to use when writing the page.
collectionIdstringNoCollection that the page represents, when it comes from a detected collection.
collectionItemIdstringNoCollection item that the page represents, when it comes from a detected collection.
audience"consumer" | "maintainer" | "reference"NoIntended reader. Defaults to "consumer".
navVisibility"visible" | "hidden"NoWhether the page appears in generated navigation. Defaults to "visible".
canonicalRoutestringNoCanonical route of the page, if known. Otherwise, writers use generated routes.
allowedInternalTermsstring[]NoInternal terms or paths that the page explicitly allows.
referencePageReferenceMetadataNoStructured reference metadata that writers and reference navigation use.

SourceEvidence

Each entry in DocPage.sourceEvidence has these fields:

FieldTypeRequiredDescription
pathstringYesProject-relative path of the source file.
kind"docs" | "readme" | "package" | "source" | "manifest" | "example" | "other"NoWhy the file is relevant to the page.
titlestringNoHuman-readable label for display.

Example

The following example builds a small structure and checks that every page identifier is unique. It uses only the exported types.

typescript
import type {
  DocPage,
  DocSection,
  DocumentationStructure,
} from "@doxahq/agent";

const overview: DocPage = {
  id: "overview",
  title: "Overview",
  description: "What the project does and how to start.",
  audience: "consumer",
  sourceEvidence: [{ path: "README.md", kind: "readme" }],
};

const api: DocPage = {
  id: "api",
  title: "API",
  description: "Public functions and types.",
  audience: "reference",
  navVisibility: "visible",
};

const sections: DocSection[] = [
  { id: "start", title: "Getting started", pages: [overview], default: true },
  { id: "reference", title: "Reference", pages: [api] },
];

const structure: DocumentationStructure = { sections };

const ids = structure.sections.flatMap((section) =>
  section.pages.map((page) => page.id),
);

if (new Set(ids).size !== ids.length) {
  throw new Error("Page identifiers must be unique.");
}

Errors and edge cases

These are TypeScript types. The package does not check values at runtime, so a value that does not match the types is not rejected when your code creates it. Validate structures where they enter your code, for example before you store them or pass them to another system.

The audience and navVisibility fields use their defaults only when you omit them. Set them explicitly when your code depends on a specific value.

Generations and Doxabot Instructions

How generations produce the pages of a hosted site.

Start a generation

Start a documentation generation for a project through the REST API.

Editing Pages in the Content Editor

Edit the MDX source of a page in the dashboard.