config

Configuration management for GraphQL Markdown.

This module handles all aspects of configuration including:

• Loading and merging configuration from multiple sources
• Validating configuration values
• Providing defaults for missing options
• Processing special configuration options (directives, deprecated items, etc)

The configuration follows this precedence (highest to lowest):

1. CLI arguments
2. Config file options
3. GraphQL Config options
4. Default values

DeprecatedOption

Defined in: config.ts:96

Options for handling deprecated items in the schema.

• DEFAULT: Show deprecated items normally
• GROUP: Group deprecated items separately
• SKIP: Exclude deprecated items from documentation

Example

const deprecatedHandling = DeprecatedOption.GROUP;

Enumeration Members

DEFAULT

DEFAULT: "default";

Defined in: config.ts:97

GROUP

GROUP: "group";

Defined in: config.ts:98

SKIP

SKIP: "skip";

Defined in: config.ts:99

---

DiffMethod

Defined in: config.ts:78

Diff methods used to determine how schema changes are processed.

• NONE: No diffing is performed
• FORCE: Force regeneration of documentation regardless of schema changes

Example

const diffMethod = DiffMethod.FORCE;

Enumeration Members

FORCE

FORCE: "FORCE";

Defined in: config.ts:80

NONE

NONE: "NONE";

Defined in: config.ts:79

---

TypeHierarchy

Defined in: config.ts:60

Type hierarchy options for organizing schema documentation.

• API: Groups types by their role in the API (Query, Mutation, etc.)
• ENTITY: Groups types by their entity relationships
• FLAT: No grouping, all types in a flat structure

Example

const hierarchy = TypeHierarchy.API;

Enumeration Members

API

API: "api";

Defined in: config.ts:61

ENTITY

ENTITY: "entity";

Defined in: config.ts:62

FLAT

FLAT: "flat";

Defined in: config.ts:63

---

ASSET_HOMEPAGE_LOCATION

const ASSET_HOMEPAGE_LOCATION: string;

Defined in: config.ts:118

Location of the default homepage template.

---

DEFAULT_HIERARCHY

const DEFAULT_HIERARCHY: object;

Defined in: config.ts:129

Default hierarchy configuration using the API hierarchy type.

Type declaration

api

api: object = {};

---

DEFAULT_OPTIONS

const DEFAULT_OPTIONS: Readonly<Pick<ConfigOptions, "customDirective" | "groupByDirective" | "loaders"> & Required<Omit<ConfigOptions, 
  | "customDirective"
  | "groupByDirective"
  | "loaders"
  | "mdxParser"
  | "printTypeOptions">>> & object;

Defined in: config.ts:138

Default configuration options used when no user options are provided. These values serve as fallbacks for any missing configuration.

Type declaration

printTypeOptions

printTypeOptions: Required<Omit<ConfigPrintTypeOptions, "hierarchy">> & object;

Type declaration

hierarchy

hierarchy: Required<Pick<TypeHierarchyObjectType, API>>;

See

Options for the complete configuration interface

---

DOCS_URL

const DOCS_URL: "https://graphql-markdown.dev/docs";

Defined in: config.ts:106

Documentation website URL for reference in error messages and help text.

---

PACKAGE_NAME

const PACKAGE_NAME: "@graphql-markdown/docusaurus";

Defined in: config.ts:112

Default package name used for temporary directory creation and identification.

---

buildConfig()

function buildConfig(
   configFileOpts, 
   cliOpts?, 
id?): Promise<Options>

Defined in: config.ts:740

Builds the complete configuration object by merging options from multiple sources in order of precedence:

1. CLI options (highest priority)
2. Configuration file options
3. GraphQL Config options
4. Default options (lowest priority)

Parameters

configFileOpts

Maybe<ConfigOptions>

Options from the configuration file

cliOpts?

Maybe<CliOptions>

Options from the command line interface

id?

Maybe<string> = "default"

The configuration ID used when referencing multiple schemas

Returns

Promise<Options>

A promise resolving to the final merged configuration object

Example

