or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-gatsby-transformer-documentationjs

Gatsby transformer plugin which uses Documentation.js to extract JavaScript documentation

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/gatsby-transformer-documentationjs@6.25.x

To install, run

npx @tessl/cli install tessl/npm-gatsby-transformer-documentationjs@6.25.0

gatsby-transformer-documentationjs

gatsby-transformer-documentationjs is a Gatsby transformer plugin that integrates Documentation.js to extract and process JavaScript documentation from source code files. It automatically parses JSDoc comments from JavaScript, TypeScript, JSX, and TSX files, transforming them into GraphQL-queryable nodes within the Gatsby data layer.

Package Information

Package Name: gatsby-transformer-documentationjs
Package Type: npm (Gatsby plugin)
Language: JavaScript/TypeScript
Installation: npm install gatsby-transformer-documentationjs
Peer Dependencies: gatsby ^4.0.0-next
Node Engine: >=14.15.0

Core Imports

This plugin provides no direct imports - it exports Gatsby lifecycle hooks that are automatically called by Gatsby's plugin system.

// In gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-transformer-documentationjs`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `source`,
        path: `${__dirname}/src/`,
      },
    },
  ],
};

Basic Usage

// Example JavaScript file with JSDoc comments (src/utils.js)
/**
 * A utility function that adds two numbers
 * @param {number} a First number
 * @param {number} b Second number
 * @returns {number} Sum of a and b
 * @example
 * const result = add(5, 3);
 * console.log(result); // 8
 */
export function add(a, b) {
  return a + b;
}

Then query the documentation in GraphQL:

{
  allDocumentationJs {
    edges {
      node {
        name
        description {
          childMarkdownRemark {
            html
          }
        }
        params {
          name
          type {
            name
          }
          description {
            childMarkdownRemark {
              html
            }
          }
        }
        returns {
          type {
            name
          }
          description {
            childMarkdownRemark {
              html
            }
          }
        }
        examples {
          raw
          highlighted
          caption
        }
      }
    }
  }
}

Architecture

The plugin operates through Gatsby's plugin lifecycle system:

Schema Definition: Creates GraphQL types for documentation nodes
Node Processing: Processes JavaScript/TypeScript files to extract JSDoc
GraphQL Resolution: Provides custom resolvers for complex type relationships
Markdown Processing: Converts JSDoc descriptions to markdown nodes

Capabilities

Plugin Exports

The plugin exports the following Gatsby lifecycle hooks and utility functions:

/**
 * Exported lifecycle hooks and functions
 */
exports.createSchemaCustomization = createSchemaCustomization;
exports.createResolvers = createResolvers;
exports.onCreateNode = onCreateNode;
exports.unstable_shouldOnCreateNode = unstable_shouldOnCreateNode;

Schema Customization

Defines the GraphQL schema types for documentation nodes.

/**
 * Gatsby lifecycle hook that defines GraphQL schema types
 * @param {Object} params - Gatsby API parameters
 * @param {Object} params.actions - Gatsby actions
 * @param {Function} params.actions.createTypes - Function to create GraphQL types
 */
function createSchemaCustomization({ actions });

Creates the following GraphQL types:

DocumentationJs: Main documentation node
DocumentationJSComponentDescription: Markdown description content
DocumentationJsExample: Code examples with syntax highlighting
DocumentationJsMembers: Categorized members (static, instance, events, etc.)
DoctrineType: Type information from Doctrine parser
DocumentationJSLocation: Source location information

GraphQL Resolvers

Creates custom resolvers for complex field relationships.

/**
 * Gatsby lifecycle hook that adds custom GraphQL field resolvers
 * @param {Object} params - Gatsby API parameters
 * @param {Function} params.createResolvers - Function to register custom resolvers
 */
function createResolvers({ createResolvers });

Provides recursive type definition resolution for the DocumentationJs.type field.

Node Processing Filter

Determines if a file node should be processed for documentation extraction. This function is exported by the plugin.

/**
 * Filter function to determine if a node should be processed
 * @param {Object} params - Parameters
 * @param {Object} params.node - Gatsby file node
 * @returns {boolean} True if node should be processed
 */
function unstable_shouldOnCreateNode({ node });

Export: This function is exported as exports.unstable_shouldOnCreateNode for use by Gatsby's plugin system.

Processes files with these characteristics:

Internal type: File
Media type: application/javascript
Extensions: .js, .jsx, .ts, .tsx

Documentation Node Creation

Main transformation function that processes JavaScript files to extract documentation.

/**
 * Gatsby lifecycle hook that creates documentation nodes from source files
 * @param {Object} params - Gatsby API parameters
 * @param {Object} params.node - Source file node
 * @param {Object} params.actions - Gatsby actions
 * @param {Function} params.actions.createNode - Function to create new nodes
 * @param {Function} params.actions.createParentChildLink - Function to link parent/child nodes
 * @param {Function} params.createNodeId - Function to generate node IDs
 * @param {Function} params.createContentDigest - Function to generate content digests
 * @param {Object} params.reporter - Gatsby reporter for logging
 * @returns {Promise<boolean|null>} True if nodes were created, null if no documentation found
 */
async function onCreateNode({ node, actions, createNodeId, createContentDigest, reporter });

The function:

Uses Documentation.js to parse JSDoc comments from the file
Creates hierarchical DocumentationJs nodes for each documented element
Processes description and deprecated fields as markdown
Links related nodes (params, returns, examples, etc.)
Handles complex type relationships and recursive definitions
Applies syntax highlighting to code examples using Prism.js

