Automated Folder Structure Generator

Inspired by my last blog post on creating a Python script for organizing files, I decided to create a script that would generate an organized representation of project structure in markdown format. This new tool would not only help me visualize my folders and files but also serve as a handy resource for creating GitHub README files. With a simple run, I could generate a neat overview of my projects—making documentation easy.

The Idea Takes Shape

I thought of a beautifully formatted markdown output that listed my folders and files, complete with icons to make it visually appealing. I chose the classic folder emoji (🗂️) for directories and a document emoji (📄) for files.

Here’s a the main function of the code:

def generate_markdown_structure(root_dir, skip_folders, indent=''):
    markdown_structure = ''
    items = sorted(os.listdir(root_dir))

    for index, item in enumerate(items):
        if item in skip_folders:
            continue

        path = os.path.join(root_dir, item)
        if os.path.isdir(path):
            icon = '🗂️'
            connector = '└── ' if index == len(items) - 1 else '├── '
            markdown_structure += f"{indent}{connector}{icon} {item}\n"
            sub_indent = indent + ('    ' if connector == '└── ' else '│   ')
            markdown_structure += generate_markdown_structure(path, skip_folders, sub_indent)
        else:
            icon = '📄'
            connector = '└── ' if index == len(items) - 1 else '├── '
            markdown_structure += f"{indent}{connector}{icon} {item}\n"

    return markdown_structure

This piece of code recursively explores the directory and generates a structured output while skipping unwanted folders.

Sample Output

├── 📄 .gitignore
├── 📄 CHANGELOG.md
├── 📄 README.md
├── 📄 eslint.config.js
├── 📄 index.html
├── 📄 package-lock.json
├── 📄 package.json
├── 📄 postcss.config.js
├── 🗂️ public
│   └── 📄 vite.svg
├── 🗂️ src
│   ├── 📄 App.css
│   ├── 📄 App.tsx
│   ├── 🗂️ assets
│   │   └── 📄 react.svg
│   ├── 🗂️ component
│   │   ├── 🗂️ add-expense
│   │   │   ├── 📄 AddExpense.module.css
│   │   │   └── 📄 AddExpense.tsx
│   │   ├── 🗂️ expense-grid
│   │   │   ├── 📄 ExpenseGrid.module.css
│   │   │   └── 📄 ExpenseGrid.tsx
│   │   ├── 🗂️ home
│   │   │   └── 📄 Home.tsx
│   │   ├── 🗂️ navbar
│   │   │   ├── 📄 Navbar.module.css
│   │   │   └── 📄 Navbar.tsx
│   │   └── 🗂️ sidebar
│   │       ├── 📄 Sidebar.module.css
│   │       └── 📄 Sidebar.tsx
│   ├── 📄 index.css
│   ├── 📄 main.tsx
│   ├── 📄 types.ts
│   └── 📄 vite-env.d.ts
├── 📄 tailwind.config.js
├── 📄 tsconfig.app.json
├── 📄 tsconfig.json
├── 📄 tsconfig.node.json
└── 📄 vite.config.ts

Next Steps

Now that we have a powerful script to organize the folder structure in markdown format, it’s time to think about how to make the most of it. One exciting possibility is to integrate this script into your release process or CI/CD pipeline. By doing so, you can ensure that your README file is always up to date with the latest project structure without any manual effort.

Automating with CI/CD

Here’s how you can set up your CI/CD pipeline to automatically generate or update your README file:

1. Add the Script to Your Repository: Make sure the script is part of your repository. Place it in a logical location, such as a /scripts folder.

2. Create a Workflow: If you’re using GitHub Actions, you can create a workflow that triggers on specific events, like when you push new commits or create a release. Your workflow file (e.g., .github/workflows/update-readme.yml) might look something like this:

name: Update README

on:
  push:
    branches:
      - main
  release:
    types: [created]

jobs:
  update-readme:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.8'  # Python version

      - name: Install dependencies
        run: |
          pip install -r requirements.txt  # If any dependencies

      - name: Run folder structure script
        run: python scripts/your_script.py  # Update with script path

      - name: Commit and push changes
        run: |
          git config --local user.email "[email protected]"
          git config --local user.name "GitHub Action"
          git add project_structure.md
          git commit -m "Update project structure in README" || echo "No changes to commit"
          git push

• Update Your README: In your script, you can modify it to not only generate a project_structure.md file but also append or integrate its contents directly into your main README.md. This way, you’ll always have an up-to-date overview of your project structure right on your project’s main page.

• Test the Workflow: Push your changes to the repository and check the Actions tab on GitHub to see if the workflow runs successfully.

You can access the full code on my GitHub.