Overview -> Quickstart -> Concepts -> Guides -> Reference -> Troubleshooting

README -> Config.ts -> UserController -> random generated page -> OpenAPI

export type PageId = string & { readonly brand: unique symbol };
export type RoutePath = string & { readonly brand: unique symbol };

export type PageKind =
  | "overview"
  | "quickstart"
  | "concept"
  | "howTo"
  | "reference"
  | "apiReference"
  | "troubleshooting"
  | "migration"
  | "architecture"
  | "adr";

export type PageManifestEntry = {
  id: PageId;
  sourcePath: string;
  route: RoutePath;
  title: string;
  description: string;
  kind: PageKind;
  navTitle?: string;
  order?: number;
  tags: string[];
  generated: boolean;
  draft: boolean;
  hidden: boolean;
  canonical?: RoutePath;
  redirects?: RoutePath[];
};

export type NavNode =
  | NavGroupNode
  | NavPageNode
  | NavLinkNode
  | NavGeneratedSectionNode;

export type NavGroupNode = {
  type: "group";
  title: string;
  children: NavNode[];
  collapsed?: boolean;
};

export type NavPageNode = {
  type: "page";
  pageId: PageId;
  title?: string;
};

export type NavLinkNode = {
  type: "link";
  title: string;
  href: string;
  external?: boolean;
};

export type NavGeneratedSectionNode = {
  type: "generatedSection";
  id: string;
  source: "apiReference" | "guides" | "concepts" | "troubleshooting";
  title: string;
  options?: Record<string, unknown>;
};

export type RouteRecord = {
  pageId: PageId;
  route: RoutePath;
  sourcePath: string;
  title: string;
  anchors: Set<string>;
};

export type RouteIndex = {
  byRoute: Map<RoutePath, RouteRecord>;
  byPageId: Map<PageId, RouteRecord>;
  bySourcePath: Map<string, RouteRecord>;
};

{
  "pages": [
    {
      "id": "quickstart",
      "sourcePath": "docs/quickstart.mdx",
      "route": "/quickstart",
      "title": "Quickstart",
      "description": "Generate and preview documentation from a repository.",
      "kind": "quickstart",
      "order": 1,
      "generated": true,
      "draft": false,
      "hidden": false
    }
  ]
}

export function routeFromSourcePath(docsRoot: string, sourcePath: string): RoutePath {
  const relative = normalizeRelativePath(docsRoot, sourcePath);

  const withoutExtension = relative.replace(/\.mdx?$/, "");

  if (withoutExtension === "index") {
    return "/" as RoutePath;
  }

  if (withoutExtension.endsWith("/index")) {
    return (`/${withoutExtension.slice(0, -"/index".length)}` || "/") as RoutePath;
  }

  return (`/${withoutExtension}`) as RoutePath;
}

docs/guides/install.mdx -> /guides/install
docs/guides/install/index.mdx -> /guides/install

export function validateRouteCollisions(entries: PageManifestEntry[]): Diagnostic[] {
  const byRoute = new Map<string, PageManifestEntry[]>();

  for (const entry of entries) {
    const existing = byRoute.get(entry.route) ?? [];
    existing.push(entry);
    byRoute.set(entry.route, existing);
  }

  const diagnostics: Diagnostic[] = [];

  for (const [route, routeEntries] of byRoute) {
    if (routeEntries.length <= 1) {
      continue;
    }

    diagnostics.push({
      code: "nav.route.collision",
      severity: "error",
      category: "structure",
      message: `Multiple pages resolve to the same route: ${route}.`,
      location: { path: routeEntries[0]!.sourcePath },
      related: routeEntries.slice(1).map((entry) => ({ path: entry.sourcePath })),
      hint: "Rename one page or configure an explicit route override.",
    });
  }

  return diagnostics;
}

{
  "navigation": [
    {
      "type": "group",
      "title": "Get started",
      "children": [
        { "type": "page", "path": "index.mdx" },
        { "type": "page", "path": "quickstart.mdx" }
      ]
    }
  ]
}

