Overview The metadata extraction system creates structured metadata from parsed API documentation, handling headings, stability indexes, YAML properties, and navigation entries.
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 GitHub Slugger instance for generating URL-safe slugs from headings
Returns Metadata builder instance with methods: setHeading
(heading: HeadingMetadataParent) => void
Set the heading for the current metadata entry
addStability
(stability: StabilityIndexParent) => void
Add a stability index node to the metadata
updateProperties
(properties: Partial<ApiDocRawMetadataEntry>) => void
Update metadata properties from YAML or other sources
setYamlPosition
(position: Position) => void
Set the position of the YAML block in the source file
create
(apiDoc: FileInfo, section: AST) => ApiDocMetadataEntry
Generate a metadata entry for an API doc section
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:38Parameters heading
HeadingMetadataParent
required
Heading node containing:
type - Node type (usually ‘heading’)data.text - Heading textdata.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:48Parameters 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:64Parameters properties
Partial<ApiDocRawMetadataEntry>
required
Metadata properties to update: API type override (method, class, module, etc.)
Versions when the API was added
Versions when the API was deprecated
Versions when the API was removed
Array of change log entries
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:78Parameters 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:93Parameters File information object: File name without extension (e.g., ‘fs’)
Full file name (e.g., ‘fs.md’)
AST tree containing the nodes of the API doc entry section
Returns Complete metadata entry: API module name (from file stem)
URL-safe slug for the section
Path to source documentation file
Heading AST with slug and type
Stability index information
Position of YAML in source
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 ); } }