export type SearchDocument = {
  pageId: PageId;
  route: RoutePath;
  title: string;
  description: string;
  kind: PageKind;
  tags: string[];
  sections: SearchSection[];
  metadata: SearchMetadata;
};

export type SearchSection = {
  id: string;
  heading?: string;
  anchor?: string;
  level?: number;
  text: string;
  code?: SearchCodeBlock[];
  entities?: SearchEntity[];
};

export type SearchCodeBlock = {
  language: string;
  title?: string;
  text: string;
  executable?: boolean;
};

export type SearchEntity =
  | { type: "cliCommand"; name: string }
  | { type: "configField"; name: string }
  | { type: "apiOperation"; operationId: string; method: string; path: string }
  | { type: "symbol"; name: string; language?: string }
  | { type: "package"; name: string };

export type SearchMetadata = {
  sourcePath: string;
  navPath: string[];
  breadcrumbs: string[];
  generated: boolean;
  hidden: boolean;
  draft: boolean;
};

Configuration Reference
/docs/reference/configuration

outputDir
Configuration Reference > Build output
/docs/reference/configuration#build-output

Defines where the static site build is written.

export type SearchChunk = {
  id: string;
  pageId: PageId;
  route: RoutePath;
  anchor?: string;
  title: string;
  sectionTitle?: string;
  breadcrumbs: string[];
  kind: PageKind;
  text: string;
  entities: SearchEntity[];
  weight: number;
};

export function chunkHref(chunk: SearchChunk): string {
  return chunk.anchor
    ? `${chunk.route}#${chunk.anchor}`
    : chunk.route;
}

# Configuration Reference

## Build output

The `outputDir` field controls where static output is written.

## Search

The `search.enabled` field controls whether search artifacts are emitted.

[
  {
    "title": "Configuration Reference",
    "sectionTitle": "Build output",
    "anchor": "build-output",
    "text": "The outputDir field controls where static output is written."
  },
  {
    "title": "Configuration Reference",
    "sectionTitle": "Search",
    "anchor": "search",
    "text": "The search.enabled field controls whether search artifacts are emitted."
  }
]

export function splitLargeSection(section: SearchSection): SearchSection[] {
  if (wordCount(section.text) <= 800) {
    return [section];
  }

  return splitByParagraphs(section, {
    targetWords: 500,
    maxWords: 900,
  });
}

<Callout type="warning" title="Do not publish unreviewed AI output">
Always review generated documentation before applying it to the main branch.
</Callout>

Do not publish unreviewed AI output
Always review generated documentation before applying it to the main branch.

<Tabs>
  <Tab title="npm">
    npm install -D docforge
  </Tab>
  <Tab title="pnpm">
    pnpm add -D docforge
  </Tab>
</Tabs>

Generate API reference
Create endpoint documentation from an OpenAPI specification.

export function extractSearchDocument(
  page: CompilePageResult,
  manifestEntry: PageManifestEntry,
  registry: ComponentRegistry
): SearchDocument {
  const sections = extractSearchSectionsFromAst(page.ast, {
    registry,
    route: manifestEntry.route,
    pageTitle: manifestEntry.title,
  });

  return {
    pageId: manifestEntry.id,
    route: manifestEntry.route,
    title: manifestEntry.title,
    description: manifestEntry.description,
    kind: manifestEntry.kind,
    tags: manifestEntry.tags,
    sections,
    metadata: {
      sourcePath: manifestEntry.sourcePath,
      navPath: [],
      breadcrumbs: [],
      generated: manifestEntry.generated,
      hidden: manifestEntry.hidden,
      draft: manifestEntry.draft,
    },
  };
}

export function normalizeSearchText(input: string): string {
  return input
    .replace(/\s+/g, " ")
    .trim();
}

search.enabled -> search, enabled only

search.enabled -> search.enabled, search, enabled

export function expandDeveloperToken(token: string): string[] {
  const expanded = new Set<string>();
  expanded.add(token);

  if (token.includes(".")) {
    for (const part of token.split(".")) {
      expanded.add(part);
    }
  }

  if (token.includes("/")) {
    for (const part of token.split("/").filter(Boolean)) {
      expanded.add(part);
    }
  }

  if (token.startsWith("--")) {
    expanded.add(token.slice(2));
  }

  return [...expanded];
}

