Skip to main content

renderer

Renderer​

Defined in: packages/core/src/renderer.ts:376

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​

Constructors​

Constructor​

new Renderer(options): Renderer;

Defined in: packages/core/src/renderer.ts:395

Creates a new Renderer instance.

Parameters​
options​

RendererOptions

Renderer construction options

Returns​

Renderer

Example​

Properties​

baseURL​

readonly baseURL: string;

Defined in: packages/core/src/renderer.ts:379

group​

readonly group: Maybe<Partial<Record<SchemaEntity, Record<string, Maybe<string>>>>>;

Defined in: packages/core/src/renderer.ts:377

mdxExtension​

readonly mdxExtension: string;

Defined in: packages/core/src/renderer.ts:382

options​

readonly options: Maybe<RendererDocOptions>;

Defined in: packages/core/src/renderer.ts:381

outputAdapter​

readonly outputAdapter: OutputAdapter;

Defined in: packages/core/src/renderer.ts:383

outputDir​

readonly outputDir: string;

Defined in: packages/core/src/renderer.ts:378

prettify​

readonly prettify: boolean;

Defined in: packages/core/src/renderer.ts:380

Methods​

generateCategoryMetafileType()​

generateCategoryMetafileType(
   type,
   name,
   rootTypeName
): Promise<string>;

Defined in: packages/core/src/renderer.ts:500

Generates the directory path and metafiles for a specific schema entity type. Creates the appropriate directory structure based on configuration options.

Parameters​
type​

unknown

The schema entity type

name​

string

The name of the schema entity

rootTypeName​

SchemaEntity

The root type name this entity belongs to

Returns​

Promise<string>

The generated directory path

Example​

generateIndexMetafile()​

generateIndexMetafile(
   dirPath,
   category,
   options?
): Promise<void>;

Defined in: packages/core/src/renderer.ts:445

Generates an index metafile for a category directory if MDX support is available.

Parameters​
dirPath​

string

The directory path where the index should be created

category​

string

The category name

options?​

CategoryMetafileOptions

Configuration options for the index

Returns​

Promise<void>

Promise that resolves when the index is generated

Example​
await renderer.generateIndexMetafile("docs/types", "Types", {
  collapsible: true,
  collapsed: false,
});

preCollectCategories()​

preCollectCategories(rootTypeNames): void;

Defined in: packages/core/src/renderer.ts:796

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"

Parameters​
rootTypeNames​

string[]

Array of root type names from the schema

Returns​

void

renderHomepage()​

renderHomepage(homepageLocation): Promise<void>;

Defined in: packages/core/src/renderer.ts:846

Renders the homepage for the documentation from a template file. Replaces placeholders in the template with actual values.

Parameters​
homepageLocation​

Maybe<string>

Path to the homepage template file

Returns​

Promise<void>

Promise that resolves when the homepage is rendered

Example​

renderRootTypes()​

renderRootTypes(rootTypeName, type): Promise<Maybe<Maybe<Category>[]>>;

Defined in: packages/core/src/renderer.ts:584

Renders all types within a root type category (e.g., all Query types).

Parameters​
rootTypeName​

SchemaEntity

The name of the root type (e.g., "Query", "Mutation")

type​

unknown

The type object containing all entities to render

Returns​

Promise<Maybe<Maybe<Category>[]>>

Array of rendered categories or undefined

Example​

renderTypeEntities()​

renderTypeEntities(
   dirPath,
   name,
   type,
   operationNamespaceParts?,
   entity?
): Promise<Maybe<Category>>;

Defined in: packages/core/src/renderer.ts:654

Renders documentation for a specific type entity and saves it to a file.

Parameters​
dirPath​

string

The directory path where the file should be saved

name​

string

The name of the type entity

type​

unknown

The type entity to render

operationNamespaceParts?​

string[]

The namespace parts for a namespaced operation

entity?​

SchemaEntity

The schema entity kind being rendered, e.g. queries

Returns​

Promise<Maybe<Category>>

The category information for the rendered entity or undefined

Example​

CategoryMetafileOptions​

Defined in: packages/core/src/renderer.ts:221

Configuration options for category metafiles in the documentation. These options control the appearance and behavior of category sections in the sidebar.

