Public | Automated Build

Last pushed: 2 years ago
Short Description
Short description is empty for this repo.
Full Description


CGI script and config for serving HTML for markdown files.

Markdown generation happens in the client side using javascript markdown library (marked).

A cgi shell script creates the HTML skeleton and javascript for the transformation.

A Dockerfile is included that builds a preconfigured nginx image which can be run with docker.

Running with docker

The container runs nginx with a markdown handler for all paths ending in .md. All other files (besides htmls) are not accessible, so you can expose your source repository for the documentation without exposing all the source code or other sensitive files.

The container expects the files to be served to be mounted on /www.

$ docker run -d --name docs \
    -v ~/my_repo:/www/docs/my_repo \
    -p \

Proxying the container from an external apache

Once the container is up it is possible to proxy it from an external apache server using the following config:

    ProxyPreserveHost  On
    ProxyRequests      Off

    ProxyPass          /docs
    ProxyPassReverse   /docs

Standalone Config

If you don't want to use the container you can use the following CGI config for serving the markdown files (versions for nginx and apache provided).

nginx config (+fcgiwrap)

This config uses fcgiwrap (needs to be run separately) with a unix socket (unix:/var/run/fcgiwrap.socket).

Assuming that is installed in /usr/lib/cgi-bin and you want serve files under /www:

location / {
    root   /www;
    index  index.html;

    deny all;

    location ~ (\.html|/)$ {
        allow all;

location ~ \.md$ {
    gzip off;
    root /www;
    include /etc/nginx/fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /usr/lib/cgi-bin/;
    fastcgi_param PATH_TRANSLATED $document_root$fastcgi_script_name;
    fastcgi_pass unix:/var/run/fcgiwrap.socket;


Assuming CGI is enabled and the script was dropped in the cgi-bin directory:

   [Directory /www]
           Order allow,deny
           Deny from all
           [FilesMatch "\.(html|md)$"]
                   Allow from all
           [FilesMatch "^$"]
                   Allow from all

           DirectoryIndex index.html
           Action markdownjs /cgi-bin/
           AddHandler markdownjs .md
Docker Pull Command
Source Repository