export type WeightedText = {
  text: string;
  field: SearchField;
  weight: number;
};

export type SearchField =
  | "pageTitle"
  | "description"
  | "heading"
  | "body"
  | "code"
  | "apiPath"
  | "apiMethod"
  | "cliCommand"
  | "configField"
  | "tag";

export type SearchQuery = {
  raw: string;
  terms: string[];
  exactPhrases: string[];
};

export type SearchHit = {
  chunk: SearchChunk;
  score: number;
  highlights: SearchHighlight[];
};

export function scoreChunk(query: SearchQuery, chunk: IndexedChunk): number {
  let score = 0;

  for (const term of query.terms) {
    score += scoreTerm(term, chunk);
  }

  for (const phrase of query.exactPhrases) {
    if (chunk.normalizedText.includes(phrase)) {
      score += 20;
    }
  }

  score += chunk.weight;

  return score;
}

export function scoreTerm(term: string, chunk: IndexedChunk): number {
  let score = 0;

  for (const field of chunk.fields) {
    if (field.tokens.includes(term)) {
      score += field.weight;
    }

    if (field.exactValues.includes(term)) {
      score += field.weight * 2;
    }
  }

  return score;
}

{
  "chunks": [
    {
      "id": "quickstart#install",
      "title": "Quickstart",
      "sectionTitle": "Install",
      "href": "/quickstart#install",
      "text": "Install DocForge with npm...",
      "tokens": ["install", "docforge", "npm"]
    }
  ]
}

{
  "terms": {
    "docforge": [["chunk1", 12], ["chunk2", 4]],
    "build": [["chunk3", 10]]
  },
  "chunks": {
    "chunk1": {
      "title": "Quickstart",
      "href": "/quickstart"
    }
  }
}

export type StaticSearchIndex = {
  version: string;
  chunks: Record<string, SearchChunkPreview>;
  terms: Record<string, Posting[]>;
};

export type Posting = {
  chunkId: string;
  score: number;
  fields: SearchField[];
};

export type SearchChunkPreview = {
  id: string;
  title: string;
  sectionTitle?: string;
  href: string;
  breadcrumbs: string[];
  kind: PageKind;
  excerpt: string;
};

export function buildInvertedIndex(chunks: SearchChunk[]): StaticSearchIndex {
  const index: StaticSearchIndex = {
    version: "1",
    chunks: {},
    terms: {},
  };

  for (const chunk of chunks) {
    index.chunks[chunk.id] = toPreview(chunk);

    for (const field of buildWeightedFields(chunk)) {
      const tokens = tokenize(field.text);

      for (const token of tokens) {
        const postings = index.terms[token] ?? [];
        postings.push({
          chunkId: chunk.id,
          score: field.weight,
          fields: [field.field],
        });
        index.terms[token] = postings;
      }
    }
  }

  return compactIndex(index);
}

export function compactIndex(index: StaticSearchIndex): StaticSearchIndex {
  for (const [term, postings] of Object.entries(index.terms)) {
    const byChunk = new Map<string, Posting>();

    for (const posting of postings) {
      const existing = byChunk.get(posting.chunkId);

      if (!existing) {
        byChunk.set(posting.chunkId, posting);
        continue;
      }

      existing.score += posting.score;
      existing.fields = [...new Set([...existing.fields, ...posting.fields])];
    }

    index.terms[term] = [...byChunk.values()]
      .sort((a, b) => b.score - a.score);
  }

  return index;
}

const STOP_WORDS = new Set([
  "the", "a", "an", "and", "or", "to", "of", "in", "for", "with", "on",
]);

export function createExcerpt(text: string, maxLength = 220): string {
  const normalized = text.replace(/\s+/g, " ").trim();

  if (normalized.length <= maxLength) {
    return normalized;
  }

  return normalized.slice(0, maxLength - 1).trimEnd() + "…";
}

export type SearchHighlight = {
  start: number;
  end: number;
  term: string;
};

export type SearchFilter = {
  kind?: PageKind[];
  tag?: string[];
  method?: string[];
  version?: string[];
};

export type SearchChunkPreview = {
  id: string;
  title: string;
  href: string;
  kind: PageKind;
  tags: string[];
  facets: Record<string, string[]>;
};

