1.8 KiB
dirmd
Generate markdown documentation from directory structure. Optimized for LLM ingestion.
Install
go install git.flo.fo/FLO/dirmd@latest
Linux only. Run dirmd -h for all flags.
Why
LLMs don't need 40k tokens of preamble. dirmd dumps a repo as markdown: tree + file contents, minus the noise. Everything filtered out stays visible in the tree (~ tests omitted, ~ ignored) so nothing vanishes silently — the model knows what exists and can ask for it.
Three ways to use it
One file — small repos. For small projects that fit in a context window comfortably:
dirmd -o out.md ~/repos/myproject
Everything lands in a single markdown file. Simplest, works fine until it doesn't.
Vertical slices — large repos. Once a single file gets too big to paste repeatedly, split it:
dirmd -o docs ~/repos/myproject --vertical-slices
This produces an index file (metadata + full tree + slice table) and one file per top-level directory. The full tree exists only in the index; every other file carries a one-line breadcrumb pointing back to it. Workflow: paste the index, then paste only the slice you need.
Slices + picks — you already know which files matter. Sometimes you need one specific file without its whole directory:
dirmd -o docs ~/repos/myproject --vertical-slices \
--pick common/src/config.rs --pick init/src/main.rs
Picks are individual files written alongside the slices, in the same directory layout (common/config.rs.md next to common/common_myproject.md). Use this when you're mid-conversation, already know the relevant files, and want a single consistent snapshot containing exactly those.
Rule of thumb: one file for tiny repos, slices when you need to browse, picks when you already know the answer.