Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



19 Commits

Repository files navigation

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)