Tutorial: Spruce Up Your GitHub Readme with a Current Source Tree Visualization

As programmers, we’re almost universally guilty of it: Boring Readme.md files that nobody wants to read. Why then, shouldn’t we spice up our Readme.md files with some pizzazz? A source tree visualization is easy to add to a Readme.md using GitHub markup, and there’s an open source project which makes the visualization of the tree itself a breeze. While it never found a market as a product, Source Tree Visualizer (STV) has found a new life since being open sourced last spring. Below, I’ll show you how to add STV to your build process and display the most current version in your README.md file.

Here’s what the Readme.md for “The Grind” looks like:


While you read through the tutorial below, I’ll be working on sloooowly converting my ~90 GitHub projects’ README files over to this method as well.

And here’s a graph of a dinosaur, my favorite QuickGrapher promotional graph:

I’ll be walking through the basic Debian/Mint/Ubuntu installation and configuration. You should be able to compile and run on Windows/OSX, but I can’t vouch for that lately. The steps would be the same.

  1. Install your pre-requisites with a sudo apt-get install git build-essential automake libboost1.42-dev libmagick++-dev libcurl4-openssl-dev libcurl4-gnutls-dev
  2. Check out STV from github with a git clone https://github.com/huntergdavis/Source-Tree-Visualizer
  3. Inside Source-Tree-Visualizer, initiate a compile with make. If you are having trouble compiling it on your system post back in the comments and I can post up a VirtualBox development image that’s pre-baked and ready to go.
  4. Now that you have STV compiled, execute a first interactive run over your repository with ./bin/simple_tree -i. This will execute an interactive shell which guides you through a tree visualization.
  5. If you want to add this to your build process, simply add the direct command for a git project with ./bin/simple_tree -g /path/to/build/tree Those not using git are still covered, STV supports tree generation from many types of version control.
    Here’s what the STV repository itself looks like today:

  6. Now make sure you commit that file to your repository somewhere, and browse to it on GitHub. Click on the ‘raw’ icon to get the raw link to the file.

  7. Put the raw link to the file into the following code in your Readme.md file

And Voila! When a user comes to your GitHub page, they’ll be greeted with a visual indicator of the health and layout of your project. And it’s snazzy! Best of all, the absolute location of the file never changes, so your build process can simply write to the same image every build and your Readme.md becomes much more dynamic.