# **Automatic Markdown Documentation and Directory Tree Generator**
This script generates 2 files (**directory_tree.md** and **all_files_content.md**) of structured Markdown documentation for any project directory:
- **directory_tree.md:** Directory structure with Git metadata (branch, commit, repo, etc.)
- **all_files_content.md:** Grouped file index and content previews (with truncation for large files, CSV/Excel previews, and special handling for binaries and logs)
- Skips configured folders/files (see configuration)
- Automatically adds the documentation folder to `.gitignore`
- Supports GitHub/GitLab links to each file at current commit (if Git is configured)
## Documentation Example
- [Markdown example of directory_tree.md file](https://github.com/sdkng44/document-folder-structure/blob/main/DOCUMENTATION_EXAMPLES/directory_tree.md)
- [Markdown example of all_files_content.md file](https://github.com/sdkng44/document-folder-structure/blob/main/DOCUMENTATION_EXAMPLES/all_files_content.md)
## Installation
### **A. Install from PyPI (recommended for most users)**
```sh
pip install document-folder-structure
```
### **B. Install from Source (GitHub)**
- **1. Clone the repo:**
```sh
git clone https://github.com/sdkng44/document-folder-structure.git
cd document-folder-structure
```
- **2. Install dependencies:**
```sh
pip install -r requirements.txt
```
## Usage
### **A. As CLI (after installing from PyPI):**
Once installed, run from any folder providing the full path to the project you want to document as an argument:
```sh
document-folder-structure C:\path\to\myproject
```
or in Linux:
```sh
document-folder-structure /path/to/your/project
```
### **B. From Source (if you cloned the repo):**
Always run from the root of the cloned repo (where the document_folder_structure/ folder is).
```sh
python -m document_folder_structure C:\path\to\myproject
```
or in Linux:
```sh
python -m document_folder_structure /path/to/your/project
```
The documentation files will be created inside the `INTERNAL_DOCS/` folder within the target project directory you specified.
**Optional arguments:**
`--config` Path to JSON configuration file (default: config.json)
`--max-depth` Maximum directory depth to display (default: 4)
`--tree-title` Custom title for the directory tree Markdown
`--truncate-lines` Max lines for README/large files (default: 10)
`--truncate-chars` Max characters for file previews (default: 2000)
`--max-log-lines` Max lines to preview for .log files (default: 10)
`--max-preview-columns` Max columns to preview in CSV/Excel tables (default: 20)
`--no-lines` Turn off line numeration on Markdown file content preview (default show line numeration)
**Example with arguments (on Windows):**
```sh
document-folder-structure C:\home\user\myproject --max-depth 3 --truncate-lines 8 --max-preview-columns 15 --no-lines
```
When using `--no-lines`, line numbers will not be shown in the file previews (except for CSV/Excel tables).
Section headers, line totals, and file separation are always included to keep the documentation clear.
## Output
All output files are placed in `INTERNAL_DOCS/` inside your project root:
- `directory_tree.md`: Directory tree with Git and file extension summary
- `all_files_content.md`: File index and preview for all non-binary, non-excluded files
If .gitignore does not exist, it is created. The folder `INTERNAL_DOCS/` is always added to .gitignore (if not present), to help avoid committing generated documentation.
## Configuration
You can customize exclusions, tree directory depth and truncate file content on Markdown documentation in a JSON config file.
First 4 lines are for files, extensions and directories exclusion before the tree generation, 5-12 lines are for truncate file content on Markdown documentation.
**Example `config.json`:**
```json
{
"excluded_dirs": ["node_modules", "__pycache__", ".git", "deps", ".fingerprint", "build", "incremental"],
"excluded_files": [".gitignore", ".849C9593-D756-4E56-8D6E-42412F2A707B"],
"excluded_extensions": [".log", ".tmp", ".bak", ".db-shm", ".db-wal", ".npmrc", ".prettierignore", ".prettierrc"],
"max_depth": 4,
"truncate_files": ["README", "LICENSE", "CHANGELOG", "CONTRIBUTING", "SECURITY"],
"truncate_exts": [".md", ".txt"],
"truncate_dirs": ["docs"],
"truncate_file_pairs": [["document_folder_structure", ".html"]],
"max_truncate_chars": 2000,
"truncate_lines": 10,
"max_log_lines": 10,
"max_preview_columns": 20
}
```
## Features
- Handles large files, binary files, and non-text files smartly (binary omitted, logs/README truncated)
- Markdown code highlighting by extension (.py, .js, .md, etc.)
- CSV files: Markdown table preview of first N rows and M columns (configurable)
- Excel (.xlsx): Markdown table preview of first N rows per sheet and up to M columns (requires openpyxl)
- Customizable file/folder exclusions by name, extension, or directory
- Adds the documentation folder to .gitignore automatically (with checks for missing/newline)
- Shows a summary of unique file extensions found in the tree
- Supports Linux, macOS, and Windows
## Limitations
- `.xls` (old Excel format) preview is not supported—use `.xlsx` instead.
- For correct GitHub/GitLab links, your repo must have a remote named `origin`.
## Example Output
After running, you'll find the following in INTERNAL_DOCS/:
- `directory_tree.md`
- `all_files_content.md`
Both files are readable Markdown, suitable for project documentation, onboarding, or quick file audits.
## Requirements
- Python 3.6+
- [openpyxl](https://pypi.org/project/openpyxl/) (for `.xlsx` preview)
- All dependencies listed in `requirements.txt`
## License
Apache License 2.0
---
Created by sdkng44@gmail.com
Raw data
{
"_id": null,
"home_page": null,
"name": "document-folder-structure",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "directory-tree, markdown, documentation-generation, documentation-tool, repository-management, tree-structure, project-management",
"author": null,
"author_email": "sdkng44 <sdkng44@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/49/64/74f30922497ecf62af2584172254c3989fc0ec76d9958ac58198ae2e7d70/document_folder_structure-0.2.3.tar.gz",
"platform": null,
"description": "# **Automatic Markdown Documentation and Directory Tree Generator**\n\nThis script generates 2 files (**directory_tree.md** and **all_files_content.md**) of structured Markdown documentation for any project directory:\n\n- **directory_tree.md:** Directory structure with Git metadata (branch, commit, repo, etc.)\n- **all_files_content.md:** Grouped file index and content previews (with truncation for large files, CSV/Excel previews, and special handling for binaries and logs)\n- Skips configured folders/files (see configuration)\n- Automatically adds the documentation folder to `.gitignore`\n- Supports GitHub/GitLab links to each file at current commit (if Git is configured)\n\n\n## Documentation Example\n\n- [Markdown example of directory_tree.md file](https://github.com/sdkng44/document-folder-structure/blob/main/DOCUMENTATION_EXAMPLES/directory_tree.md)\n \n\n- [Markdown example of all_files_content.md file](https://github.com/sdkng44/document-folder-structure/blob/main/DOCUMENTATION_EXAMPLES/all_files_content.md)\n \n\n\n\n## Installation\n\n### **A. Install from PyPI (recommended for most users)**\n\n```sh\npip install document-folder-structure\n```\n\n### **B. Install from Source (GitHub)**\n- **1. Clone the repo:**\n```sh\ngit clone https://github.com/sdkng44/document-folder-structure.git\ncd document-folder-structure\n```\n- **2. Install dependencies:**\n```sh\npip install -r requirements.txt\n```\n\n## Usage\n\n### **A. As CLI (after installing from PyPI):**\nOnce installed, run from any folder providing the full path to the project you want to document as an argument:\n```sh\ndocument-folder-structure C:\\path\\to\\myproject\n```\nor in Linux:\n```sh\ndocument-folder-structure /path/to/your/project\n```\n\n### **B. From Source (if you cloned the repo):**\nAlways run from the root of the cloned repo (where the document_folder_structure/ folder is).\n```sh\npython -m document_folder_structure C:\\path\\to\\myproject\n```\nor in Linux:\n```sh\npython -m document_folder_structure /path/to/your/project\n```\n\nThe documentation files will be created inside the `INTERNAL_DOCS/` folder within the target project directory you specified.\n\n\n**Optional arguments:**\n\n`--config`\tPath to JSON configuration file (default: config.json)\n\n`--max-depth`\tMaximum directory depth to display (default: 4)\n\n`--tree-title`\tCustom title for the directory tree Markdown\n\n`--truncate-lines`\tMax lines for README/large files (default: 10)\n\n`--truncate-chars`\tMax characters for file previews (default: 2000)\n\n`--max-log-lines`\tMax lines to preview for .log files (default: 10)\n\n`--max-preview-columns`\tMax columns to preview in CSV/Excel tables (default: 20)\n\n`--no-lines`\tTurn off line numeration on Markdown file content preview (default show line numeration)\n\n\n**Example with arguments (on Windows):**\n```sh\ndocument-folder-structure C:\\home\\user\\myproject --max-depth 3 --truncate-lines 8 --max-preview-columns 15 --no-lines\n```\n\nWhen using `--no-lines`, line numbers will not be shown in the file previews (except for CSV/Excel tables).\nSection headers, line totals, and file separation are always included to keep the documentation clear.\n\n\n## Output\n\nAll output files are placed in `INTERNAL_DOCS/` inside your project root:\n\n- `directory_tree.md`: Directory tree with Git and file extension summary\n- `all_files_content.md`: File index and preview for all non-binary, non-excluded files\n\nIf .gitignore does not exist, it is created. The folder `INTERNAL_DOCS/` is always added to .gitignore (if not present), to help avoid committing generated documentation.\n\n\n## Configuration\n\nYou can customize exclusions, tree directory depth and truncate file content on Markdown documentation in a JSON config file.\nFirst 4 lines are for files, extensions and directories exclusion before the tree generation, 5-12 lines are for truncate file content on Markdown documentation.\n\n**Example `config.json`:**\n\n```json\n{\n \"excluded_dirs\": [\"node_modules\", \"__pycache__\", \".git\", \"deps\", \".fingerprint\", \"build\", \"incremental\"],\n \"excluded_files\": [\".gitignore\", \".849C9593-D756-4E56-8D6E-42412F2A707B\"],\n \"excluded_extensions\": [\".log\", \".tmp\", \".bak\", \".db-shm\", \".db-wal\", \".npmrc\", \".prettierignore\", \".prettierrc\"],\n \"max_depth\": 4,\n \"truncate_files\": [\"README\", \"LICENSE\", \"CHANGELOG\", \"CONTRIBUTING\", \"SECURITY\"],\n \"truncate_exts\": [\".md\", \".txt\"],\n \"truncate_dirs\": [\"docs\"],\n \"truncate_file_pairs\": [[\"document_folder_structure\", \".html\"]],\n \"max_truncate_chars\": 2000,\n \"truncate_lines\": 10,\n \"max_log_lines\": 10,\n\t\"max_preview_columns\": 20\n}\n```\n\n\n## Features\n\n- Handles large files, binary files, and non-text files smartly (binary omitted, logs/README truncated)\n- Markdown code highlighting by extension (.py, .js, .md, etc.)\n- CSV files: Markdown table preview of first N rows and M columns (configurable)\n- Excel (.xlsx): Markdown table preview of first N rows per sheet and up to M columns (requires openpyxl)\n- Customizable file/folder exclusions by name, extension, or directory\n- Adds the documentation folder to .gitignore automatically (with checks for missing/newline)\n- Shows a summary of unique file extensions found in the tree\n- Supports Linux, macOS, and Windows\n\n\n\n## Limitations\n\n- `.xls` (old Excel format) preview is not supported\u2014use `.xlsx` instead.\n- For correct GitHub/GitLab links, your repo must have a remote named `origin`.\n\n\n## Example Output\n\nAfter running, you'll find the following in INTERNAL_DOCS/:\n\n- `directory_tree.md`\n- `all_files_content.md`\n\nBoth files are readable Markdown, suitable for project documentation, onboarding, or quick file audits.\n\n\n## Requirements\n\n- Python 3.6+\n- [openpyxl](https://pypi.org/project/openpyxl/) (for `.xlsx` preview)\n- All dependencies listed in `requirements.txt`\n\n\n## License\n\nApache License 2.0\n\n---\n\nCreated by sdkng44@gmail.com\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Automatic Markdown Documentation and Project Directory Tree Generator",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/sdkng44/document-folder-structure/issues",
"Homepage": "https://github.com/sdkng44/document-folder-structure",
"Repository": "https://github.com/sdkng44/document-folder-structure"
},
"split_keywords": [
"directory-tree",
" markdown",
" documentation-generation",
" documentation-tool",
" repository-management",
" tree-structure",
" project-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d0cc0c16cb41cfa7775386d9d5af6e617b4e93abcdb58d34ad77bcf6d4653860",
"md5": "df54dd831a8773577d297d4cb218d7c1",
"sha256": "b6bed34230de101cb1148b54b9deaeef42d00bf9ffc5c31e280f70c6a80a9d87"
},
"downloads": -1,
"filename": "document_folder_structure-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df54dd831a8773577d297d4cb218d7c1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 16485,
"upload_time": "2025-07-24T01:29:33",
"upload_time_iso_8601": "2025-07-24T01:29:33.169252Z",
"url": "https://files.pythonhosted.org/packages/d0/cc/0c16cb41cfa7775386d9d5af6e617b4e93abcdb58d34ad77bcf6d4653860/document_folder_structure-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "496474f30922497ecf62af2584172254c3989fc0ec76d9958ac58198ae2e7d70",
"md5": "07f7de8eb7005b534a3ad6d9b9d28592",
"sha256": "5107334edc97e5763287f56a493cacdfe3aa426a3462ac4bb358a86f76e30c27"
},
"downloads": -1,
"filename": "document_folder_structure-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "07f7de8eb7005b534a3ad6d9b9d28592",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 17266,
"upload_time": "2025-07-24T01:29:34",
"upload_time_iso_8601": "2025-07-24T01:29:34.560929Z",
"url": "https://files.pythonhosted.org/packages/49/64/74f30922497ecf62af2584172254c3989fc0ec76d9958ac58198ae2e7d70/document_folder_structure-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 01:29:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sdkng44",
"github_project": "document-folder-structure",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openpyxl",
"specs": [
[
">=",
"3.0.0"
]
]
}
],
"lcname": "document-folder-structure"
}
JSON
