[github] Is there a way to represent a directory tree in a Github README.md?

In my Githubs repos documentation I want to represent a directory tree structure like this:

Is there a way to do that with Github flavoured markdown, besides just creating it with ascii art?

So basically like this question, but I'm wondering if there is a github specific solution.

You can use <pre> tags as I did in one of my projects.

If you are working on windows write tree /f inside the directory you want to achieve that in command prompt. This should do your job. you can copy and paste the output on markdown surrounded my triple back ticks i.e. '''{tree structure here}'''

I made a node module to automate this task: mddir

Usage

node mddir "../relative/path/"

To install: npm install mddir -g

To generate markdown for current directory: mddir

To generate for any absolute path: mddir /absolute/path

To generate for a relative path: mddir ~/Documents/whatever.

The md file gets generated in your working directory.

Currently ignores node_modules, and .git folders.

Troubleshooting

If you receive the error 'node\r: No such file or directory', the issue is that your operating system uses different line endings and mddir can't parse them without you explicitly setting the line ending style to Unix. This usually affects Windows, but also some versions of Linux. Setting line endings to Unix style has to be performed within the mddir npm global bin folder.

Line endings fix

Get npm bin folder path with:

npm config get prefix

Cd into that folder

brew install dos2unix

dos2unix lib/node_modules/mddir/src/mddir.js

This converts line endings to Unix instead of Dos

Then run as normal with: node mddir "../relative/path/".

Example generated markdown file structure 'directoryList.md'

    |-- .bowerrc
    |-- .jshintrc
    |-- .jshintrc2
    |-- Gruntfile.js
    |-- README.md
    |-- bower.json
    |-- karma.conf.js
    |-- package.json
    |-- app
        |-- app.js
        |-- db.js
        |-- directoryList.md
        |-- index.html
        |-- mddir.js
        |-- routing.js
        |-- server.js
        |-- _api
            |-- api.groups.js
            |-- api.posts.js
            |-- api.users.js
            |-- api.widgets.js
        |-- _components
            |-- directives
                |-- directives.module.js
                |-- vendor
                    |-- directive.draganddrop.js
            |-- helpers
                |-- helpers.module.js
                |-- proprietary
                    |-- factory.actionDispatcher.js
            |-- services
                |-- services.cardTemplates.js
                |-- services.cards.js
                |-- services.groups.js
                |-- services.posts.js
                |-- services.users.js
                |-- services.widgets.js
        |-- _mocks
            |-- mocks.groups.js
            |-- mocks.posts.js
            |-- mocks.users.js
            |-- mocks.widgets.js

Here is a useful git alias that works for me.

git config --global alias.tree '! git ls-tree --full-name --name-only -t -r HEAD | sed -e "s/[^-][^\/]*\//   |/g" -e "s/|\([^ ]\)/|-- \1/"'

Here is the output of git tree

jonavon@XPS13:~/projects/roman-numerals$ git tree
.gitignore
pom.xml
src
   |-- main
   |   |-- java
   |   |   |-- com
   |   |   |   |-- foxguardsolutions
   |   |   |   |   |-- jonavon
   |   |   |   |   |   |-- AbstractFile.java
   |   |   |   |   |   |-- roman
   |   |   |   |   |   |   |-- Main.java
   |   |   |   |   |   |   |-- Numeral.java
   |   |   |   |   |   |   |-- RomanNumberInputFile.java
   |   |   |   |   |   |   |-- RomanNumeralToDecimalEvaluator.java
   |-- test
   |   |-- java
   |   |   |-- com
   |   |   |   |-- foxguardsolutions
   |   |   |   |   |-- jonavon
   |   |   |   |   |   |-- roman
   |   |   |   |   |   |   |-- InterpretSteps.java
   |   |   |   |   |   |   |-- RunCukesTest.java
   |   |-- resources
   |   |   |-- com
   |   |   |   |-- foxguardsolutions
   |   |   |   |   |-- jonavon
   |   |   |   |   |   |-- roman
   |   |   |   |   |   |   |-- Interpret.feature
   |   |   |-- sample-input.txt

The comparable tree command