GraphQL Schema Types

DocumentationJs Node

Main documentation node representing a documented code element.

interface DocumentationJs {
  /** Element name */
  name: string;
  /** Element kind (function, class, typedef, etc.) */
  kind: string;
  /** Parent element name */
  memberof?: string;
  /** Scope (instance, static, inner, global) */
  scope?: string;
  /** Access level (public, private, protected) */
  access?: string;
  /** Whether parameter is optional */
  optional: boolean;
  /** Whether element is readonly */
  readonly?: boolean;
  /** Whether element is abstract */
  abstract?: boolean;
  /** Whether function is a generator */
  generator?: boolean;
  /** Whether function is async */
  async?: boolean;
  /** Whether element overrides parent */
  override?: boolean;
  /** Whether to hide constructor */
  hideconstructor?: boolean;
  /** Element alias */
  alias?: string;
  /** Copyright information */
  copyright?: string;
  /** Author information */
  author?: string;
  /** License information */
  license?: string;
  /** Since version information */
  since?: string;
  /** Lends information */
  lends?: string;
  /** Type information */
  type?: DoctrineType;
  /** Default value */
  default?: any;
  /** Markdown description */
  description?: DocumentationJSComponentDescription;
  /** Deprecation notice */
  deprecated?: DocumentationJSComponentDescription;
  /** Extended/inherited elements */
  augments?: DocumentationJs[];
  /** Code examples */
  examples?: DocumentationJsExample[];
  /** Implemented interfaces */
  implements?: DocumentationJs[];
  /** Function parameters */
  params?: DocumentationJs[];
  /** Object properties */
  properties?: DocumentationJs[];
  /** Return values */
  returns?: DocumentationJs[];
  /** Thrown exceptions */
  throws?: DocumentationJs[];
  /** Todo items */
  todos?: DocumentationJs[];
  /** Yielded values */
  yields?: DocumentationJs[];
  /** Categorized members */
  members?: DocumentationJsMembers;
  /** Code location in source */
  codeLocation?: DocumentationJSLocationRange;
  /** Documentation location in source */
  docsLocation?: DocumentationJSLocationRange;
}

Code Examples

Structure for code examples with syntax highlighting.

interface DocumentationJsExample {
  /** Example caption */
  caption?: string;
  /** Example description */
  description?: string;
  /** Syntax-highlighted code */
  highlighted: string;
  /** Raw code content */
  raw: string;
}

Member Categories

Categorized members of documented elements.

interface DocumentationJsMembers {
  /** Static members */
  static?: DocumentationJs[];
  /** Instance members */
  instance?: DocumentationJs[];
  /** Event members */
  events?: DocumentationJs[];
  /** Global members */
  global?: DocumentationJs[];
  /** Inner members */
  inner?: DocumentationJs[];
}

Type Information

Type information parsed by Doctrine.

interface DoctrineType {
  /** Type category */
  type: string;
  /** Type name */
  name?: string;
  /** Array/union elements */
  elements?: any[];
  /** Expression for complex types */
  expression?: any;
  /** Type applications */
  applications?: any[];
  /** Function parameters */
  params?: any[];
  /** Object fields */
  fields?: any[];
  /** Function result type */
  result?: any;
  /** Referenced type definition */
  typeDef?: DocumentationJs;
}

Source Location

Source code location information.

interface DocumentationJSLocation {
  /** Line number */
  line: number;
  /** Column number */
  column: number;
}

interface DocumentationJSLocationRange {
  /** Start position */
  start: DocumentationJSLocation;
  /** End position */
  end: DocumentationJSLocation;
}

Supported Documentation Features

Type Definitions

@typedef - Custom type definitions
@callback - Callback type definitions
Interface and class documentation
Property and method documentation
Static and instance member categorization

Flow and TypeScript

Flow type annotations
TypeScript type definitions
Generic type parameters
Union and intersection types
Optional and nullable types

Dependencies

The plugin depends on the following packages (as declared in package.json):

documentation: ^13.1.0 (Documentation.js for parsing JSDoc)
prismjs: ^1.23.0 (Syntax highlighting for code examples)
@babel/runtime: ^7.15.4 (Babel runtime support)

Internal Dependencies (used but not declared in package.json, provided by Gatsby environment):

remark - For markdown processing of JSDoc descriptions
lodash - For utility functions like pick, reduce, isPlainObject

Error Handling

The plugin gracefully handles parsing errors:

Continues processing other files if one file fails
Reports warnings for circular type references
Ignores files without documentation
Provides detailed error context via Gatsby reporter

Version

Tile

Files

tessl/npm-gatsby-transformer-documentationjs

To install, run

index.mddocs/

gatsby-transformer-documentationjs

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Plugin Exports

Schema Customization

GraphQL Resolvers

Node Processing Filter

Documentation Node Creation

GraphQL Schema Types

DocumentationJs Node

Code Examples

Member Categories

Type Information

Source Location

Supported Documentation Features

JSDoc Tags

Type Definitions

Flow and TypeScript

Dependencies

Error Handling

Version

Tile

Files

tessl/npm-gatsby-transformer-documentationjs

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

gatsby-transformer-documentationjs

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Plugin Exports

Schema Customization

GraphQL Resolvers

Node Processing Filter

Documentation Node Creation

GraphQL Schema Types

DocumentationJs Node

Code Examples

Member Categories

Type Information

Source Location

Supported Documentation Features

JSDoc Tags

Type Definitions

Flow and TypeScript

Dependencies

Error Handling

index.mddocs/