# dirmd

Generate markdown documentation from directory structure. Optimized for LLM ingestion.

<video src="./docs/videos/dirmd.webm" autoplay loop muted playsinline></video>

## 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.