{
  "navigation": [
    {
      "type": "group",
      "title": "Start here",
      "children": [
        { "type": "page", "path": "index.mdx" },
        { "type": "page", "path": "quickstart.mdx" }
      ]
    },
    {
      "type": "generatedSection",
      "id": "api-reference",
      "source": "apiReference",
      "title": "API Reference"
    }
  ]
}

export const NavPageNodeSchema = z.object({
  type: z.literal("page"),
  path: z.string().min(1),
  title: z.string().optional(),
});

export const NavLinkNodeSchema = z.object({
  type: z.literal("link"),
  title: z.string().min(1),
  href: z.string().min(1),
  external: z.boolean().optional(),
});

export const NavGeneratedSectionNodeSchema = z.object({
  type: z.literal("generatedSection"),
  id: z.string().min(1),
  source: z.enum(["apiReference", "guides", "concepts", "troubleshooting"]),
  title: z.string().min(1),
  options: z.record(z.unknown()).optional(),
});

export type NavNodeInput =
  | z.infer<typeof NavPageNodeSchema>
  | z.infer<typeof NavLinkNodeSchema>
  | z.infer<typeof NavGeneratedSectionNodeSchema>
  | {
      type: "group";
      title: string;
      collapsed?: boolean;
      children: NavNodeInput[];
    };

export const NavNodeSchema: z.ZodType<NavNodeInput> = z.lazy(() =>
  z.discriminatedUnion("type", [
    NavPageNodeSchema,
    NavLinkNodeSchema,
    NavGeneratedSectionNodeSchema,
    z.object({
      type: z.literal("group"),
      title: z.string().min(1),
      collapsed: z.boolean().optional(),
      children: z.array(NavNodeSchema),
    }),
  ])
);

export const NavigationSchema = z.array(NavNodeSchema);

export function resolveNavigation(
  input: NavNodeInput[],
  manifest: PageManifest
): ResolvedNavigation {
  const diagnostics: Diagnostic[] = [];
  const nodes = input.map((node) => resolveNavNode(node, manifest, diagnostics));

  return {
    nodes: nodes.filter(Boolean) as NavNode[],
    diagnostics,
  };
}

function resolvePageNode(
  node: { path: string; title?: string },
  manifest: PageManifest,
  diagnostics: Diagnostic[]
): NavPageNode | undefined {
  const page = manifest.bySourcePath.get(normalizePath(node.path));

  if (!page) {
    diagnostics.push({
      code: "nav.page.notFound",
      severity: "error",
      category: "structure",
      message: `Navigation references a page that does not exist: ${node.path}.`,
      location: { path: "docforge.config.json" },
      hint: "Check the path or remove the nav entry.",
    });
    return undefined;
  }

  return {
    type: "page",
    pageId: page.id,
    title: node.title,
  };
}

const DEFAULT_KIND_GROUPS: Array<{
  title: string;
  kinds: PageKind[];
}> = [
  { title: "Start here", kinds: ["overview", "quickstart"] },
  { title: "Concepts", kinds: ["concept", "architecture"] },
  { title: "Guides", kinds: ["howTo"] },
  { title: "Reference", kinds: ["reference"] },
  { title: "API Reference", kinds: ["apiReference"] },
  { title: "Troubleshooting", kinds: ["troubleshooting"] },
  { title: "Migration", kinds: ["migration"] },
  { title: "Decisions", kinds: ["adr"] },
];

export function inferNavigation(manifest: PageManifest): NavNode[] {
  const visiblePages = manifest.pages.filter((page) => !page.hidden && !page.draft);

  const groups: NavGroupNode[] = [];

  for (const group of DEFAULT_KIND_GROUPS) {
    const pages = visiblePages
      .filter((page) => group.kinds.includes(page.kind))
      .sort(comparePagesForNav);

    if (pages.length === 0) {
      continue;
    }

    groups.push({
      type: "group",
      title: group.title,
      children: pages.map((page) => ({
        type: "page",
        pageId: page.id,
      })),
    });
  }

  return groups;
}