// Basic usage with minimal options
const config = await buildConfig(
  { baseURL: "api" }, // Config file options
  { pretty: true }    // CLI options
);

// With specific config ID
const config = await buildConfig(
  { schema: "./schemas/users.graphql" },
  { force: true },
  "users"
);

// The resulting config will contain all required options
// with values from CLI taking precedence over config file,
// and defaults filling in any missing values

See

• Options for the complete configuration interface
• DEFAULT_OPTIONS for default values

---

getCustomDirectives()

function getCustomDirectives(customDirectiveOptions, skipDocDirective?): Maybe<CustomDirective>

Defined in: config.ts:383

Processes custom directives, filtering out any that should be skipped. Validates that each custom directive has the correct format with required functions.

Parameters

customDirectiveOptions

Maybe<CustomDirective>

The custom directive configuration object

skipDocDirective?

Maybe<DirectiveName[]>

Array of directive names that should be skipped

Returns

Maybe<CustomDirective>

The filtered custom directives object, or undefined if empty/invalid

Throws

Error if a custom directive has an invalid format

Example

// Valid custom directive with tag function
const customDirectives = {
  example: {
    tag: (value) => `Example: ${value}`
  },
  todo: {
    descriptor: () => "TODO items"
  }
};

// Filter out the "example" directive
const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
console.log(filteredDirectives); // { todo: { descriptor: [Function] } }

// Invalid format - will throw an error
getCustomDirectives({ example: { invalid: true } }, []);
// Error: Wrong format for plugin custom directive "example"...

See

DOCS_URL/advanced/custom-directive for custom directive format documentation

---

getDiffMethod()

function getDiffMethod(diff, force): TypeDiffMethod

Defined in: config.ts:435

Determines the diff method to use based on the configuration and force flag. If force is true, always returns FORCE regardless of the configured diff method.

Parameters

diff

TypeDiffMethod

The configured diff method

force

boolean = false

Whether to force regeneration (overrides diff setting)

Returns

TypeDiffMethod

The resolved diff method to use

Example

// Normal usage - respects the configured diff method
const method1 = getDiffMethod(DiffMethod.NONE, false);
console.log(method1); // "NONE"

// Force flag overrides the diff method
const method2 = getDiffMethod(DiffMethod.NONE, true);
console.log(method2); // "FORCE"

See

DiffMethod for available diff methods

---

getDocDirective()

function getDocDirective(name): DirectiveName

Defined in: config.ts:206

Retrieves a directive name from a string by parsing and validating the format. Directive names should be prefixed with '@' (e.g., '@example').

Parameters

name

Maybe<DirectiveName>

The directive name as a string, which should follow the format '@directiveName'

Returns

DirectiveName

The validated directive name without the '@' prefix

Throws

Error if the directive name format is invalid

Example

const directive = getDocDirective("@example");
console.log(directive); // "example"

// Invalid - will throw an error
getDocDirective("example"); // Error: Invalid "example"

---

getDocOptions()

function getDocOptions(cliOpts?, configOptions?): Required<ConfigDocOptions>

Defined in: config.ts:479

Builds the document options by merging CLI options, config file options, and defaults. Handles index generation flag and front matter configuration.

Parameters

cliOpts?

Maybe<CliOptions & Omit<DeprecatedCliOptions, "never">>

CLI options for document generation

configOptions?

Maybe<ConfigDocOptions & Omit<DeprecatedConfigDocOptions, "never">>

Config file options for document generation

Returns

Required<ConfigDocOptions>

The resolved document options with all required fields

Example

const cliOptions = { index: true };
const configOptions = { frontMatter: { sidebar_label: 'API' } };

const docOptions = getDocOptions(cliOptions, configOptions);
console.log(docOptions);
// {
//   index: true,
//   frontMatter: { sidebar_label: 'API' }
// }

---

getOnlyDocDirectives()

function getOnlyDocDirectives(cliOpts, configFileOpts): DirectiveName[]

Defined in: config.ts:239

Retrieves the list of "only" directives from CLI and config options. These directives specify which schema elements should be included in the documentation.

Parameters

cliOpts

Maybe<CliOptions>

