project-to-markdown

A bidirectional tool to export Python projects to Markdown and recreate projects from Markdown files.

Features

Export (project-to-markdown)

• Recursively scans a project directory
• Includes code and markdown files (configurable)
• Outputs a single, well-structured Markdown file
• Supports file/directory exclusion and size limits
• Git-aware (respects .gitignore when requested)

Import (markdown-to-project)

• Recreates project structure from exported Markdown files
• Preserves directory hierarchy and file contents
• Handles UTF-8 encoding properly
• Safe overwrite protection

Installation

pip install project-to-markdown

Or, for local development:

pip install .

Usage

Export a Project to Markdown

project-to-markdown --root path/to/project --output export.md --include-exts .py,.md --exclude-dirs .venv,.git --title "My Project"

Export Options

• --root Root directory of the project (default: current directory)
• --output Output Markdown file (default: project_export.md)
• --title Title for the Markdown document
• --include-exts Comma-separated list of file extensions to include (default: .py,.md)
• --exclude-dirs Comma-separated list of directory names to exclude
• --exclude-filesComma-separated list of file names to exclude
• --use-gitignoreRespect .gitignore files in the export
• --all-files Include all files, not just tracked files
• --max-bytes Maximum size of files to include (default: 10,000,000)
• --max-lines Maximum number of lines to include per file (0 = unlimited)
• --tree-from-files Build tree from included files (mirrors gitignore/filters)

Recreate a Project from Markdown

python -m project_to_markdown.markdown_to_project -i exported_project.md -o recreated_project

Import Options

• -i, --input Input markdown file containing the project source (required)
• -o, --output Output directory to recreate the project in (default: 'recreated_project')
• --overwrite Allow writing into an existing, non-empty output directory

Examples

Export Example

project-to-markdown --root my_project --output my_project.md --title "My Project"

Import Example

markdown-to-project -i my_project.md -o recreated_project --overwrite

Project Structure

codebase_to_markdown/
├── project_to_markdown/
│   ├── __init__.py
│   ├── project_to_markdown.py    # Export script - project to markdown
│   └── markdown_to_project.py    # Import script - markdown to project
├── pyproject.toml
├── README.md
├── MANIFEST.in
├── example.md
└── __init__.py

License

MIT License

Created by Benaya Trabelsi. Contributions welcome! benaya7@gmail.com