polen/build/api/content/sidebar.d.ts

A framework for delightful GraphQL developer portals

import type { ScanResult } from './scan.js';
/**
 * Represents a complete sidebar structure with navigation items.
 * This is the main data structure used to render sidebars in the UI.
 */
export interface Sidebar {
    /** Array of navigation items that can be either direct links or sections containing multiple links */
    items: Item[];
}
/**
 * A sidebar navigation item that can be either a direct link or a section containing multiple links.
 * @see {@link ItemLink} for direct navigation links
 * @see {@link ItemSection} for grouped navigation sections
 */
export type Item = ItemLink | ItemSection;
/**
 * A direct navigation link in the sidebar.
 * Used for pages that don't have child pages.
 *
 * @example
 * ```ts
 * const link: ItemLink = {
 *   type: 'ItemLink',
 *   title: 'Get Started',
 *   pathExp: 'guide/get-started'
 * }
 * ```
 */
export interface ItemLink {
    /** Discriminator for TypeScript union types */
    type: `ItemLink`;
    /** Display title for the link (e.g., "Get Started") */
    title: string;
    /** Path expression relative to the base path, without leading slash (e.g., "guide/get-started") */
    pathExp: string;
}
/**
 * A collapsible section in the sidebar that groups related links.
 * Used for directories that contain multiple pages.
 *
 * @example
 * ```ts
 * const section: ItemSection = {
 *   type: 'ItemSection',
 *   title: 'Guide',
 *   pathExp: 'guide',
 *   isLinkToo: true, // Has an index page
 *   links: [
 *     { type: 'ItemLink', title: 'Installation', pathExp: 'guide/installation' },
 *     { type: 'ItemLink', title: 'Configuration', pathExp: 'guide/configuration' }
 *   ]
 * }
 * ```
 */
export interface ItemSection {
    /** Discriminator for TypeScript union types */
    type: `ItemSection`;
    /** Display title for the section (e.g., "Guide", "API Reference") */
    title: string;
    /** Path expression for the section's index page, if it exists (e.g., "guide") */
    pathExp: string;
    /** Whether this section also acts as a link (true if the directory has an index page) */
    isLinkToo: boolean;
    /** Child navigation links within this section */
    links: ItemLink[];
}
/**
 * A mapping of route paths to their corresponding sidebar structures.
 * Used to store different sidebars for different sections of a site.
 *
 * @example
 * ```ts
 * const sidebarIndex: SidebarIndex = {
 *   '/guide': { items: [...] },     // Sidebar for /guide section
 *   '/api': { items: [...] },       // Sidebar for /api section
 *   '/reference': { items: [...] }  // Sidebar for /reference section
 * }
 * ```
 */
export type SidebarIndex = Record<string, Sidebar>;
/**
 * Builds sidebars for all top-level directories that contain both an index page and nested content.
 *
 * This function analyzes a scan result to identify which directories should have sidebars.
 * A directory gets a sidebar if it meets these criteria:
 * 1. It's a top-level directory (e.g., /guide, /api, /docs)
 * 2. It has an index page (e.g., /guide/index.md)
 * 3. It has nested pages (e.g., /guide/getting-started.md, /guide/configuration.md)
 *
 * @param scanResult - The result of scanning pages, containing both a flat list and tree structure
 * @returns A mapping of route paths to sidebar structures
 *
 * @example
 * ```ts
 * const scanResult = await Content.scan({ dir: './pages' })
 * const sidebars = buildSidebarIndex(scanResult)
 * // Returns: {
 * //   '/guide': { items: [...] },
 * //   '/api': { items: [...] }
 * // }
 * ```
 */
export declare const buildSidebarIndex: (scanResult: ScanResult) => SidebarIndex;
//# sourceMappingURL=sidebar.d.ts.map