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

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

GROUP​

GROUP: "group";

Defined in: core/src/config.ts:100

SKIP​

SKIP: "skip";

Defined in: core/src/config.ts:101

DiffMethod​

Defined in: core/src/config.ts:80

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

NONE​

NONE: "NONE";

Defined in: core/src/config.ts:81

TypeHierarchy​

Defined in: core/src/config.ts:62

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

ENTITY​

ENTITY: "entity";

Defined in: core/src/config.ts:64

FLAT​

FLAT: "flat";

Defined in: core/src/config.ts:65

ASSET_HOMEPAGE_LOCATION​

const ASSET_HOMEPAGE_LOCATION: string;

Defined in: core/src/config.ts:119

Location of the default homepage template.

DEFAULT_HIERARCHY​

const DEFAULT_HIERARCHY: object;

Defined in: core/src/config.ts:130

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"
        | "formatter"
        | "groupByDirective"
        | "loaders"
        | "mdxParser"
        | "printTypeOptions"
      >
    >
> &
  object;

Defined in: core/src/config.ts:139

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

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

PACKAGE_NAME​

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

Defined in: core/src/config.ts:114

Default package name used for temporary directory creation and identification.

buildConfig()​

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

Defined in: core/src/config.ts:761

Parameters​

configFileOpts​

Maybe<ConfigOptions>

cliOpts?​

Maybe<CliOptions>

id?​

Maybe<string> = "default"

Returns​

Promise<Options>

getCustomDirectives()​

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

Defined in: core/src/config.ts:386

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

Parameters​

diff​

TypeDiffMethod

Returns​

TypeDiffMethod

getDocDirective()​

function getDocDirective(name): DirectiveName;

Defined in: core/src/config.ts:211

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

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>

CLI options for document generation

configOptions?​

Maybe<ConfigDocOptions>

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

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

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

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

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

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

Parameters​

_cliOpts?​

Maybe<CliOptions>

_configOptions?​

Maybe<ConfigDocOptions>

Returns​

Record<string, never>

parseDeprecatedFormatterOption()​

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

Defined in: core/src/config.ts:565

Parameters​

cliOpts?​

Maybe<CliOptions>

configOptions?​

Maybe<ConfigOptions>

Returns​

Maybe<string>

parseDeprecatedPrintTypeOptions()​

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

Defined in: core/src/config.ts:585

Parameters​

_cliOpts?​

Maybe<CliOptions>

_configOptions?​

Maybe<ConfigPrintTypeOptions>

Returns​

Record<string, never>

parseGroupByOption()​

function parseGroupByOption(groupOptions): Maybe<GroupByDirectiveOptions>;

Defined in: core/src/config.ts:673

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

Parameters​

cliHomepage​

Maybe<string | false>

configHomepage​

Maybe<string | false>

Returns​

Maybe<string>