CategoryMetafileOptions

Example​

const options: CategoryMetafileOptions = {
  collapsible: true,
  collapsed: false,
  sidebarPosition: SidebarPosition.FIRST,
  styleClass: CATEGORY_STYLE_CLASS.API,
};

Properties​

collapsed?​

optional collapsed?: boolean;

Defined in: packages/core/src/renderer.ts:223

Whether the category should be initially collapsed

collapsible?​

optional collapsible?: boolean;

Defined in: packages/core/src/renderer.ts:222

Whether the category should be collapsible in the sidebar

sidebarPosition?​

optional sidebarPosition?: number;

Defined in: packages/core/src/renderer.ts:224

Custom position in the sidebar (lower numbers appear first)

styleClass?​

optional styleClass?: string;

Defined in: packages/core/src/renderer.ts:225

CSS class to apply to the category for styling

RendererOptions​

Defined in: packages/core/src/renderer.ts:344

Constructor options for Renderer, and input to getRenderer.

Properties​

baseURL​

baseURL: string;

Defined in: packages/core/src/renderer.ts:350

Base URL for the documentation

docOptions​

docOptions: Maybe<RendererDocOptions>;

Defined in: packages/core/src/renderer.ts:356

Additional documentation options

group​

group: Maybe<Partial<Record<SchemaEntity, Record<string, Maybe<string>>>>>;

Defined in: packages/core/src/renderer.ts:352

Optional grouping configuration for schema entities

mdxExtension​

mdxExtension: string;

Defined in: packages/core/src/renderer.ts:358

Optional MDX file extension to use

outputAdapter?​

optional outputAdapter?: OutputAdapter | null;

Defined in: packages/core/src/renderer.ts:360

Destination for generated pages; defaults to the local filesystem

outputDir​

outputDir: string;

Defined in: packages/core/src/renderer.ts:348

Directory where documentation will be generated

prettify​

prettify: boolean;

Defined in: packages/core/src/renderer.ts:354

Whether to format the generated markdown

printer​

printer: typeof IPrinter;

Defined in: packages/core/src/renderer.ts:346

The printer instance used to convert GraphQL types to markdown

API_GROUPS​

const API_GROUPS: Required<ApiGroupOverrideType>;

Defined in: packages/core/src/renderer.ts:125

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.

Example​

// Default structure
const defaultGroups = API_GROUPS;
// { operations: "operations", types: "types" }

// With custom override
const customGroups = { ...API_GROUPS, operations: "queries-and-mutations" };

See​

getApiGroupFolder For usage with type categorization

getApiGroupFolder()​

function getApiGroupFolder(type, groups?): string;

Defined in: packages/core/src/renderer.ts:147

Determines the appropriate folder for a GraphQL schema entity based on its type.

Parameters​

type​

unknown

The GraphQL schema entity to categorize

groups?​

Maybe<boolean | ApiGroupOverrideType>

Optional custom group naming configuration

Returns​

string

The folder name where the entity should be placed

Example​

// With default groups
const folder = getApiGroupFolder(queryType); // Returns "operations"

// With custom groups
const folder = getApiGroupFolder(objectType, { operations: "queries" }); // Returns appropriate folder

getRenderer()​

function getRenderer(options): Promise<Renderer>;

Defined in: packages/core/src/renderer.ts:1094

Factory function to create and initialize a Renderer instance. Creates the output directory and returns a configured renderer.

Parameters​

options​

RendererOptions

Renderer construction options

Returns​

Promise<Renderer>

A configured Renderer instance

Example​

const renderer = await getRenderer({
  printer: myPrinter,
  outputDir: "./docs",
  baseURL: "/api",
  group: groupConfig,
  prettify: true,
  docOptions: { force: true, index: true },
  mdxExtension: ".mdx",
});

logHandlerErrors()​

function logHandlerErrors(eventName, errors): void;

Defined in: packages/core/src/renderer.ts:335

Reports errors thrown by event handlers.

Handler errors are collected rather than thrown, so without this they are dropped and the formatter's post-processing silently does nothing.

Parameters​

eventName​

string

Name of the emitted event

errors​

Error[]

Errors collected from the handlers

Returns​

void