export function comparePagesForNav(a: PageManifestEntry, b: PageManifestEntry): number {
  if (a.order != null && b.order != null) {
    return a.order - b.order;
  }

  if (a.order != null) return -1;
  if (b.order != null) return 1;

  return a.route.localeCompare(b.route);
}

{
  "type": "generatedSection",
  "id": "api-reference",
  "source": "apiReference",
  "title": "API Reference",
  "options": {
    "groupBy": "tag"
  }
}

export function expandGeneratedSection(
  node: NavGeneratedSectionNode,
  manifest: PageManifest
): NavGroupNode {
  const pages = manifest.pages.filter((page) => {
    if (node.source === "apiReference") {
      return page.kind === "apiReference";
    }

    if (node.source === "guides") {
      return page.kind === "howTo";
    }

    if (node.source === "concepts") {
      return page.kind === "concept";
    }

    if (node.source === "troubleshooting") {
      return page.kind === "troubleshooting";
    }

    return false;
  });

  return {
    type: "group",
    title: node.title,
    children: groupGeneratedPages(node, pages),
  };
}

export type ApiPageMetadata = {
  operationId: string;
  method: string;
  path: string;
  tags: string[];
  resource?: string;
};

export function apiNavTitle(api: ApiPageMetadata, title: string): string {
  if (api.operationId) {
    return title;
  }

  return `${api.method.toUpperCase()} ${api.path}`;
}

export function groupApiPagesByTag(pages: ApiPage[]): NavNode[] {
  const byTag = new Map<string, ApiPage[]>();

  for (const page of pages) {
    const tag = page.api.tags[0] ?? "Other";
    const group = byTag.get(tag) ?? [];
    group.push(page);
    byTag.set(tag, group);
  }

  return [...byTag.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([tag, tagPages]) => ({
      type: "group",
      title: tag,
      children: tagPages
        .sort(compareApiOperations)
        .map((page) => ({ type: "page", pageId: page.id })),
    }));
}

const METHOD_ORDER = ["GET", "POST", "PUT", "PATCH", "DELETE"];

export function compareApiOperations(a: ApiPage, b: ApiPage): number {
  const pathCompare = a.api.path.localeCompare(b.api.path);

  if (pathCompare !== 0) {
    return pathCompare;
  }

  return METHOD_ORDER.indexOf(a.api.method) - METHOD_ORDER.indexOf(b.api.method);
}

export function validateNoDuplicateNavPages(nav: NavNode[]): Diagnostic[] {
  const seen = new Map<PageId, NavPageNode>();
  const diagnostics: Diagnostic[] = [];

  for (const pageNode of flattenNavPages(nav)) {
    const existing = seen.get(pageNode.pageId);

    if (existing) {
      diagnostics.push({
        code: "nav.page.duplicate",
        severity: "warning",
        category: "structure",
        message: `Page appears more than once in navigation.`,
        hint: "Keep duplicate nav entries only if the page intentionally belongs to multiple contexts.",
      });
    }

    seen.set(pageNode.pageId, pageNode);
  }

  return diagnostics;
}

export function findOrphanPages(
  manifest: PageManifest,
  nav: NavNode[]
): PageManifestEntry[] {
  const referenced = new Set<PageId>();

  for (const node of flattenNavPages(nav)) {
    referenced.add(node.pageId);
  }

  return manifest.pages.filter((page) => {
    return !page.hidden &&
      !page.draft &&
      !referenced.has(page.id);
  });
}

{
  code: "nav.page.orphan",
  severity: "warning",
  category: "structure",
  message: `Visible page is not included in navigation: ${page.sourcePath}.`,
  location: { path: page.sourcePath },
  hint: "Add the page to navigation, mark it hidden, or include it through a generated section.",
}

