📝 Project2MD

Overview

The Project2MD function converts a project directory into a single Markdown (.md) file. It recursively walks through the directory tree, reads file contents, and appends them to a Markdown file with optional formatting. It also generates a summary table of all processed files.

This is useful for creating project documentation, code snapshots, or sharing projects as a single Markdown file.

---

Installation

          
            1npm install hbh-nodes
          
        

Or using yarn:

          
            1yarn add hbh-nodes
          
        

---

Usage

          
            1import { P2PMD } from 'hbh-nodes';3const { Project2MD, SimpleExclude } = P2PMD;5await Project2MD({6  input: './my-project',7  output: './docs/project.md',8  concurrency: 10,9  onprogress: ({ index, relPath }) => {10    console.log(`Processed file #${index}: ${relPath}`);11  },12  onEnd: ({ total }) => {13    console.log(`Finished! Total files processed: ${total}`);14  },15});
          
        

---

Function Signature

          
            1async function Project2MD(opts?: Project2MDOptions): Promise<void>
          
        

Parameters

opts – An optional object of type Project2MDOptions.

Options

---

Predefined Exclude

SimpleExclude is provided to skip common Node.js project files and directories:

          
            1SimpleExclude.Node = ['node_modules', 'package-lock.json', '.gitignore', 'package.json'];
          
        

---

How It Works

1. Resolve Paths Converts input and output to absolute paths and ensures the output file itself is excluded.

2. Directory Walk Recursively walks directories sequentially to avoid concurrency deadlocks.

   • Directories are traversed first.
   • Files are processed concurrently, respecting the concurrency limit.

3. File Processing For each file:

   • Skips if hidden, excluded, or exceeds maxFileSize.
   • Reads file contents (utf-8).
   • Generates a Markdown header using filenameFormatter.
   • Wraps the content in a fenced code block with language derived from the file extension.
   • Appends content to the output Markdown file.
   • Calls onprogress callback.

4. Summary Generation After all files are processed:

   • Calls summaryFormatter with the list of processed files.
   • Appends the generated summary to the Markdown file.

5. Error Handling

   • Wraps file system operations in safeRun to catch errors without stopping execution unless stopOnError is true.
   • Logs warnings and errors for files that fail to process.

---

Example Output

Assuming a directory structure:

src/
 ├─ index.js
 ├─ utils.js
README.md

Generated output.md could look like:

          
            1###### `src/index.js`3```js4console.log('Hello World');
          
        

src/utils.js

          
            1export function add(a, b) { return a + b; }
          
        

README.md

          
            1# My Project2This is my project.
          
        

---

Notes

• Files larger than maxFileSize are skipped.
• Hidden files/directories are ignored if ignoreHidden is true.
• Concurrency ensures faster processing but directory traversal is always sequential.
• Markdown language blocks are derived from file extensions; fallback to no language if unknown.
• onprogress and onEnd allow progress tracking or UI updates.

---

This function is designed for Node.js environments and uses ESM imports (fs/promises, path).

---