Neil Mahajan
Personal Project
August 2025

🌳 Project Tree Markdown CLI

A simple CLI tool written in Go that generates Markdown-formatted tree structures of any directory. Perfect for creating README documentation that shows your project structure.

Go
CLI
Markdown
Tree Structure
Box Drawing Characters
File System
Makefile
Documentation
GitHub
Terminal Output
$ ./project-tree-md
```
project-tree-md
├── cmd/
│   └── main.go
├── internal/
│   ├── cli/
│   │   └── cli.go
│   └── tree/
│       └── printer.go
├── .gitignore
├── go.mod
├── LICENSE
├── Makefile
└── README.md
```

Project Overview

Project Tree Markdown is a lightweight CLI tool built with Go that generates clean, properly formatted tree structures of directory hierarchies in Markdown format. It's designed specifically for developers who want to document their project structure in README files and documentation.

The tool uses box-drawing characters to create visually appealing tree representations and includes smart filtering to automatically skip common unwanted files and directories like .git, node_modules, and various build artifacts. This makes the output clean and focused on the important project structure.

Built with simplicity and efficiency in mind, the tool provides a straightforward command-line interface with minimal dependencies, making it easy to integrate into any development workflow or build process.

Key Features

Clean Output & Formatting

  • Generates properly formatted tree structures using box-drawing characters
  • Output wrapped in markdown code blocks, ready for README files
  • Copy-paste ready format for documentation
  • Consistent and professional visual representation

Smart Filtering & Efficiency

  • Automatically skips common unwanted files and directories
  • Filters out .git, node_modules, build artifacts
  • Excludes system files like .DS_Store and Thumbs.db
  • Preserves important hidden files like .gitignore

Usage Examples

Basic Commands

# Generate tree for current directory
$ ./project-tree-md

# Generate tree for specific directory
$ ./project-tree-md -path /path/to/your/project

# Show help
$ ./project-tree-md -help

Make Commands

# Build the project
$ make build

# Build and run on current directory
$ make run

# Run development tasks (format, vet, test, build)
$ make dev

# Build for multiple platforms
$ make build-all

Installation Options

# Build from source using Make
$ git clone https://github.com/neilsmahajan/project-tree-md.git
$ cd project-tree-md
$ make build

# Install system-wide
$ make install # Installs to /usr/local/bin

Technical Implementation

Architecture

The application is built using Go's standard library with a clean, modular architecture. It includes a CLI package for command-line argument handling and a tree package for the core tree generation and printing functionality.

Project Structure

project-tree-md/
├── cmd/
│   └── main.go
├── internal/
│   ├── cli/
│   │   └── cli.go
│   └── tree/
│       └── printer.go
├── .gitignore
├── go.mod
├── LICENSE
├── Makefile
└── README.md

Key Technical Features

  • Efficient directory traversal using Go's filepath package
  • Smart filtering system to exclude unwanted files and directories
  • Box-drawing character formatting for clean tree output
  • Command-line flag parsing for path specification
  • Cross-platform compatibility (macOS, Linux, Windows)
  • Makefile for easy building and development workflow
  • Minimal dependencies using only Go standard library

Filtering System

The tool includes a comprehensive filtering system that automatically excludes common files and directories that don't add value to project documentation:

Version Control

  • .git
  • .github

IDE/Editor

  • .vscode
  • .idea

Dependencies

  • node_modules
  • vendor

Build Artifacts

  • target
  • build
  • dist
  • __pycache__

System Files

  • .DS_Store
  • Thumbs.db

Environment

  • .env
  • .env.local

Important hidden files like .gitignore, .dockerignore, and similar configuration files are preserved in the output.

Use Cases & Benefits

Documentation

  • Perfect for README files and project documentation
  • Shows project structure at a glance
  • Helps new contributors understand codebase layout
  • Professional presentation for portfolios

Development Workflow

  • Quick project structure overview
  • Easy integration into build processes
  • Lightweight tool with minimal dependencies
  • Cross-platform compatibility

Example Output

Here's what the tool generates when run on its own source code:

Generated Tree
```
project-tree-md
├── cmd/
│   └── main.go
├── internal/
│   ├── cli/
│   │   └── cli.go
│   └── tree/
│       └── printer.go
├── .gitignore
├── go.mod
├── LICENSE
├── Makefile
└── README.md
```