Start here / Quickstart

Guides / API Reference / Create User

export type BreadcrumbItem = {
  title: string;
  route?: RoutePath;
};

export type BreadcrumbIndex = Map<PageId, BreadcrumbItem[]>;

export function buildBreadcrumbIndex(
  nav: NavNode[],
  manifest: PageManifest
): BreadcrumbIndex {
  const index: BreadcrumbIndex = new Map();

  function visit(nodes: NavNode[], ancestors: BreadcrumbItem[]) {
    for (const node of nodes) {
      if (node.type === "group") {
        visit(node.children, [
          ...ancestors,
          { title: node.title },
        ]);
      }

      if (node.type === "page") {
        const page = manifest.byPageId.get(node.pageId);
        if (!page) continue;

        index.set(node.pageId, [
          ...ancestors,
          {
            title: node.title ?? page.navTitle ?? page.title,
            route: page.route,
          },
        ]);
      }
    }
  }

  visit(nav, []);

  return index;
}

export function flattenNavPageOrder(nav: NavNode[]): PageId[] {
  const ids: PageId[] = [];

  function visit(nodes: NavNode[]) {
    for (const node of nodes) {
      if (node.type === "page") {
        ids.push(node.pageId);
      }

      if (node.type === "group") {
        visit(node.children);
      }
    }
  }

  visit(nav);
  return ids;
}

export type PrevNext = {
  previous?: PageId;
  next?: PageId;
};

export function buildPrevNextIndex(nav: NavNode[]): Map<PageId, PrevNext> {
  const order = flattenNavPageOrder(nav);
  const index = new Map<PageId, PrevNext>();

  for (let i = 0; i < order.length; i++) {
    index.set(order[i]!, {
      previous: order[i - 1],
      next: order[i + 1],
    });
  }

  return index;
}

export type RelatedPage = {
  pageId: PageId;
  reason: "sameTag" | "sameApiTag" | "explicit" | "linked" | "generated";
  score: number;
};

export function findRelatedPages(
  page: PageManifestEntry,
  manifest: PageManifest
): RelatedPage[] {
  const related: RelatedPage[] = [];

  for (const candidate of manifest.pages) {
    if (candidate.id === page.id) {
      continue;
    }

    const sharedTags = intersection(page.tags, candidate.tags);

    if (sharedTags.length > 0) {
      related.push({
        pageId: candidate.id,
        reason: "sameTag",
        score: sharedTags.length,
      });
    }
  }

  return related
    .sort((a, b) => b.score - a.score)
    .slice(0, 5);
}

"Generate API Docs" -> "Generate API Reference"

/guides/generate-api-docs

/guides/generate-api-reference

{
  "api:createUser": "/api/users/create-user",
  "guide:install": "/guides/install"
}

export function resolveStableGeneratedRoute(
  generatedId: string,
  proposedRoute: string,
  routeLock: RouteLock
): string {
  const existing = routeLock.routes[generatedId];

  if (existing) {
    return existing;
  }

  routeLock.routes[generatedId] = proposedRoute;
  return proposedRoute;
}

export type Redirect = {
  from: RoutePath;
  to: RoutePath;
  status: 301 | 302 | 307 | 308;
};

canonical: /reference/configuration

draft: true

hidden: true

{
  "drafts": {
    "includeInDev": true,
    "includeInProduction": false
  },
  "hiddenPages": {
    "includeInSearch": false
  }
}

/v1/quickstart
/v2/quickstart

export type DocsVersion = {
  id: string;
  label: string;
  root: string;
  default?: boolean;
  deprecated?: boolean;
};

version?: string;

export type VersionedNavigation = {
  version: string;
  nodes: NavNode[];
};

Start here
Packages
  CLI
  SDK
  Server
API Reference
  Admin API
  Public API

export type PageManifestEntry = {
  packageName?: string;
  serviceName?: string;
  owner?: string;
  // ...
};

