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

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

import type { ApiGroupOverrideType, Category, Maybe, MDXSupportType, Printer, 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
 * @useDeclaredType
 *
 * @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
 * @useDeclaredType
 *
 * @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
 * @useDeclaredType
 *
 * @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.
 * @useDeclaredType
 * @example
 */
export declare class Renderer {
    group: Maybe<SchemaEntitiesGroupMap>;
    outputDir: string;
    baseURL: string;
    prettify: boolean;
    options: Maybe<RendererDocOptions>;
    mdxModule: unknown;
    mdxModuleIndexFileSupport: boolean;
    private readonly printer;
    /**
     * 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 mdxModule - Optional MDX module for enhanced documentation features
     * @example
     */
    constructor(printer: Printer, outputDir: string, baseURL: string, group: Maybe<SchemaEntitiesGroupMap>, prettify: boolean, docOptions: Maybe<RendererDocOptions>, mdxModule?: unknown);
    /**
     * Checks if the provided module supports MDX index file generation.
     *
     * @param module - The module to check for MDX support
     * @returns True if the module supports index metafile generation
     * @useDeclaredType
     * @example
     */
    hasMDXIndexFileSupport(module?: unknown): module is Partial<MDXSupportType> & Pick<MDXSupportType, "generateIndexMetafile">;
    /**
     * 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
     * @useDeclaredType
     *
     * @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
     * @useDeclaredType
     * @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
     * @useDeclaredType
     * @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
     * @useDeclaredType
     * @example
     */
    renderTypeEntities(dirPath: string, name: string, type: unknown): Promise<Maybe<Category>>;
    /**
     * 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
     * @useDeclaredType
     * @example
     */
    renderHomepage(homepageLocation: Maybe<string>): Promise<void>;
}
/**
 * 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 mdxModule - Optional MDX module for enhanced features
 * @returns A configured Renderer instance
 * @useDeclaredType
 *
 * @example
 * ```typescript
 * const renderer = await getRenderer(
 *   myPrinter,
 *   './docs',
 *   '/api',
 *   groupConfig,
 *   true,
 *   { force: true, index: true }
 * );
 * ```
 */
export declare const getRenderer: (printer: Printer, outputDir: string, baseURL: string, group: Maybe<SchemaEntitiesGroupMap>, prettify: boolean, docOptions: Maybe<RendererDocOptions>, mdxModule?: unknown) => Promise<InstanceType<typeof Renderer>>;