or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdfile-utilities.mdindex.mdprogrammatic-api.md
tile.json

file-utilities.mddocs/

File System Utilities

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:

  1. Read directory contents using fs.readdirSync()
  2. Get file statistics for each entry
  3. Separate files from directories
  4. Filter markdown files by extension
  5. Filter directories by ignore list
  6. Recursively process allowed subdirectories
  7. 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)}`);
    });
  }
});