{
  "type": "generatedSection",
  "source": "apiReference",
  "title": "API Reference",
  "options": {
    "groupBy": ["service", "tag"]
  }
}

Overview
Quickstart
Guides
  Installation
  Basic usage
  Configuration
Reference
  CLI
  Config
Troubleshooting

Start here
  Overview
  Quickstart
  Authentication
Guides
  Create your first resource
  Pagination
  Errors
API Reference
  Users
  Projects
  Webhooks
SDKs
  JavaScript
  Python
Troubleshooting

Overview
Concepts
  Architecture
  Environments
  Ownership model
Guides
  Local setup
  Deploy service
  Add config
Reference
  CLI
  Config
  Policies
Runbooks
  Incident response
  Rollback

Start here
  Overview
  Quickstart
  Installation
Concepts
  Source artifacts
  Content IR
  MDX pipeline
  Provenance
Guides
  Generate docs from a repo
  Generate API reference
  Configure navigation
Reference
  CLI commands
  Config schema
  Components
API Reference
Troubleshooting

export const AiNavProposalSchema = z.object({
  groups: z.array(z.object({
    title: z.string(),
    pageIds: z.array(z.string()),
    rationale: z.string(),
  })),
  diagnostics: z.array(z.object({
    message: z.string(),
    severity: z.enum(["info", "warning"]),
  })),
});

Return only JSON matching the schema.
Use only page IDs from the provided list.
Do not invent pages.
Do not change routes.
Prefer task-oriented grouping.
Keep Start here short.
Put high-volume API reference under a generated section if possible.
If a page is low-confidence, include it in diagnostics instead of guessing.

export type RenderNavNode =
  | {
      type: "group";
      title: string;
      collapsed?: boolean;
      children: RenderNavNode[];
    }
  | {
      type: "page";
      title: string;
      route: RoutePath;
      active?: boolean;
    }
  | {
      type: "link";
      title: string;
      href: string;
      external?: boolean;
    };

export function toRenderNav(
  nav: NavNode[],
  manifest: PageManifest,
  activeRoute: RoutePath
): RenderNavNode[] {
  return nav.map((node) => {
    if (node.type === "group") {
      return {
        type: "group",
        title: node.title,
        collapsed: node.collapsed,
        children: toRenderNav(node.children, manifest, activeRoute),
      };
    }

    if (node.type === "page") {
      const page = manifest.byPageId.get(node.pageId)!;

      return {
        type: "page",
        title: node.title ?? page.navTitle ?? page.title,
        route: page.route,
        active: page.route === activeRoute,
      };
    }

    return node;
  });
}

{
  "items": [
    {
      "type": "group",
      "title": "Start here",
      "children": [
        {
          "type": "page",
          "title": "Overview",
          "route": "/"
        },
        {
          "type": "page",
          "title": "Quickstart",
          "route": "/quickstart"
        }
      ]
    }
  ]
}

{
  "pages": [
    {
      "id": "quickstart",
      "route": "/quickstart",
      "sourcePath": "docs/quickstart.mdx",
      "title": "Quickstart",
      "description": "Generate and preview documentation from a repository."
    }
  ]
}

warning nav.page.orphan docs/guides/deploy.mdx
Visible page is not included in navigation.

Hint:
Add it to navigation, mark it hidden, or include it through a generated section.

error nav.page.notFound docforge.config.json
Navigation references a page that does not exist: docs/setup.mdx.

Hint:
Check the path or remove the nav entry.

warning nav.group.tooLarge docforge.config.json
Group "Guides" contains 42 pages.

Hint:
Split the group into smaller task-oriented groups.

export function validateHasQuickstart(manifest: PageManifest): Diagnostic[] {
  const hasQuickstart = manifest.pages.some((page) => page.kind === "quickstart");

  if (hasQuickstart) {
    return [];
  }

  return [{
    code: "nav.ia.missingQuickstart",
    severity: "warning",
    category: "structure",
    message: "Documentation has no quickstart page.",
    hint: "Add a quickstart page that gives users the shortest path to a working result.",
  }];
}

