How to Represent Folder Trees in Docs and Code

If you’ve ever tried to explain a project layout in a README, design doc, or code comment, you’ve probably needed some way to show a folder tree.

There’s no built-in “directory tree” in Markdown or most languages, but there are a couple of simple text conventions that work really well everywhere.

This post shows the only two styles I actually use:

A Unicode box-drawing tree (nice and clean in modern environments).
A pure ASCII tree (works anywhere).

General rules

Whichever style you pick:

Put trees in a monospace context:
- In Markdown: use fenced code blocks (for example, ```text).
- In code: put them inside a comment block.
Use spaces, not tabs for indentation.
Keep depth to about 3–4 levels; split huge trees into multiple sections.
Always add / to directory names so an empty folder is still obviously a folder.

Pattern 1: Box-drawing tree (Unicode)

This is the “A+” version. It uses Unicode box-drawing characters and looks clean in modern terminals, editors, and browsers.

my-app/
├─ src/
│  ├─ components/
│  │  └─ Button.tsx
│  ├─ pages/
│  │  └─ Home.tsx
│  └─ main.ts
├─ package.json
└─ README.md

Rules for the box-drawing style

Directories: always end with /
Non-last child: ├─
Last child: └─
Indent under a parent with:
- more siblings below → │
- last in that branch → (spaces)

In the example above:

src/, package.json, and README.md are children of my-app/.
src/ and package.json aren’t last children, so they use ├─.
README.md is the last child, so it uses └─.
Under src/, the vertical continuation is drawn with │ .

When to use it

Use the box-drawing style when:

You’re writing a blog post, README, ADR, or design doc that will be viewed in a modern browser or editor.
You want something more visually refined than raw ASCII.
You’re happy to rely on Unicode and monospace fonts (which is fine for almost all modern tooling).

If the characters ever look misaligned in a specific environment, fall back to the ASCII tree below.

How to get the box-drawing characters

macOS: press Ctrl + Cmd + Space, search “box drawing”, then click the characters (├, └, │, ─).
Windows: use the emoji/character picker (Win + .) or the “Character Map” app and search for “Box Drawing”.
Linux (GTK apps): often support Ctrl + Shift + U, then the hex code (e.g. 251C → ├, 2514 → └, 2502 → │, 2500 → ─).

Realistically: copy one good tree into a scratch file and just edit the names.

Does Unicode break anything?

Used in comments or Markdown, these characters:

Are fine as long as the file is saved as UTF-8 (which is the default almost everywhere now).
Won’t affect compilation because compilers ignore the content of comments once they’ve tokenised them.
At worst, will show up as boxes/� in very old or misconfigured environments.

If you’re working in a very conservative environment and are worried about tools not handling Unicode nicely, use the ASCII pattern below in that codebase.

Pattern 2: ASCII tree

This style uses only plain ASCII characters. It’s a bit more old-school but it never breaks.

my-app/
|-- src/
|   |-- components/
|   |   \-- Button.tsx
|   |-- pages/
|   |   \-- Home.tsx
|   \-- main.ts
|-- package.json
\-- README.md

Rules for the ASCII style

Directories: always end with /
Non-last sibling: |--
Last sibling: \--
Indent:
- under a continuing parent → |
- under a last parent → (spaces)

In the example above:

src/, package.json, and README.md are children of my-app/.
src/ and package.json aren’t last children, so they use |--.
README.md is the last child, so it uses \--.
Under src/, the tree continues with | until you reach the last child in that branch, where the indent switches to plain spaces.

When to use it

Use the ASCII style when:

You need maximum compatibility (older terminals, unusual fonts, plain-text emails, or tooling where you’re not sure about Unicode support).
You want to match the feel of classic tree output.
You’re dropping the tree into places where the rendering environment is unknown.

Using these trees in docs (Markdown, wikis, etc.)

In docs, the only thing you really need is a fenced code block so spacing is preserved and a monospace font is used.

my-app/
├─ src/
│  ├─ components/
│  │  └─ Button.tsx
│  ├─ pages/
│  │  └─ Home.tsx
│  └─ main.ts
├─ package.json
└─ README.md

You can use text, plain, or no language hint at all — the important part is the fenced block.

If you need maximum compatibility in exported docs (PDFs, plain text), use the ASCII style instead:

my-app/
|-- src/
|   |-- components/
|   |   \-- Button.tsx
|   |-- pages/
|   |   \-- Home.tsx
|   \-- main.ts
|-- package.json
\-- README.md

Using these trees in code comments

The trees are just plain text, so you can drop them straight into comments.

C++ (box-drawing):

// Project layout:
// my-app/
// ├─ src/
// │  ├─ components/
// │  │  └─ Button.cpp
// │  └─ main.cpp
// ├─ CMakeLists.txt
// └─ README.md

C++ (ASCII):

// Project layout:
// my-app/
// |-- src/
// |   |-- components/
// |   |   \-- Button.cpp
// |   \-- main.cpp
// |-- CMakeLists.txt
// \-- README.md

Python (ASCII, same idea):

# Project layout:
# my_app/
# |-- src/
# |   |-- handlers/
# |   |   \-- __init__.py
# |   \-- main.py
# |-- pyproject.toml
# \-- README.md

Guidelines:

Prefer the ASCII style if you’re worried about older tooling or weird encodings.
Keep the tree within your usual line width (e.g. 80–100 chars).
Treat the tree as an explanatory snapshot, not the source of truth for the structure.

Which one should you use?

My rules of thumb:

Docs, READMEs, ADRs, blog posts

Use the box-drawing style. It’s easier to scan and looks good in modern environments.
Anything that might end up in plain text or old tools

Use the ASCII style. It’s as compatible as it gets.

Within a single document, pick one style and stick to it. Once you’ve chosen, the rest is just copy, paste, and adjust the names.