tessl/npm-doctoc

Command-line tool and library for generating table of contents for markdown files with multi-platform support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

File System Utilities

Name: tessl/npm-doctoc
Author: tessl

DocToc's file system utilities provide functionality for discovering and processing markdown files in directory structures with intelligent filtering and recursive search capabilities.

Capabilities

Find Markdown Files

Recursively discovers all markdown files in a directory structure.

/**
 * Recursively finds all markdown files in the specified directory
 * @param {string} dir - Absolute directory path to search
 * @returns {Array<FileInfo>} Array of file information objects
 */
function findMarkdownFiles(dir);

interface FileInfo {
  /** Absolute path to the markdown file */
  path: string;
  /** File name (including extension) */
  name: string;
}

Supported File Extensions

Markdown files are identified by their file extensions.

// Supported markdown extensions
const markdownExts = ['.md', '.markdown'];

Usage Examples:

const { findMarkdownFiles } = require('doctoc/lib/file');

// Find all markdown files in current directory
const files = findMarkdownFiles(process.cwd());

// Find files in specific directory
const docsFiles = findMarkdownFiles('/path/to/docs');

// Process found files
files.forEach(file => {
  console.log(`Found: ${file.name} at ${file.path}`);
});

Directory Filtering

Certain directories are automatically excluded from the search.

// Ignored directories during search
const ignoredDirs = ['.', '..', '.git', 'node_modules'];

Filtering Behavior:

Hidden directories: Directories starting with . (except .git which is explicitly listed)
Version control: .git directories are skipped
Dependencies: node_modules directories are ignored
Navigation: Current (.) and parent (..) directory references

Search Algorithm

Recursive directory traversal with intelligent filtering.

Search Process:

Read directory contents using fs.readdirSync()
Get file statistics for each entry
Separate files from directories
Filter markdown files by extension
Filter directories by ignore list
Recursively process allowed subdirectories
Combine results from all levels

File Discovery Examples:

const { findMarkdownFiles } = require('doctoc/lib/file');

// Typical project structure search
const files = findMarkdownFiles('/project');
/*
Discovers:
- /project/README.md
- /project/docs/api.md
- /project/docs/guide.md
- /project/src/components/README.md

Ignores:
- /project/.git/config
- /project/node_modules/package/README.md
- /project/.hidden/docs.md
*/

Integration with Main CLI

The file utilities integrate seamlessly with DocToc's main CLI functionality.

CLI Integration Example:

// From doctoc.js main executable
const file = require('./lib/file');

// Process directory
if (stat.isDirectory()) {
  console.log('DocToccing "%s" and its sub directories for %s.', target, mode);
  files = file.findMarkdownFiles(target);
} else {
  console.log('DocToccing single file "%s" for %s.', target, mode);
  files = [{ path: target }];
}

Console Output

The search process provides informative console output.

Search Progress Output:

// During search, outputs progress for each directory:
// Found README.md, guide.md in "/project/docs"
// Found nothing in "/project/src/empty-dir"
// Found API.md in "/project/api"

Output Format:

Files found: Lists discovered markdown files by directory
Empty directories: Reports directories with no markdown files
Search path: Shows which directory is being processed

Error Handling

Robust error handling for file system operations.

Common Error Scenarios:

Permission denied: Handles directories without read permissions
Broken symlinks: Skips invalid symbolic links
File system errors: Gracefully handles I/O errors

Error Behavior:

Continues processing other directories if one fails
Logs errors to console for debugging
Returns partial results when some paths fail

Performance Considerations

Optimized for efficient directory traversal.

Performance Features:

Synchronous I/O: Uses fs.statSync() and fs.readdirSync() for simplicity
Early filtering: Applies directory filters before recursion
Flat result structure: Returns simple array of file objects
Memory efficient: Processes directories one at a time

Usage Tips:

Best suited for moderate-sized directory structures
For very large repositories, consider filtering specific subdirectories
Results are not cached - call once and store results if processing multiple times

Complete Usage Example

Comprehensive File Discovery and Processing:

const { findMarkdownFiles } = require('doctoc/lib/file');
const { transform } = require('doctoc');
const fs = require('fs');
const path = require('path');

// Find all markdown files in project
const projectPath = path.resolve('./docs');
const files = findMarkdownFiles(projectPath);

console.log(`Found ${files.length} markdown files`);

// Process each file
files.forEach(fileInfo => {
  try {
    const content = fs.readFileSync(fileInfo.path, 'utf8');
    const result = transform(content, 'github.com', 4);
    
    if (result.transformed) {
      fs.writeFileSync(fileInfo.path, result.data, 'utf8');
      console.log(`✓ Updated TOC in ${fileInfo.name}`);
    } else {
      console.log(`- No changes needed in ${fileInfo.name}`);
    }
  } catch (error) {
    console.error(`✗ Error processing ${fileInfo.name}:`, error.message);
  }
});

Custom Directory Processing:

const { findMarkdownFiles } = require('doctoc/lib/file');

// Process multiple directories
const directories = ['./docs', './guides', './api'];

directories.forEach(dir => {
  if (fs.existsSync(dir)) {
    const files = findMarkdownFiles(path.resolve(dir));
    console.log(`\n${dir}: Found ${files.length} markdown files`);
    
    files.forEach(file => {
      console.log(`  - ${path.relative(dir, file.path)}`);
    });
  }
});

Install with Tessl CLI