Markdown est un format de texte bien pratique. Il est possible de servir une arborescence de fichiers markdown avec Apache à l’aide du module apache-mod-markdown. Ce document décrit l’installation de ce module sur une distribution Debian (mais doit être applicable sans soucis majeurs sur d’autres distributions).

Si vous avez des difficultés lors de l’installation, les note de bas de page pourraient vous être utiles.

Prérequis

Installer les bibliothèques suivantes :

sudo apt-get install libmarkdown2-dev
sudo apt-get install apache2-threaded-dev

Pour le build, il peut être nécessaire d’ajouter autoconf et libtool :

sudo apt-get install autoconf
sudo apt-get install libtool

Build du module

Télécharger l’archive, la dézipper et se placer dans le répertoire.

Builder le source :

autoreconf -f -i
./configure --with-apxs=/usr/bin/apxs2 --with-discount=/usr
make

Copier le module dans son répertoire d’installation :

sudo mkdir /opt/misc/apache-mod-markdown/
sudo cp ./.libs/libmodmarkdown.so /opt/misc/apache-mod-markdown/mod_markdown.so

Configuration Apache

Se rendre dans le répertoire de configuration des modules d’apache /etc/apache2/mods-available pour y placer le fichier de configuration markodwn.load suivant :

LoadModule markdown_module /opt/misc/apache-mod-markdown/mod_markdown.so

On laissera le fichier de configuration du module vide :

sudo touch markdown.conf

On activera ensuite le module avec :

sudo a2enmod markdown

On devra ensuite redémarrer apache pour recharger la configuration.

Configuration du site

Dans le répertoire de configuration des sites Apache, on placera le fichier de configuration suivant :

# Apache configuration file for docs. Put this file in directory:
# /etc/apache2/sites-available. To enable this site, type :
# 
#   sudo a2ensite docs
# 
# To disable it:
# 
#   sudo a2dissite docs

Alias /docs/ /home/web/docs/
<Directory /home/web/docs/>
    AddHandler markdown .md
    DirectoryIndex index.md
    Options +Indexes
    Order allow,deny
    Allow from all
    MarkdownCss /docs/css/stylesheet.css
</Directory>

Il faudra bien sûr personnaliser le chemin du projet /home/web/docs/, l’URL du site /docs/ ainsi que l’éventuelle feuille de style à appliquer aux pages /docs/css/stylesheet.css.

Voilà ! Vous pouvez maintenant visualiser le résultat à l’URL http://localhost/docs/.

Notes

Les dernières versions de Debian ne proposent plus le package apache2-threaded-dev qui a été remplacé par apache2-dev.

Je n’ai pas pu builder les releases du module sur les dernières Debian (Jessie et Stretch). cependant, j’ai pu builder le master sans problème.

Les utilisateurs de la version 2.4 d’Apache doivent remplacer les lignes suivantes du fichier de configuration du site :

Order allow,deny
Allow from all

Par la ligne :

Require all granted

Enjoy!