Representing Directory & File Structure in Markdown Syntax
UnicodeMarkdownJekyllDirectory StructureProject StructureUnicode Problem Overview
I want to describe directory & file structures in some of my Jekyll blog posts, does Markdown provide a neat way of outputting such a thing?
For example, you can see at this link on the Jekyll website that the directory & file structure is output on the page very neatly:
.
├── _config.yml
├── _drafts
│ ├── begin-with-the-crazy-ideas.textile
│ └── on-simplicity-in-technology.markdown
├── _includes
│ ├── footer.html
│ └── header.html
├── _layouts
│ ├── default.html
│ └── post.html
├── _posts
│ ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
│ └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _data
│ └── members.yml
├── _site
└── index.html
I believe the line block characters above are Unicode (as described in this answer here), but I am not sure how Markdown or different browsers will handle them. I was hoping that Markdown had included some way of doing this which outputs as the Unicode characters above perhaps.
Unicode Solutions
Solution 1 - Unicode
I followed an example in another repository and wrapped the directory structure within a pair of triple backticks (```
):
```
project
│ README.md
│ file001.txt
│
└───folder1
│ │ file011.txt
│ │ file012.txt
│ │
│ └───subfolder1
│ │ file111.txt
│ │ file112.txt
│ │ ...
│
└───folder2
│ file021.txt
│ file022.txt
```
Solution 2 - Unicode
If you are concerned about Unicode characters you can use ASCII to build the structures, so your example structure becomes
.
+-- _config.yml
+-- _drafts
| +-- begin-with-the-crazy-ideas.textile
| +-- on-simplicity-in-technology.markdown
+-- _includes
| +-- footer.html
| +-- header.html
+-- _layouts
| +-- default.html
| +-- post.html
+-- _posts
| +-- 2007-10-29-why-every-programmer-should-play-nethack.textile
| +-- 2009-04-26-barcamp-boston-4-roundup.textile
+-- _data
| +-- members.yml
+-- _site
+-- index.html
Which is similar to the format tree
uses if you select ANSI
output.
Solution 3 - Unicode
If you're using VS Code, this is an awesome extension for generating file trees.
Added directly to markdown...
📦quakehunter
┣ 📂client
┣ 📂node_modules
┣ 📂server
┃ ┗ 📜index.js
┣ 📜.gitignore
┣ 📜package-lock.json
┗ 📜package.json
Solution 4 - Unicode
You can use tree to generate something very similar to your example. Once you have the output, you can wrap it in a <pre>
tag to preserve the plain text formatting.
Solution 5 - Unicode
As already recommended, you can use tree
. But for using it together with restructured text some additional parameters were required.
The standard tree
output will not be printed if your're using pandoc
to produce pdf.
tree --dirsfirst --charset=ascii /path/to/directory
will produce a nice ASCII
tree that can be integrated into your document like this:
.. code::
.
|-- ContentStore
| |-- de-DE
| | |-- art.mshc
| | |-- artnoloc.mshc
| | |-- clientserver.mshc
| | |-- noarm.mshc
| | |-- resources.mshc
| | `-- windowsclient.mshc
| `-- en-US
| |-- art.mshc
| |-- artnoloc.mshc
| |-- clientserver.mshc
| |-- noarm.mshc
| |-- resources.mshc
| `-- windowsclient.mshc
`-- IndexStore
|-- de-DE
| |-- art.mshi
| |-- artnoloc.mshi
| |-- clientserver.mshi
| |-- noarm.mshi
| |-- resources.mshi
| `-- windowsclient.mshi
`-- en-US
|-- art.mshi
|-- artnoloc.mshi
|-- clientserver.mshi
|-- noarm.mshi
|-- resources.mshi
`-- windowsclient.mshi
Solution 6 - Unicode
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
Solution 7 - Unicode
If you're using Atom editor, you can accomplish this by the ascii-tree package.
You can write the following tree:
root
+-- dir1
+--file1
+-- dir2
+-- file2
and convert it to the following by selecting it and pressing ctrl-alt-t
:
root
├── dir1
│ └── file1
└── dir2
└── file2
Solution 8 - Unicode
I scripted this for my Dropbox file list.
sed
is used for removing full paths of symlinked file/folder path coming after ->
Unfortunately, tabs are lost. Using zsh
I am able to preserve tabs.
!/usr/bin/env bash
#!/usr/bin/env zsh
F1='index-2.md' #With hyperlinks
F2='index.md'
if [ -e $F1 ];then
rm $F1
fi
if [ -e $F2 ];then
rm $F2
fi
DATA=`tree --dirsfirst -t -Rl --noreport | \
sed 's/->.*$//g'` # Remove symlink adress and ->
echo -e '```\n' ${DATA} '\n```' > $F1 # Markdown needs triple back ticks for <pre>
# With the power of piping, creating HTML tree than pipe it
# to html2markdown program, creates cool markdown file with hyperlinks.
DATA=`tree --dirsfirst -t -Rl --noreport -H http://guneysu.pancakeapps.com`
echo $DATA | \
sed 's/\r\r/\n/g' | \
html2markdown | \
sed '/^\s*$/d' | \
sed 's/\# Directory Tree//g' | \
> $F2
The outputs like this:
```
.
├── 2013
│ └── index.markdown
├── 2014
│ └── index.markdown
├── 2015
│ └── index.markdown
├── _posts
│ └── 2014-12-27-2014-yili-degerlendirmesi.markdown
├── _stash
└── update.sh
```
[BASE_URL/](BASE_URL/)
├── [2013](BASE_URL/2013/)
│ └── [index.markdown](BASE_URL/2013/index.markdown)
├── [2014](BASE_URL/2014/)
│ └── [index.markdown](BASE_URL/2014/index.markdown)
├── [2015](BASE_URL/2015/)
│ └── [index.markdown](BASE_URL/2015/index.markdown)
├── [_posts](BASE_URL/_posts/)
│ └── [2014-12-27-2014-yili-degerlendirmesi.markdown](_posts/2014-12-27-2014-yili-degerlendirmesi.markdown)
├── [_stash](BASE_URL/_stash/)
├── [index-2.md](BASE_URL/index-2.md)
└── [update.sh](BASE_URL/update.sh)
* * *
tree v1.6.0 © 1996 - 2011 by Steve Baker and Thomas Moore
HTML output hacked and copyleft © 1998 by Francesc Rocher
Charsets / OS/2 support © 2001 by Kyosuke Tokoro
Solution 9 - Unicode
I'd suggest using wasabi then you can either use the markdown-ish feel like this
root/ # entry comments can be inline after a '#'
# or on their own line, also after a '#'
readme.md # a child of, 'root/', it's indented
# under its parent.
usage.md # indented syntax is nice for small projects
# and short comments.
src/ # directories MUST be identified with a '/'
fileOne.txt # files don't need any notation
fileTwo* # '*' can identify executables
fileThree@ # '@' can identify symlinks
and throw that exact syntax at the js library for this
Solution 10 - Unicode
Under OSX, using reveal.js
, I have got rendering issue if I just user tree
and then copy/paste the output: strange symbols appear.
I have found 2 possible solutions.
-
Use charset ascii and simply copy/paste the output in the markdown file
tree -L 1 --charset=ascii
-
Use directly HTML and unicode in the markdown file
. ⊢ README.md ⊢ docs ⊢ e2e ⊢ karma.conf.js ⊢ node_modules ⊢ package.json ⊢ protractor.conf.js ⊢ src ⊢ tsconfig.json ⌙ tslint.json
Hope it helps.
Solution 11 - Unicode
If you wish to generate it dynamically I recommend using Frontend-md. It is simple to use.
Solution 12 - Unicode
There is an NPM module for this:
It allows you to have a representation of a directory tree as a string or an object. Using it with the command line will allow you to save the representation in a txt file.
Example:
$ npm dree parse myDirectory --dest ./generated --name tree