jonavon@XPS13:~/projects/roman-numerals$ tree -n
.
+-- pom.xml
+-- src
¦   +-- main
¦   ¦   +-- java
¦   ¦       +-- com
¦   ¦           +-- foxguardsolutions
¦   ¦               +-- jonavon
¦   ¦                   +-- AbstractFile.java
¦   ¦                   +-- roman
¦   ¦                       +-- Main.java
¦   ¦                       +-- Numeral.java
¦   ¦                       +-- RomanNumberInputFile.java
¦   ¦                       +-- RomanNumeralToDecimalEvaluator.java
¦   +-- test
¦       +-- java
¦       ¦   +-- com
¦       ¦       +-- foxguardsolutions
¦       ¦           +-- jonavon
¦       ¦               +-- roman
¦       ¦                   +-- InterpretSteps.java
¦       ¦                   +-- RunCukesTest.java
¦       +-- resources
¦           +-- com
¦           ¦   +-- foxguardsolutions
¦           ¦       +-- jonavon
¦           ¦           +-- roman
¦           ¦               +-- Interpret.feature
¦           +-- sample-input.txt
+-- target
    +-- classes
    ¦   +-- com
    ¦       +-- foxguardsolutions
    ¦           +-- jonavon
    ¦               +-- AbstractFile.class
    ¦               +-- roman
    ¦                   +-- Main.class
    ¦                   +-- Numeral.class
    ¦                   +-- RomanNumberInputFile.class
    ¦                   +-- RomanNumeralToDecimalEvaluator.class
    +-- generated-sources
    ¦   +-- annotations
    +-- maven-status
        +-- maven-compiler-plugin
            +-- compile
                +-- default-compile
                    +-- createdFiles.lst
                    +-- inputFiles.lst

30 directories, 17 files

Clearly tree has better output, but I would like it to use my .gitignore file. So that my compiled content doesn't show

I got resolver the problem in this way:

1. Insert command tree in bash.

Example

2. Create a README.md in github repository and copy bash result
3. Insert in .md file within markdown code

Example

4. See the output and be happy =)

The best way to do this is to surround your tree in the triple backticks to denote a code block. For more info, see the markdown docs: http://daringfireball.net/projects/markdown/syntax#code

I wrote a small script that does the trick:

#!/bin/bash

#File: tree-md

tree=$(tree -tf --noreport -I '*~' --charset ascii $1 |
       sed -e 's/| \+/  /g' -e 's/[|`]-\+/ */g' -e 's:\(* \)\(\(.*/\)\([^/]\+\)\):\1[\4](\2):g')

printf "# Project tree\n\n${tree}"

Example:

Original tree command:

$ tree
.
+-- dir1
¦   +-- file11.ext
¦   +-- file12.ext
+-- dir2
¦   +-- file21.ext
¦   +-- file22.ext
¦   +-- file23.ext
+-- dir3
+-- file_in_root.ext
+-- README.md

3 directories, 7 files

Markdown tree command:

$ ./tree-md .
# Project tree

.
 * [tree-md](./tree-md)
 * [dir2](./dir2)
   * [file21.ext](./dir2/file21.ext)
   * [file22.ext](./dir2/file22.ext)
   * [file23.ext](./dir2/file23.ext)
 * [dir1](./dir1)
   * [file11.ext](./dir1/file11.ext)
   * [file12.ext](./dir1/file12.ext)
 * [file_in_root.ext](./file_in_root.ext)
 * [README.md](./README.md)
 * [dir3](./dir3)

Rendered result:

(Links are not visible in Stackoverflow...)

• tree-md
• dir2
  • file21.ext
  • file22.ext
  • file23.ext
• dir1
  • file11.ext
  • file12.ext
• file_in_root.ext
• README.md
• dir3

I just like to generate it with UTF-8 and link it to every file and folder to navigate really easily. Please take a look at the example here.

Insert command tree in bash.

Also, there is a DOS comnand "tree". You can displays directory paths and files in each subdirectory with command:

tree /F

https://web.csulb.edu/~murdock/tree.html

None of the above solution worked for me completely on my mac.

The best solution I found this is to use the utility created here.

https://github.com/michalbe/md-file-tree

Once you have installed the utility npm install md-file-tree -g then you can simply run to get all files tree

md-file-tree . > README.md

For those who want a quick solution:

There is a way to get a output to the console similar to the output from tree, by typing the following command into your terminal:

ls -R YOURFOLDER | grep ':$' | sed -e 's/:$//' -e 's/[^\/]*\//|  /g' -e 's/|  \([^|]\)/|–– \1/g' 

This alternative is mentioned in this documentation: https://wiki.ubuntuusers.de/tree/

Then the output can be copied and encapsuled inside a .md file with code block back tics, like mentioned in Jonathas B.C.'s answer.

But be aware that it also outputs all node modules folders in a node project. And in tree you can do something like

tree -I node_modules

to exlude the node modules folder.

You can also check this tree-extended package. It can be used as a command line app by using node >= 6.x.

It is very similar to tree but also has the option of configuring the max deep in the tree, that is one of the awful things of it. Also you can filter by using .gitignore file.

Simple tree command will do the job. For example: tree -o readme.md will print the tree structure of your current working directory and write it to readme.md. Then open readme.md file in one of text editor like Sublime and wrap its content within a pair of triple backticks (```).

FYI: you might have to brew install tree in OSX if it's not already installed. In Linux and Windows it should just work fine. Also in windows you might have to replace hyphen with forward slash.

I hope this helps.