Skip to main content

renderer

Renderer​

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

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(
   printer,
   outputDir,
   baseURL,
   group,
   prettify,
   docOptions,
   mdxExtension): Renderer;

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

Creates a new Renderer instance.

Parameters​
printer​

typeof IPrinter

The printer instance used to convert GraphQL types to markdown

outputDir​

string

Directory where documentation will be generated

baseURL​

string

Base URL for the documentation

group​

Maybe<Partial<Record<SchemaEntity, Record<string, Maybe<string>>>>>

Optional grouping configuration for schema entities

prettify​

boolean

Whether to format the generated markdown

docOptions​

Maybe<RendererDocOptions>

Additional documentation options

mdxExtension​

string

Optional MDX file extension to use

Returns​

Renderer

Example​

Properties​

baseURL​

readonly baseURL: string;

Defined in: core/src/renderer.ts:338

group​

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

Defined in: core/src/renderer.ts:336

mdxExtension​

readonly mdxExtension: string;

Defined in: core/src/renderer.ts:341

options​

readonly options: Maybe<RendererDocOptions>;

Defined in: core/src/renderer.ts:340

outputDir​

readonly outputDir: string;

Defined in: core/src/renderer.ts:337

prettify​

readonly prettify: boolean;

Defined in: core/src/renderer.ts:339

Methods​

generateCategoryMetafileType()​

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

Defined in: core/src/renderer.ts:463

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: core/src/renderer.ts:408

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: core/src/renderer.ts:753

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: core/src/renderer.ts:803

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: core/src/renderer.ts:547

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?): Promise<Maybe<Category>>;

Defined in: core/src/renderer.ts:614

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[]

Returns​

Promise<Maybe<Category>>

The category information for the rendered entity or undefined

Example​

CategoryMetafileOptions​

Defined in: core/src/renderer.ts:219

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: core/src/renderer.ts:221

Whether the category should be initially collapsed

collapsible?​

optional collapsible?: boolean;

Defined in: core/src/renderer.ts:220

Whether the category should be collapsible in the sidebar

sidebarPosition?​

optional sidebarPosition?: number;

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

Custom position in the sidebar (lower numbers appear first)

styleClass?​

optional styleClass?: string;

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

CSS class to apply to the category for styling

API_GROUPS​

const API_GROUPS: Required<ApiGroupOverrideType>;

Defined in: core/src/renderer.ts:124

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: core/src/renderer.ts:145

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(
  printer,
  outputDir,
  baseURL,
  group,
  prettify,
  docOptions,
  mdxExtension,
): Promise<Renderer>;

Defined in: core/src/renderer.ts:1035

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

Parameters​

printer​

typeof IPrinter

The printer instance to use for rendering types

outputDir​

string

The output directory for generated documentation

baseURL​

string

The base URL for the documentation

group​

Maybe<Partial<Record<SchemaEntity, Record<string, Maybe<string>>>>>

Optional grouping configuration

prettify​

boolean

Whether to prettify the output markdown

docOptions​

Maybe<RendererDocOptions>

Additional documentation options

mdxExtension​

string

Extension to use for MDX files

Returns​

Promise<Renderer>

A configured Renderer instance

Example​

const renderer = await getRenderer(
  myPrinter,
  "./docs",
  "/api",
  groupConfig,
  true,
  { force: true, index: true },
);