CLI options containing "only" directives

configFileOpts

Maybe<Pick<ConfigOptions, "onlyDocDirective">>

Config file options containing "onlyDocDirective"

Returns

DirectiveName[]

An array of validated "only" directives (without '@' prefix)

Example

const cliOptions = { only: ["@example", "@internal"] };
const configOptions = { onlyDocDirective: ["@auth"] };

const onlyDirectives = getOnlyDocDirectives(cliOptions, configOptions);
console.log(onlyDirectives); // ["example", "internal", "auth"]

See

getDocDirective for directive name validation

---

getPrintTypeOptions()

function getPrintTypeOptions(cliOpts, configOptions): Required<ConfigPrintTypeOptions>

Defined in: config.ts:614

Builds the print type options by merging CLI options, config file options, and defaults. Handles various formatting options for type documentation.

Parameters

cliOpts

Maybe<CliOptions & Omit<DeprecatedCliOptions, "never">>

CLI options for print type configuration

configOptions

Maybe<ConfigPrintTypeOptions & Omit<DeprecatedConfigPrintTypeOptions, "never">>

Config file options for print type configuration

Returns

Required<ConfigPrintTypeOptions>

The resolved print type options with all required fields

Example

const cliOptions = { noCode: true, deprecated: "group" };
const configOptions = {
  exampleSection: true,
  hierarchy: "entity"
};

const printOptions = getPrintTypeOptions(cliOptions, configOptions);
console.log(printOptions);
// {
//   codeSection: false,  // Disabled via noCode CLI flag
//   deprecated: "group", // From CLI
//   exampleSection: true, // From config
//   parentTypePrefix: true, // Default value
//   relatedTypeSection: true, // Default value
//   typeBadges: true, // Default value
//   hierarchy: { entity: {} } // Parsed from config
// }

See

• DeprecatedOption for deprecated handling options
• getTypeHierarchyOption for hierarchy resolution

---

getSkipDocDirectives()

function getSkipDocDirectives(cliOpts, configFileOpts): DirectiveName[]

Defined in: config.ts:274

Retrieves the list of "skip" directives from CLI and config options. These directives specify which schema elements should be excluded from the documentation. Additionally, if deprecated handling is set to SKIP, adds the "deprecated" directive.

Parameters

cliOpts

Maybe<CliOptions>

CLI options containing "skip" directives

configFileOpts

Maybe<Pick<ConfigOptions, "printTypeOptions" | "skipDocDirective">>

Config file options containing "skipDocDirective" and potentially "printTypeOptions.deprecated"

Returns

DirectiveName[]

An array of validated "skip" directives (without '@' prefix)

Example

const cliOptions = { skip: ["@internal"], deprecated: "skip" };
const configOptions = { skipDocDirective: ["@auth"] };

const skipDirectives = getSkipDocDirectives(cliOptions, configOptions);
console.log(skipDirectives); // ["internal", "auth", "deprecated"]

See

• getDocDirective for directive name validation
• DeprecatedOption for deprecated handling options

---

getTypeHierarchyOption()

function getTypeHierarchyOption(cliOption?, configOption?): Maybe<Partial<Record<TypeHierarchyValueType, TypeHierarchyTypeOptions>>>

Defined in: config.ts:525

Resolves the type hierarchy configuration by merging CLI and config file options. Validates that CLI and config don't specify conflicting hierarchy types.

Parameters

cliOption?

Maybe<TypeHierarchyValueType>

The hierarchy option specified via CLI (string value)

configOption?

Maybe<TypeHierarchyType>

The hierarchy option from the config file (string or object)

Returns

Maybe<Partial<Record<TypeHierarchyValueType, TypeHierarchyTypeOptions>>>

The resolved type hierarchy object

Throws

Error if CLI and config specify conflicting hierarchy types

Example

// Using hierarchy from CLI (string format)
const hierarchy1 = getTypeHierarchyOption("api", undefined);
console.log(hierarchy1); // { api: {} }

