Offline Rendering of GitHub Mardown

Why not a dedicated App?

I’m not a big fan of having a massive amount of windowed interfaces. A terminal emulator and a web browser are good enough for my daily routine.

When I document one of my projects on GitHub (yes, I do that), I have to write a markdown document (the README): it is very nicely rendered, first by markdown processors, then by web browsers.

However any graphical production must be visualized before being published, that’s just common sense. Conversion from plain text to a fancy rendered document never goes well at the first attempt. There are always one or two line endings that get smashed because you forgot to leave an empty line in your markdown, an emphasis on word missing, etc. Of course, I’m not talking about syntax errors since mainstream text editors, such as vim, provide pleasant syntax highlighting that prevent you from messing the markdown up.

Let alone the fact that there are like a dozen of different markdown flavours…

I simply don’t want to end up pushing my documentation to GitHub every time I want to visualize what I just wrote. Some might… but I guess.. that’s not the way to go, if you like to keep your repo history clean.

Grip

One day, Google, my good old big brother, gave me a solution to this dilemma: grip.

Grip is maintained by Joe Esposito. It is a command-line tool written in python, available through pip and which generates a preview of a markdown document. The latter is directly available on your web browser!

cd path/to/where/you/have/a/README.md
grip -b –quiet  # -b to bring in the web browser, –quiet not to echo in the terminal (it bothers me)

And boom! The markdown preview is served to you on a silver platter!
when you are done, just <CTRL-C> in the terminal to kill the local server that
grip created.
Oh, did I forget to mention it can track changes as well?

For more details, please refer to grip`s README, well, written in markdown
of course:

https://github.com/joeyespo/grip/blob/master/README.md.