@graphql-markdown/core/dist/renderer.d.ts

GraphQL-Markdown core package for generating Markdown documentation from a GraphQL schema.

import type { ApiGroupOverrideType, Category, Maybe, IPrinter, RendererDocOptions, SchemaEntitiesGroupMap, SchemaEntity } from "@graphql-markdown/types";
/**
 * Default group names for API types and non-API types.
 * This constant provides the base folder structure for organizing GraphQL schema entities.
 * Can be overridden via ApiGroupOverrideType in configuration.
 *
 * @property operations Folder name for GraphQL operations (queries, mutations, subscriptions)
 * @property types Folder name for GraphQL type definitions
 *
 * @example
 * ```typescript
 * // Default structure
 * const defaultGroups = API_GROUPS;
 * // { operations: "operations", types: "types" }
 *
 * // With custom override
 * const customGroups = { ...API_GROUPS, operations: "queries-and-mutations" };
 * ```
 *
 * @see {@link getApiGroupFolder} For usage with type categorization
 */
export declare const API_GROUPS: Required<ApiGroupOverrideType>;
/**
 * Determines the appropriate folder for a GraphQL schema entity based on its type.
 *
 * @param type - The GraphQL schema entity to categorize
 * @param groups - Optional custom group naming configuration
 * @returns The folder name where the entity should be placed
 *
 * @example
 * ```typescript
 * // With default groups
 * const folder = getApiGroupFolder(queryType); // Returns "operations"
 *
 * // With custom groups
 * const folder = getApiGroupFolder(objectType, { operations: "queries" }); // Returns appropriate folder
 * ```
 */
export declare const getApiGroupFolder: (type: unknown, groups?: Maybe<ApiGroupOverrideType | boolean>) => string;
/**
 * Configuration options for category metafiles in the documentation.
 * These options control the appearance and behavior of category sections in the sidebar.
 *
 * @interface CategoryMetafileOptions
 * @property [collapsible] - Whether the category should be collapsible in the sidebar
 * @property [collapsed] - Whether the category should be initially collapsed
 * @property [sidebarPosition] - Custom position in the sidebar (lower numbers appear first)
 * @property [styleClass] - CSS class to apply to the category for styling
 *
 * @example
 * ```typescript
 * const options: CategoryMetafileOptions = {
 *   collapsible: true,
 *   collapsed: false,
 *   sidebarPosition: SidebarPosition.FIRST,
 *   styleClass: CATEGORY_STYLE_CLASS.API
 * };
 * ```
 */
export interface CategoryMetafileOptions {
    collapsible?: boolean;
    collapsed?: boolean;
    sidebarPosition?: number;
    styleClass?: string;
}
/**
 * Core renderer class responsible for generating documentation files from GraphQL schema entities.
 * Handles the conversion of schema types to markdown/MDX documentation with proper organization.
 *
 * HIERARCHY LEVELS WHEN categorySort IS ENABLED:
 * - Level 0 (root): Query, Mutation, Subscription, Custom Groups → 01-Query, 02-Mutation, etc.
 * - Level 1 (under root): Specific types within each root → 01-Objects, 02-Enums, etc.
 *
 * Each level has its own CategoryPositionManager that restarts numbering at 1.
 * @example
 */
