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: config.ts:101

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:102

GROUP​

GROUP: "group";

Defined in: config.ts:103

SKIP​

SKIP: "skip";

Defined in: config.ts:104

DiffMethod​

Defined in: config.ts:83

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:85

NONE​

NONE: "NONE";

Defined in: config.ts:84

TypeHierarchy​

Defined in: config.ts:65

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:66

ENTITY​

ENTITY: "entity";

Defined in: config.ts:67

FLAT​

FLAT: "flat";

Defined in: config.ts:68

ASSET_HOMEPAGE_LOCATION​

const ASSET_HOMEPAGE_LOCATION: string;

Defined in: config.ts:122

Location of the default homepage template.

DEFAULT_HIERARCHY​

const DEFAULT_HIERARCHY: object;

Defined in: config.ts:133

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:142

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:111

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

PACKAGE_NAME​

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

Defined in: config.ts:117

Default package name used for temporary directory creation and identification.

buildConfig()​

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

Defined in: config.ts:771

Parameters​

configFileOpts​

Maybe<ConfigOptions>

cliOpts?​

Maybe<CliOptions>

id?​

Maybe<string> = "default"

Returns​

Promise<Options>

getCustomDirectives()​

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

Defined in: config.ts:390

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

getDiffMethod()​

function getDiffMethod(diff): TypeDiffMethod;

Defined in: config.ts:445

Parameters​

diff​

TypeDiffMethod

Returns​

TypeDiffMethod

getDocDirective()​

function getDocDirective(name): DirectiveName;

Defined in: config.ts:215

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:484

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' }
// }

getForcedDiffMethod()​

function getForcedDiffMethod(): TypeDiffMethod;

Defined in: config.ts:435

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

getNormalizedDiffMethod()​

function getNormalizedDiffMethod(diff): TypeDiffMethod;

Defined in: config.ts:439

Parameters​

diff​

TypeDiffMethod

Returns​

TypeDiffMethod

getOnlyDocDirectives()​

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

Defined in: config.ts:246

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:620

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​

getSkipDocDirectives()​

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

Defined in: config.ts:281

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: config.ts:531

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:335

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:457

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:583

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:683

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: config.ts:703

Parameters​

cliHomepage​

Maybe<string | false>

configHomepage​

Maybe<string | false>

Returns​

Maybe<string>