or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

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:

  1. Uses Documentation.js to parse JSDoc comments from the file
  2. Creates hierarchical DocumentationJs nodes for each documented element
  3. Processes description and deprecated fields as markdown
  4. Links related nodes (params, returns, examples, etc.)
  5. Handles complex type relationships and recursive definitions
  6. 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

JSDoc Tags

  • @param - Parameter documentation
  • @returns - Return value documentation
  • @example - Code examples (with optional <caption>)
  • @throws - Exception documentation
  • @deprecated - Deprecation notices
  • @since - Version information
  • @author - Author information
  • @copyright - Copyright information
  • @license - License information

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