// Using hierarchy from config (object format)
const hierarchy2 = getTypeHierarchyOption(undefined, { entity: { User: ["posts"] } });
console.log(hierarchy2); // { entity: { User: ["posts"] } }

// Error case - conflicting hierarchies
getTypeHierarchyOption("api", { entity: {} });
// Error: Hierarchy option mismatch in CLI flag 'api' and config 'entity'

See

TypeHierarchy for available hierarchy types

---

getVisibilityDirectives()

function getVisibilityDirectives(cliOpts, configFileOpts): object

Defined in: config.ts:328

Combines and validates visibility directives (only and skip) from both CLI and config sources. Ensures that no directive appears in both "only" and "skip" lists simultaneously.

Parameters

cliOpts

Maybe<CliOptions>

CLI options containing "only" and "skip" directives

configFileOpts

Maybe<Pick<ConfigOptions, "onlyDocDirective" | "printTypeOptions" | "skipDocDirective">>

Config file options containing directive configurations

Returns

object

An object with validated "onlyDocDirective" and "skipDocDirective" arrays

onlyDocDirective

onlyDocDirective: DirectiveName[];

skipDocDirective

skipDocDirective: DirectiveName[];

Throws

Error if the same directive appears in both "only" and "skip" lists

Example

const cliOptions = { only: ["@example"], skip: ["@internal"] };
const configOptions = { onlyDocDirective: ["@auth"] };

const visibilityDirectives = getVisibilityDirectives(cliOptions, configOptions);
console.log(visibilityDirectives);
// {
//   onlyDocDirective: ["example", "auth"],
//   skipDocDirective: ["internal"]
// }

// Invalid - will throw an error
getVisibilityDirectives(
  { only: ["@example"], skip: ["@example"] },
  {}
); // Error: The same directive cannot be declared in 'onlyDocDirective' and 'skipDocDirective'.

See

getOnlyDocDirectives and getSkipDocDirectives for directive retrieval

---

parseDeprecatedDocOptions()

function parseDeprecatedDocOptions(_cliOpts, _configOptions): Record<string, never>

Defined in: config.ts:452

Placeholder function for handling deprecated document options. Currently returns an empty object as these options are deprecated.

Parameters

_cliOpts

Maybe<Omit<DeprecatedCliOptions, "never">>

Deprecated CLI options (unused)

_configOptions

Maybe<Omit<DeprecatedConfigDocOptions, "never">>

Deprecated config options (unused)

Returns

Record<string, never>

An empty object

---

parseDeprecatedPrintTypeOptions()

function parseDeprecatedPrintTypeOptions(_cliOpts, _configOptions): Record<string, never>

Defined in: config.ts:577

Placeholder function for handling deprecated print type options. Currently returns an empty object as these options are deprecated.

Parameters

_cliOpts

Maybe<Omit<DeprecatedCliOptions, "never">>

Deprecated CLI options (unused)

_configOptions

Maybe<Omit<DeprecatedConfigPrintTypeOptions, "never">>

Deprecated config options (unused)

Returns

Record<string, never>

An empty object

---

parseGroupByOption()

function parseGroupByOption(groupOptions): Maybe<GroupByDirectiveOptions>

Defined in: config.ts:677

Parses and validates the groupByDirective option string format. The format should be @directive(field|=fallback) where:

• directive: Name of the directive to group by
• field: Name of the field in the directive to use for grouping
• fallback: (Optional) Fallback group name for items without the directive

Parameters

groupOptions

unknown

The group directive option as a string

Returns

Maybe<GroupByDirectiveOptions>

A parsed GroupByDirectiveOptions object or undefined if invalid

Throws

Error if the groupByDirective format is invalid

Example

// Basic usage with directive and field
const groupBy1 = parseGroupByOption("@tag(name)");
console.log(groupBy1);
// { directive: "tag", field: "name", fallback: "Miscellaneous" }

// With custom fallback group
const groupBy2 = parseGroupByOption("@category(name|=Other)");
console.log(groupBy2);
// { directive: "category", field: "name", fallback: "Other" }

// Invalid format - will throw an error
parseGroupByOption("invalid-format");
// Error: Invalid "invalid-format"