export function apiOperationToSearchChunk(
  operation: NormalizedApiOperation,
  page: PageManifestEntry
): SearchChunk {
  return {
    id: `api:${operation.operationId}`,
    pageId: page.id,
    route: page.route,
    anchor: operation.operationId,
    title: page.title,
    sectionTitle: `${operation.method} ${operation.path}`,
    breadcrumbs: ["API Reference", ...(operation.tags ?? [])],
    kind: "apiReference",
    text: [
      operation.operationId,
      operation.summary,
      operation.description,
      operation.method,
      operation.path,
      operation.parameters.map((p) => p.name).join(" "),
      operation.responses.map((r) => r.status).join(" "),
    ].join("\n"),
    entities: [
      {
        type: "apiOperation",
        operationId: operation.operationId,
        method: operation.method,
        path: operation.path,
      },
    ],
    weight: 10,
  };
}

## `docforge build`

Build the static docs site.

| Option | Description |
|---|---|
| `--out` | Output directory. |
| `--strict` | Treat warnings as errors. |

{
  type: "cliCommand",
  name: "docforge build"
}

{
  type: "cliFlag",
  command: "docforge build",
  name: "--strict"
}

build.outputDir

export function expandConfigFieldToken(field: string): string[] {
  const parts = field.split(".");
  const camelParts = parts.flatMap(splitCamelCase);

  return [
    field,
    ...parts,
    ...camelParts,
    field.toLowerCase(),
  ];
}

export function shouldIndexCodeBlock(block: SearchCodeBlock): boolean {
  if (block.text.length > 5000) {
    return false;
  }

  if (containsSecretLikePattern(block.text)) {
    return false;
  }

  return true;
}

warning search.code.skippedLargeBlock docs/page.mdx:42:1
Large code block was skipped from search indexing.

export function redactSearchText(input: string): string {
  return input
    .replace(/sk-[A-Za-z0-9_-]{20,}/g, "[REDACTED_SECRET]")
    .replace(/AKIA[0-9A-Z]{16}/g, "[REDACTED_AWS_KEY]");
}

export type SearchConfig = {
  enabled: boolean;
  includeHiddenPages: boolean;
  includeCodeBlocks: boolean;
  maxChunkWords: number;
  indexFormat: "json" | "inverted";
  minTermLength: number;
  facets: string[];
};

{
  "search": {
    "enabled": true,
    "includeHiddenPages": false,
    "includeCodeBlocks": true,
    "indexFormat": "inverted",
    "maxChunkWords": 900
  }
}

export type SearchBuildInput = {
  documents: SearchDocument[];
  manifest: PageManifest;
  navigation: NavNode[];
  config: SearchConfig;
  outputDir: string;
};

export type SearchBuildOutput = {
  indexFiles: Array<{
    path: string;
    bytes: number;
  }>;
  chunksIndexed: number;
  termsIndexed: number;
  diagnostics: Diagnostic[];
};

export async function buildSearch(input: SearchBuildInput): Promise<SearchBuildOutput> {
  const diagnostics: Diagnostic[] = [];

  const documents = input.documents
    .filter((doc) => shouldIncludeInSearch(doc, input.config));

  const chunks = documents.flatMap((doc) =>
    chunkSearchDocument(doc, input.config)
  );

  const safeChunks = chunks.map((chunk) =>
    sanitizeSearchChunk(chunk, diagnostics)
  );

  const index = input.config.indexFormat === "inverted"
    ? buildInvertedIndex(safeChunks)
    : buildJsonIndex(safeChunks);

  const files = await writeSearchArtifacts(index, input.outputDir);

  return {
    indexFiles: files,
    chunksIndexed: safeChunks.length,
    termsIndexed: countTerms(index),
    diagnostics,
  };
}

search/
  index.json
  meta.json

{
  "version": "1",
  "format": "inverted",
  "chunks": 428,
  "terms": 9231,
  "generatedAt": "2026-07-03T00:00:00.000Z"
}

export class StaticSearchClient {
  private indexPromise?: Promise<StaticSearchIndex>;

  constructor(private readonly indexUrl: string) {}