packages/navigation/
  src/
    page-manifest.ts
    route.ts
    route-index.ts
    nav-schema.ts
    nav-resolve.ts
    nav-infer.ts
    generated-sections.ts
    breadcrumbs.ts
    prev-next.ts
    related.ts
    redirects.ts
    diagnostics.ts
    render-nav.ts
    __tests__/
      route.test.ts
      nav-resolve.test.ts
      nav-infer.test.ts
      breadcrumbs.test.ts
      orphan-pages.test.ts

export * from "./page-manifest";
export * from "./route";
export * from "./route-index";
export * from "./nav-schema";
export * from "./nav-resolve";
export * from "./nav-infer";
export * from "./breadcrumbs";
export * from "./prev-next";
export * from "./render-nav";

export function manifestEntryFromCompileResult(
  result: CompilePageResult
): PageManifestEntry | undefined {
  if (!result.frontmatter) {
    return undefined;
  }

  return {
    id: pageIdFromPath(result.path),
    sourcePath: result.path,
    route: routeFromSourcePath("docs", result.path),
    title: result.frontmatter.title,
    description: result.frontmatter.description,
    kind: result.frontmatter.kind,
    navTitle: result.frontmatter.navTitle,
    order: result.frontmatter.order,
    tags: result.frontmatter.tags ?? [],
    generated: result.frontmatter.generated ?? false,
    draft: result.frontmatter.draft ?? false,
    hidden: result.frontmatter.hidden ?? false,
  };
}

const compileResult = await compileSite(...);

const manifest = buildPageManifest(compileResult.pages);

const navResult = config.navigation
  ? resolveNavigation(config.navigation, manifest)
  : { nodes: inferNavigation(manifest), diagnostics: [] };

const expandedNav = expandGeneratedSections(navResult.nodes, manifest);

const navDiagnostics = validateNavigation(expandedNav, manifest);

const breadcrumbs = buildBreadcrumbIndex(expandedNav, manifest);
const prevNext = buildPrevNextIndex(expandedNav);

export type RenderSiteInput = {
  pages: CompiledPage[];
  manifest: PageManifest;
  navigation: RenderNavNode[];
  breadcrumbs: BreadcrumbIndex;
  prevNext: Map<PageId, PrevNext>;
};

export type RenderPageContext = {
  page: PageManifestEntry;
  nav: RenderNavNode[];
  breadcrumbs: BreadcrumbItem[];
  previous?: PageManifestEntry;
  next?: PageManifestEntry;
};

it("maps docs/index.mdx to root route", () => {
  expect(routeFromSourcePath("docs", "docs/index.mdx")).toBe("/");
});

it("maps nested index to directory route", () => {
  expect(routeFromSourcePath("docs", "docs/guides/index.mdx")).toBe("/guides");
});

it("detects route collisions", () => {
  const diagnostics = validateRouteCollisions([
    page({ sourcePath: "docs/a.mdx", route: "/a" }),
    page({ sourcePath: "docs/a/index.mdx", route: "/a" }),
  ]);

  expect(diagnostics).toContainEqual(
    expect.objectContaining({ code: "nav.route.collision" })
  );
});

it("warns when visible page is not in nav", () => {
  const manifest = manifestWithPages([
    page({ id: "quickstart", hidden: false, draft: false }),
  ]);

  const diagnostics = validateOrphans(manifest, []);

  expect(diagnostics).toContainEqual(
    expect.objectContaining({ code: "nav.page.orphan" })
  );
});

it("expands api reference generated section", () => {
  const nav = expandGeneratedSection({
    type: "generatedSection",
    id: "api",
    source: "apiReference",
    title: "API Reference",
  }, manifestWithApiPages());

  expect(nav.children.length).toBeGreaterThan(0);
});