simple markdown surfer
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

smurf - a simple markdown surfer

Preview any folder on your pc using a website.

Quick Demo:

$ cd ~/project/smurf
$ smurf
Starting server http://localhost:3434

Now simply open http://localhost:3434 in your web browser and you can see a directory listing. You can open any files ending in .md, .mkd, .markown, .txt and they will be converted to html on-the-fly.

smurf demo

Supports custom css, first it checks for a file named smurf.css in the directory to be served. Then it checks for a file in home directory ~/.smurf.css.

CSS is provided by sakura, a simple css theme:


smurf [PATH to Directory]

PS: Path to directory can be ommited to serve current directory.


# Download the smurf script into your local bin folder
sudo wget "" -O /usr/local/bin/smurf

# Make the script executable
sudo chmod a+x /usr/local/bin/smurf

# Download a simple css file for pretty webpages [1]
wget "" -O ~/.smurf.css

Now if you don't have pandoc installed, you'll have to download a markdown parser which is as easy as:

pip3 install --user markdown2
# make sure Python user bin directory is in your path,
# other wise you can also install like this:
# sudo pip3 install markdown2


I write notes using plain markdown files in a dropbox folder. It works really well with me, especially after combining it with zsh and vim. But the one thing I can't do is view them in a pretty format. This is why I made this script to quickly browse those markdown files.


  • Python 3
  • Any one of the following markdown parsers
    • Pandoc
    • Markdown2 (pip3 install --user markdown2)