export declare class Renderer {
    readonly group: Maybe<SchemaEntitiesGroupMap>;
    readonly outputDir: string;
    readonly baseURL: string;
    readonly prettify: boolean;
    readonly options: Maybe<RendererDocOptions>;
    readonly mdxExtension: string;
    private readonly printer;
    private readonly rootLevelPositionManager;
    private readonly categoryPositionManager;
    /**
     * Creates a new Renderer instance.
     *
     * @param printer - The printer instance used to convert GraphQL types to markdown
     * @param outputDir - Directory where documentation will be generated
     * @param baseURL - Base URL for the documentation
     * @param group - Optional grouping configuration for schema entities
     * @param prettify - Whether to format the generated markdown
     * @param docOptions - Additional documentation options
     * @param mdxExtension - Optional MDX file extension to use
     * @example
     */
    constructor(printer: typeof IPrinter, outputDir: string, baseURL: string, group: Maybe<SchemaEntitiesGroupMap>, prettify: boolean, docOptions: Maybe<RendererDocOptions>, mdxExtension: string);
    /**
     * Generates an index metafile for a category directory if MDX support is available.
     *
     * @param dirPath - The directory path where the index should be created
     * @param category - The category name
     * @param options - Configuration options for the index
     * @returns Promise that resolves when the index is generated
     *
     * @example
     * ```typescript
     * await renderer.generateIndexMetafile('docs/types', 'Types', {
     *   collapsible: true,
     *   collapsed: false
     * });
     * ```
     */
    generateIndexMetafile(dirPath: string, category: string, options?: CategoryMetafileOptions): Promise<void>;
    /**
     * Generates the directory path and metafiles for a specific schema entity type.
     * Creates the appropriate directory structure based on configuration options.
     *
     * @param type - The schema entity type
     * @param name - The name of the schema entity
     * @param rootTypeName - The root type name this entity belongs to
     * @returns The generated directory path
     * @example
     */
    generateCategoryMetafileType(type: unknown, name: string, rootTypeName: SchemaEntity): Promise<string>;
    /**
     * Renders all types within a root type category (e.g., all Query types).
     *
     * @param rootTypeName - The name of the root type (e.g., "Query", "Mutation")
     * @param type - The type object containing all entities to render
     * @returns Array of rendered categories or undefined
     * @example
     */
    renderRootTypes(rootTypeName: SchemaEntity, type: unknown): Promise<Maybe<Maybe<Category>[]>>;
    /**
     * Renders documentation for a specific type entity and saves it to a file.
     *
     * @param dirPath - The directory path where the file should be saved
     * @param name - The name of the type entity
     * @param type - The type entity to render
     * @returns The category information for the rendered entity or undefined
     * @example
     */
    renderTypeEntities(dirPath: string, name: string, type: unknown, operationNamespaceParts?: string[]): Promise<Maybe<Category>>;
    /**
     * Pre-collects all category names that will be generated during rendering.
     * This allows the position manager to assign consistent positions before
     * any files are written.
     *
     * HIERARCHY LEVELS:
     * - Root level: Query, Mutation, Subscription, Deprecated (when grouped), custom root groups
     * - Nested level: operations/types (API groups), custom groups under roots
     *
     * CRITICAL: Categories registered must match the NAMES USED BY THE PRINTER
     * when generating links. The printer uses plural forms from ROOT_TYPE_LOCALE:
     * "operations", "objects", "directives", "enums", "inputs", "interfaces",
     * "mutations", "queries", "scalars", "subscriptions", "unions"
     *
     * NOT the folder names: "operations", "types"
     *
     * @param rootTypeNames - Array of root type names from the schema
     */
    preCollectCategories(rootTypeNames: string[]): void;
    /**
     * Renders the homepage for the documentation from a template file.
     * Replaces placeholders in the template with actual values.
     *
     * @param homepageLocation - Path to the homepage template file
     * @returns Promise that resolves when the homepage is rendered
     * @example
     */
    renderHomepage(homepageLocation: Maybe<string>): Promise<void>;
    /**
     * Registers custom group names from the current group configuration.
     * Custom groups are always registered at the ROOT level.
     *
     * @param rootCategories - Set to add custom group names to
     */
    private registerCustomGroups;
    /**
     * Registers API group categories (operations/types) based on hierarchy and group configuration.
     *
     * @param rootCategories - Set to add root-level categories
     * @param nestedCategories - Set to add nested-level categories
     * @param hasCustomGroups - Whether custom groups are configured
     */
    private registerApiGroupCategories;
    /**
     * Registers entity hierarchy categories based on configuration.
     *
     * @param rootCategories - Set to add root-level categories
     * @param nestedCategories - Set to add nested-level categories
     * @param rootTypeNames - Array of root type names from schema
     * @param hasCustomGroups - Whether custom groups are configured
     */
    private registerEntityCategories;
    /**
     * Registers collected categories with appropriate position managers.
     * Handles both hierarchical numbering (when categorySort is enabled) and traditional modes.
     *
     * @param rootCategories - Set of root-level categories
     * @param nestedCategories - Set of nested-level categories
     */
    private registerCategoriesWithManagers;
    /**
     * Formats a category folder name, optionally prefixing with an order number.
     *
     * Supports hierarchical numbering:
     * - Root level items (Query, Mutation, etc.) use rootLevelPositionManager
     * - Nested items (groups, types within roots) use categoryPositionManager
     *
     * @param categoryName - The category name to format
     * @param isRootLevel - Whether this category is at the root level (default: false for nested)
     * @returns The formatted folder name (e.g., "01-objects" if prefix is enabled)
     * @private
     */
    private formatCategoryFolderName;
}
/**
 * Factory function to create and initialize a Renderer instance.
 * Creates the output directory and returns a configured renderer.
 *
 * @param printer - The printer instance to use for rendering types
 * @param outputDir - The output directory for generated documentation
 * @param baseURL - The base URL for the documentation
 * @param group - Optional grouping configuration
 * @param prettify - Whether to prettify the output markdown
 * @param docOptions - Additional documentation options
 * @param mdxExtension - Extension to use for MDX files
 * @returns A configured Renderer instance
 *
 * @example
 * ```typescript
 * const renderer = await getRenderer(
 *   myPrinter,
 *   './docs',
 *   '/api',
 *   groupConfig,
 *   true,
 *   { force: true, index: true }
 * );
 * ```
 */
export declare const getRenderer: (printer: typeof IPrinter, outputDir: string, baseURL: string, group: Maybe<SchemaEntitiesGroupMap>, prettify: boolean, docOptions: Maybe<RendererDocOptions>, mdxExtension: string) => Promise<InstanceType<typeof Renderer>>;
//# sourceMappingURL=renderer.d.ts.map