Github offers an automatic processing of markdown files (e.g. README.md) for simple and easy repository description and/or documentation. Recently I replaced gitlist with gitweb. A great pity was that gitweb hasn’t the ability to process Markdown-Code by it’s self.

Anyway, nice chance to play around with git’s hooks and let them do the hard work for us.

What is a git hook? Link to heading

A hook is a trivial BASH-Script which would be executed by git under special circumstances like a new push to a special branch or special content inside the committed source (or what ever you wnat to keep managed). So what must be done to create and activate a git-hook? The answer is very simple and including only three steps:

If it isn’t available, we’ve to install markdown first. On a machine which is based on Debian you could use your packaging-system for this task.

apt-get install markdown

Inside the “hooks”-directory of our bare repository, we only have to create a file named ‘post-receive’ and make it executable. As content we paste the following two line into the fresh file. The filename is mandatory in this case, because git will proof the existence of specific files and will execute them if possible.

#!/bin/sh
git cat-file blob HEAD:README.md | markdown > $GIT_DIR/README.html

So making it executable should be the easiest part of the job.

chmod +x post-recevie

And that’s it. You could find a very nice overview of all available hooks here.