Skip to main content

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: packages/core/src/config.ts:102

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: packages/core/src/config.ts:103

GROUP​

GROUP: "group";

Defined in: packages/core/src/config.ts:104

SKIP​

SKIP: "skip";

Defined in: packages/core/src/config.ts:105

DiffMethod​

Defined in: packages/core/src/config.ts:84

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: packages/core/src/config.ts:86

NONE​

NONE: "NONE";

Defined in: packages/core/src/config.ts:85

TypeHierarchy​

Defined in: packages/core/src/config.ts:66

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: packages/core/src/config.ts:67

ENTITY​

ENTITY: "entity";

Defined in: packages/core/src/config.ts:68

FLAT​

FLAT: "flat";

Defined in: packages/core/src/config.ts:69

ASSET_HOMEPAGE_LOCATION​

const ASSET_HOMEPAGE_LOCATION: string;

Defined in: packages/core/src/config.ts:123

Location of the default homepage template.

DEFAULT_HIERARCHY​

const DEFAULT_HIERARCHY: object;

Defined in: packages/core/src/config.ts:134

Default hierarchy configuration using the API hierarchy type.

Type Declaration​

api​

api: object = {};

DEFAULT_OPTIONS​

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

Defined in: packages/core/src/config.ts:146

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, "exampleSection" | "hierarchy">
> & object;
Type Declaration​
exampleSection​
exampleSection: ConfigPrintTypeOptions["exampleSection"];
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: packages/core/src/config.ts:112

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

PACKAGE_NAME​

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

Defined in: packages/core/src/config.ts:118

Default package name used for temporary directory creation and identification.

buildConfig()​

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

Defined in: packages/core/src/config.ts:987

Parameters​

configFileOpts​

Maybe<ConfigOptions>

cliOpts?​

Maybe<CliOptions>

id?​

Maybe<string> = "default"

Returns​

Promise<Options>

getCustomDirectives()​

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

Defined in: packages/core/src/config.ts:412

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 descriptor function
const customDirectives = {
  example: {
    tag: (value) => `Example: ${value}`,
  },
  note: {
    descriptor: () => "Note items",
  },
};

// Filter out the "example" directive, keeping "note"
const filteredDirectives = getCustomDirectives(customDirectives, ["example"]);
console.log(filteredDirectives); // { note: { 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

getDecoratorsOption()​

function getDecoratorsOption(decorators): Maybe<Decorators>;

Defined in: packages/core/src/config.ts:815

Validates the top-level decorators option.

The option is keyed by a free-form id — it is not required to name a schema directive — and every entry must declare a render callback. An invalid entry is a configuration error rather than something to silently drop, as it would otherwise produce a page missing a section without any indication why.

Parameters​

decorators​

Maybe<Decorators>

the decorators option declared in the config file.

Returns​

Maybe<Decorators>

the validated decorators, or undefined when none is declared.

Throws​

Error if an entry is malformed or claims a built-in section name.

Example​

getDecoratorsOption({
  responses: {
    predicate: hasDirectiveNamed("httpResponse"),
    title: "Responses",
    position: { after: "metadata" },
    render: (values) =>
      values.map((v) => `- \`${v.code}\` ${v.description}`).join("\n"),
  },
});

getDiffMethod()​

function getDiffMethod(diff): TypeDiffMethod;

Defined in: packages/core/src/config.ts:472

Parameters​

diff​

TypeDiffMethod

Returns​

TypeDiffMethod

getDocDirective()​

function getDocDirective(name): DirectiveName;

Defined in: packages/core/src/config.ts:236

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: packages/core/src/config.ts:526

Parameters​

cliOpts?​

Maybe<CliOptions>

configOptions?​

Maybe<ConfigDocOptions>

Returns​

Required<ConfigDocOptions>

getForcedDiffMethod()​

function getForcedDiffMethod(): TypeDiffMethod;

Defined in: packages/core/src/config.ts:463

Returns FORCE as the diff method. This function is used when documentation should be forcefully regenerated.

Returns​

TypeDiffMethod

The FORCE diff method

Example​

const method = getForcedDiffMethod();
console.log(method); // "FORCE"

See​

DiffMethod for available diff methods

getOnlyDocDirectives()​

function getOnlyDocDirectives(cliOpts, configFileOpts): DirectiveName[];

Defined in: packages/core/src/config.ts:267

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

getSkipDocDirectives()​

function getSkipDocDirectives(cliOpts, configFileOpts): DirectiveName[];

Defined in: packages/core/src/config.ts:302

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​

getTypeHierarchyOption()​

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

Defined in: packages/core/src/config.ts:581

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: packages/core/src/config.ts:356

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: packages/core/src/config.ts:477

Parameters​

_cliOpts?​

Maybe<CliOptions>

_configOptions?​

Maybe<ConfigDocOptions>

Returns​

Record<string, never>

parseDeprecatedFormatterOption()​

function parseDeprecatedFormatterOption(
  cliOpts?,
  configOptions?,
): Maybe<string>;

Defined in: packages/core/src/config.ts:626

Parameters​

cliOpts?​

Maybe<CliOptions>

configOptions?​

Maybe<ConfigOptions>

Returns​

Maybe<string>

parseDeprecatedPrintTypeOptions()​

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

Defined in: packages/core/src/config.ts:647

Parameters​

_cliOpts?​

Maybe<CliOptions>

_configOptions?​

Maybe<ConfigPrintTypeOptions>

Returns​

Record<string, never>

parseGroupByOption()​

function parseGroupByOption(groupOptions): Maybe<GroupByDirectiveOptions>;

Defined in: packages/core/src/config.ts:898

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"

parseHomepageOption()​

function parseHomepageOption(cliHomepage, configHomepage): Maybe<string>;

Defined in: packages/core/src/config.ts:919

Parameters​

cliHomepage​

Maybe<string | false>

configHomepage​

Maybe<string | false>

Returns​

Maybe<string>