Markdown readme files in cgit

In Git repos, it's fairly common to include a markdown readme file. This post is quickly going to go over configuring cgit to render markdown readmes. This post assumes you've already installed and configured cgit, if you need any more info on doing this, please have a look at my previous post on cgit.

Setting the readme file

The first thing to do is tell cgit where to find the readme file, this is done with the readme option in /etc/cgitrc:

readme=master:README.md

The configuration above tells cgit to look in the master branch for a file called README.md when creating the about page for a repository. It's also possible to omit the branch:

readme=:README.md

While this will display the contents of README.md, the text will not be converted to HTML:

Note: the readme option can be specified multiple times if you want to handle different possible filenames:

readme=:README.md
readme=:README.text

Adding an about filter

The about-filter option can be used to specify a script which should be used to format the readme file. The about filter will be given the readme contents via stdin and the filename as the first argument. stdout will be then be added to the about page for the repository. A very simple filter might look something like the following:

#!/bin/sh
if echo "$1" | grep -qi '\.md$'; then
  markdown -
else
  cat -
fi

cgit comes with a standard about filter which can be configured as follows in /etc/cgitrc:

about-filter=/usr/lib/cgit/filters/about-formatting.sh

This script will call /usr/lib/cgit/filters/html-converters/md2html for markdown files. If everything goes well the about page should now be rendered:

Note: the md2html script is written in Python 3 and assumes you have python3-markdown installed.