  async search(query: string): Promise<SearchResult[]> {
    const index = await this.loadIndex();
    return searchIndex(index, parseQuery(query));
  }

  private async loadIndex(): Promise<StaticSearchIndex> {
    if (!this.indexPromise) {
      this.indexPromise = fetch(this.indexUrl).then((res) => res.json());
    }

    return this.indexPromise;
  }
}

Configuration Reference
Build output · /reference/configuration#build-output
Defines where the static site build is written.

POST /users
API Reference > Users · /api/users/create
Creates a new user.

export type ParsedQuery = {
  raw: string;
  terms: string[];
  phrases: string[];
  filters: Record<string, string[]>;
};

kind:api users
method:POST users
tag:config outputDir

export function parseSearchQuery(raw: string): ParsedQuery {
  const phrases = [...raw.matchAll(/"([^"]+)"/g)].map((m) => m[1]!);
  const withoutPhrases = raw.replace(/"([^"]+)"/g, " ");

  const filters: Record<string, string[]> = {};
  const terms: string[] = [];

  for (const token of withoutPhrases.split(/\s+/).filter(Boolean)) {
    const filterMatch = token.match(/^([a-zA-Z]+):(.+)$/);

    if (filterMatch) {
      const [, key, value] = filterMatch;
      filters[key!] = [...(filters[key!] ?? []), value!];
      continue;
    }

    terms.push(token);
  }

  return {
    raw,
    terms: terms.flatMap(expandDeveloperToken),
    phrases,
    filters,
  };
}

export function diversifyResults(hits: SearchHit[]): SearchHit[] {
  const byPage = new Map<PageId, SearchHit[]>();

  for (const hit of hits) {
    const group = byPage.get(hit.chunk.pageId) ?? [];
    group.push(hit);
    byPage.set(hit.chunk.pageId, group);
  }

  const diversified: SearchHit[] = [];

  for (const group of byPage.values()) {
    diversified.push(...group.slice(0, 2));
  }

  return diversified.sort((a, b) => b.score - a.score);
}

{
  "search": {
    "synonyms": {
      "auth": ["authentication", "authorization"],
      "config": ["configuration"],
      "deploy": ["deployment"]
    }
  }
}

export function expandSynonyms(term: string, synonyms: Record<string, string[]>): string[] {
  return [term, ...(synonyms[term] ?? [])];
}

{
  code: "search.component.missingExtractor",
  severity: "warning",
  category: "search",
  message: "Component <CustomChart> has no search extractor, so its content may not be searchable.",
  hint: "Add extractSearchText to the component registry entry.",
}

{
  "search": {
    "maxIndexBytes": 5000000
  }
}

warning search.index.tooLarge
Search index is 7.2 MB, above the configured 5 MB budget.

Hint:
Exclude large code blocks, reduce hidden pages, or switch to a remote search provider.

search/
  meta.json
  shards/
    api.json
    guides.json
    reference.json

{
  "shards": [
    {
      "id": "api",
      "url": "/search/shards/api.json",
      "kinds": ["apiReference"]
    },
    {
      "id": "guides",
      "url": "/search/shards/guides.json",
      "kinds": ["howTo", "quickstart"]
    }
  ]
}

export type SearchEvalCase = {
  query: string;
  expectedRoutes: string[];
  expectedTopRoute?: string;
  description: string;
};

[
  {
    "query": "outputDir",
    "expectedTopRoute": "/reference/configuration#build-output"
  },
  {
    "query": "docforge build --strict",
    "expectedTopRoute": "/reference/cli#docforge-build"
  },
  {
    "query": "POST /users",
    "expectedTopRoute": "/api/users/create"
  }
]

export type SearchEvalResult = {
  total: number;
  top1: number;
  top3: number;
  top5: number;
  misses: SearchEvalCase[];
};

packages/search/
  src/
    document.ts
    extract.ts
    chunk.ts
    tokenize.ts
    weights.ts
    index-json.ts
    index-inverted.ts
    query.ts
    rank.ts
    client.ts
    diagnostics.ts
    eval.ts
    __tests__/
      tokenize.test.ts
      chunk.test.ts
      rank.test.ts
      api-search.test.ts
      config-field-search.test.ts

packages/static-build/src/stages/search.ts
packages/theme-default/src/components/SearchDialog.tsx