Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nodejs/doc-kit/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The metadata extraction system creates structured metadata from parsed API documentation, handling headings, stability indexes, YAML properties, and navigation entries.

​
createMetadata

Creates a metadata builder instance for extracting structured information from API documentation. 
import createMetadata from './metadata.mjs';
import GithubSlugger from 'github-slugger';

const slugger = new GithubSlugger();
const metadata = createMetadata(slugger);

​
Parameters

​
slugger
GithubSlugger
required
GitHub Slugger instance for generating URL-safe slugs from headings

​
Returns

​
metadata
MetadataBuilder
Metadata builder instance with methods:

​
setHeading

Sets the heading for the current metadata entry. The heading is cloned to prevent later mutations. 
metadata.setHeading({
  type: 'heading',
  data: {
    text: 'fs.readFile(path[, options], callback)',
    type: 'method',
  },
  children: [/* ... */],
});
Source: metadata.mjs:38

​
Parameters

​
heading
HeadingMetadataParent
required
Heading node containing:
  • type - Node type (usually ‘heading’)
  • data.text - Heading text
  • data.type - API type (method, class, property, etc.)
  • children - AST child nodes

​
addStability

Adds a stability index node to the metadata. 
metadata.addStability({
  type: 'stability',
  children: [{
    type: 'text',
    value: 'Stability: 2 - Stable',
  }],
});
Source: metadata.mjs:48

​
Parameters

​
stability
StabilityIndexParent
required
Stability index AST node

​
updateProperties

Updates metadata properties from YAML frontmatter or other sources. Can be called multiple times to complement data. 
metadata.updateProperties({
  type: 'module',
  added: ['v18.0.0'],
  deprecated: ['v20.0.0'],
  changes: [
    {
      version: 'v19.0.0',
      'pr-url': 'https://github.com/nodejs/node/pull/12345',
      description: 'Added new parameter',
    },
  ],
});
Source: metadata.mjs:64

​
Parameters

​
properties
Partial<ApiDocRawMetadataEntry>
required
Metadata properties to update:

​
Behavior

  • Array properties are concatenated (pushed) rather than replaced
  • Non-array properties are overwritten
  • Called multiple times to complement YAML blocks from the same entry

​
setYamlPosition

Sets the position of the YAML block in the source file for error reporting. 
metadata.setYamlPosition({
  start: { line: 10, column: 1, offset: 150 },
  end: { line: 15, column: 1, offset: 200 },
});
Source: metadata.mjs:78

​
Parameters

​
yaml_position
Position
required
Unist position object with start and end locations

​
create

Generates a complete metadata entry for an API doc section. This is the final step after setting heading, stability, and properties. 
const entry = metadata.create(
  { stem: 'fs', basename: 'fs.md' },
  sectionContentAST
);
Source: metadata.mjs:93

​
Parameters

​
apiDoc
FileInfo
required
File information object:
​
section
AST
required
AST tree containing the nodes of the API doc entry section

​
Returns

​
entry
ApiDocMetadataEntry
Complete metadata entry:

​
Usage Pattern

Typical workflow for extracting metadata from an API doc section: 
import createMetadata from './metadata.mjs';
import GithubSlugger from 'github-slugger';

const slugger = new GithubSlugger();
const metadata = createMetadata(slugger);

// 1. Set the heading
metadata.setHeading(headingNode);

// 2. Add stability if present
if (stabilityNode) {
  metadata.addStability(stabilityNode);
}

// 3. Update properties from YAML (can be called multiple times)
if (yamlNode) {
  metadata.setYamlPosition(yamlNode.position);
  metadata.updateProperties(yamlNode.data);
}

// 4. Create the final metadata entry
const entry = metadata.create(
  { stem: 'fs', basename: 'fs.md' },
  sectionContentAST
);

​
Example Output

{
  api: 'fs',
  slug: 'fs_fs_readfile_path_options_callback',
  source_link: 'https://github.com/nodejs/node/blob/v20.0.0/lib/fs.js#L100',
  api_doc_source: 'doc/api/fs.md',
  added_in: ['v0.0.2'],
  deprecated_in: [],
  removed_in: [],
  n_api_version: undefined,
  updates: [],
  changes: [
    {
      version: 'v18.0.0',
      'pr-url': 'https://github.com/nodejs/node/pull/12345',
      description: 'Added support for async iterators',
    },
  ],
  heading: {
    type: 'heading',
    data: {
      text: 'fs.readFile(path[, options], callback)',
      type: 'method',
      slug: 'fs_fs_readfile_path_options_callback',
    },
    children: [/* ... */],
  },
  stability: {
    type: 'root',
    children: [/* ... */],
  },
  content: {
    type: 'root',
    children: [/* section content AST */],
  },
  tags: ['async', 'filesystem'],
  introduced_in: 'v0.0.2',
  llm_description: 'Asynchronously reads the entire contents of a file',
  yaml_position: {
    start: { line: 10, column: 1, offset: 150 },
    end: { line: 15, column: 1, offset: 200 },
  },
}

​
Integration with Generators

The metadata API is used by the metadata generator to extract structured information from parsed API docs: 
import createMetadata from './metadata.mjs';

// Inside metadata generator
for (const apiDoc of parsedDocs) {
  const slugger = new GithubSlugger();
  const metadata = createMetadata(slugger);
  
  // Extract metadata from each section
  for (const section of apiDoc.sections) {
    // ... set heading, stability, properties
    const entry = metadata.create(apiDoc, section.content);
    entries.push(entry);
  }
}