FLO/dirmd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

finished vertical-.slices

Browse Source
This commit is contained in:
Bartal Laearsson
2026-08-07 23:10:42 +01:00
parent 8c39068453
commit 6fbb9bf983
4 changed files with 504 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+60 -26
View File
@@ -1,13 +1,14 @@
# dirmd
Generate markdown documentation from directory structure.
Generate markdown documentation from directory structure. Optimized for LLM ingestion.
## Features
- Recursive directory traversal
- Tree visualization (standard tree command format)
- Full file contents with syntax-highlighted code blocks
- ASCII tree visualization (LLM-friendly, minimal token overhead)
- Full file contents with explicit delimiters and metadata
- Filters dotfiles, binaries, and blacklisted extensions
- Vertical slices mode: root file + one markdown per top-level directory
- Append mode for single files or directories
- Force overwrite of existing output files
- Configurable depth, file size limits, ignore patterns
@@ -31,12 +32,42 @@ Generate markdown documentation from directory structure.
# Append another directory
dirmd -a ~/repos/anotherproject -o existing.md
# Generate with vertical slices
dirmd -o output.md ~/repos/myproject --vertical-slices
# Generate and upload to Proton Drive (default: /my-files/md/<filename>)
dirmd -o output.md ~/repos/myproject --proton-drive
# Generate and upload to a specific remote path
dirmd -o output.md ~/repos/myproject --proton-drive --drive-path /my-files/docs/api.md
## Vertical Slices Mode
When `--vertical-slices` is passed, dirmd splits output into multiple files instead of one monolithic document:
- **Root file** (`-o output.md`): Full directory tree with cross-references to slice files, a vertical slices index table (file counts, total bytes per directory), and full contents of all root-level files.
- **Slice files** (`cmd.md`, `internal.md`, etc.): One per top-level directory, placed alongside the root file. Each contains its own tree, a back-reference to the root document, and full recursive file contents for that directory.
This mode cannot be combined with `--append` or `--input-file`.
Example output with `dirmd -o docs.md ~/repos/myproject --vertical-slices`:
docs/
├── docs.md ← root: tree + slices index + root file contents
├── cmd.md ← slice: tree + contents of cmd/
└── internal.md ← slice: tree + contents of internal/
## LLM-Optimized Output
Output is designed for RAG ingestion and LLM context windows, not human presentation:
- **ASCII tree format** (`+-` instead of Unicode box-drawing) to reduce token overhead
- **Explicit file delimiters**: `--- FILE: ./path (bytes, lines) ---` and `--- END FILE ---`
- **Document type markers**: `[ROOT]` and `[SLICE]` in H1 headers
- **Cross-references**: Directory entries in root tree show `-> see cmd.md`; slice files reference their root document
- **Slices index table**: File counts and total bytes per slice for informed retrieval decisions
- **Tilde fences** (`~~~`) to avoid conflicts with backticks in source files
## Flags
| Flag | Description | Default |
@@ -45,6 +76,7 @@ Generate markdown documentation from directory structure.
| `-a`, `--append` | Append to existing output file | false |
| `-f`, `--force` | Overwrite existing output file (non-append mode) | false |
| `-i`, `--input-file` | Single file input (append mode only) | |
| `--vertical-slices` | Split output into root file + one markdown per top-level directory | false |
| `--max-size` | Max file size in bytes | 524288 |
| `--max-depth` | Max directory recursion depth | 20 |
| `--ignore` | Additional ignore patterns (glob) | |
@@ -54,7 +86,9 @@ Generate markdown documentation from directory structure.
## Proton Drive Integration
dirmd can optionally upload the generated markdown file to Proton Drive using the [Proton Drive CLI](https://proton.me/support/drive-cli). The upload is performed only when `--proton-drive` is passed. Without it, dirmd behaves exactly as before — no Proton Drive dependency is required.
dirmd can optionally upload the generated markdown file(s) to Proton Drive using the [Proton Drive CLI](https://proton.me/support/drive-cli). The upload is performed only when `--proton-drive` is passed. Without it, dirmd behaves exactly as before — no Proton Drive dependency is required.
In vertical slices mode, all generated files (root + slices) are uploaded to `/my-files/md/`. The `--drive-path` flag is ignored in slices mode; each file is uploaded by its basename.
### Prerequisites
@@ -62,14 +96,7 @@ dirmd can optionally upload the generated markdown file to Proton Drive using th
2. Authenticate by running `proton-drive auth login`.
3. Ensure `proton-drive` is in your `PATH`.
If the CLI is not installed or you are not logged in, dirmd will report the error to stderr and exit with a non-zero code. The local markdown file is still written successfully before the upload is attempted.
### Upload Behavior
- Default remote path: `/my-files/md/<filename>` where `<filename>` is the basename of the local output file.
- Override with `--drive-path /my-files/custom/report.md` (full path including filename).
- Existing remote files are overwritten (`--conflict-strategy replace`).
- The local markdown file is always written before the upload is attempted.
If the CLI is not installed or you are not logged in, dirmd will report the error to stderr and exit with a non-zero code. Local files are always written successfully before the upload is attempted.
For full documentation on the Proton Drive CLI, including installation, authentication, and troubleshooting, refer to the [official Proton Drive CLI support page](https://proton.me/support/drive-cli).
@@ -84,6 +111,9 @@ For full documentation on the Proton Drive CLI, including installation, authenti
# Skip additional file extensions
dirmd -o output.md ~/repos/project --extensions .log --extensions .tmp
# Vertical slices with overwrite
dirmd -o docs.md ~/repos/project -f --vertical-slices
# Generate, then upload to default remote location
dirmd -o docs.md ~/repos/project --proton-drive
@@ -97,31 +127,35 @@ For full documentation on the Proton Drive CLI, including installation, authenti
Produces markdown with:
1. Absolute path as H1 header
2. Directory tree (indented with 4 spaces per level)
3. All text files with content in code blocks
4. Language detection from file extensions
1. Absolute path as H1 header with `[ROOT]` or `[SLICE]` marker
2. ASCII directory tree (indented with `+-` and `|` characters)
3. Vertical slices index table (sliced mode only)
4. All text files with content in fenced code blocks
5. Explicit `--- FILE: ---` and `--- END FILE ---` delimiters with byte and line counts
6. Language detection from file extensions
Example output structure:
Example output structure (non-sliced mode):
# /home/user/repos/myproject
# /home/user/repos/myproject [ROOT]
## Directory Tree
~~~
myproject/
├── cmd/
│ └── main.go
└── internal/
└── config.go
+- cmd/
| +- main.go
+- internal/
| +- config.go
~~~
## Contents
### ./cmd/main.go
```go
--- FILE: ./cmd/main.go (45 bytes, 3 lines) ---
~~~go
package main
func main() {}
```
~~~
--- END FILE ---
Note: Uses tilde fences (~~~) internally to avoid conflicts with nested backticks in source files.