Skip to content
Instant Markdown Server
Branch: master
Clone or download
Latest commit 9358661 Apr 26, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
app fix css issues Oct 18, 2018
assets update screenshots Jun 2, 2018
bin add executable flag Mar 11, 2017
lib version bump Jan 4, 2019
spec fix ...ture Aug 29, 2018
.gitignore remove toc file Nov 14, 2018
.rspec add support for instead of README May 30, 2018
.travis.yml update changelog Jan 4, 2019
CNAME Create CNAME Jun 1, 2018
LICENSE remove year from license Jun 11, 2016 maintenance update Apr 26, 2019

Madness - Instant Markdown Server

Gem Version Build Status Maintainability

Screenshots (click to zoom)

Table of Contents


$ gem install madness

Design Intentions

Madness was designed in order to provide easy browsing, viewing and searching for local, markdown based documentation directories.

Feature Highlights

  • Easy to use.
  • Built-in full text search.
  • Compatible with how markdown files are displayed on GitHub and GitHub pages.
  • Configure with a configuration file or command arguments.
  • Fully customizable theme.
  • Automatic generation of navigation sidebar.
  • Automatic generation of Table of Contents.


Go to any directory that contains markdown files and run:

$ madness

For more options, run:

$ madness --help

If you do not have Ruby installed, you can also run madness with docker.

Directory Conventions

Madness expects to be executed in a documentation directory.

A documentation directory contains only markdown files (*.md) and sub directories that contain more markdown files.

The server will consider the file or in any directory as the main file describing this directory, where has priority.

The navigation sidebar will show all the sub directories and files in the same directory as the viewed file.

Example structure:

├── Another
├── Folder
│   ├──
│   └── image.png
└── Another Folder

Configuration File

All the command line arguments can also be configured through a configuration file. Create a file named .madness.yml in your documentation directory, and modify any of the settings below.

# .madness.yml
path: '.'
port: '3000'
bind: ''
sidebar: true
auto_h1: true
auto_nav: true
highlighter: true
line_numbers: true
index: false
toc: Table of Contents
theme: _theme

For convenience, you can get a template config file by running:

$ madness create config


Madness comes with a full text search page. To activate it, you need to generate a search index by running madness --index or madness path/to/docs --index.

This will create an _index sub folder, and will add a new search page to your documentation server.

You will need to run this command from time to time, as your documents change or new documents are added.

Images and Static Files

You can put images and any other asset file anywhere in your documentation folder.

When linking to other pages or images in your documentation folder, simply use the URL relative to the markdown file.

For example, if you have a folder named subfolder that contains a and a nice-picture.png, showing it in your README is done by this markdown:

![alt text](nice-picture.png)

If you wish to link to images or pages in a different folder, simply specify the path relative to the homepage:

![alt text](/images/nice-picture.png)

Automatic H1

If your markdown document does not start with a level 1 heading, it will be automatically added based on the file name.

Table of Contents Generation

You can use the madness --toc command to generate a "Table of Contents" markdown file.

Hidden Directories

Diretories that are made only of lowercase letters, underscoes, dash and/or numbers (/^[a-z_\-0-9]+$/) will not be displayed in the navigation.

Controlling Sort Order

To control the sort order of the automatically generated navigation elements, simply perfix your files and directories with digits followed by a dot and a space, just like you would create an ordered list in Markdown

├── 1. Some file or folder
└── 2. Another file or folder

Customizing Theme

There are two ways to change how Madness looks.

Option 1: Change CSS and HTML (Slim)

In order to have complete control over the CSS and generated HTML, you can override the views and styles. Views are provided as Slim templates, and CSS is provided as SCSS.

Madness comes with a command that copies the default theme to a folder of your choice, where you can customize it to your taste. Run:

$ madness create theme my_theme

Where my_theme is the folder that will be created.

To use the created theme, simply run Madness with the --theme my_theme option.

$ madness --theme my_theme

Option 2: Change CSS only

If you are looking to implement a more minor CSS change, follow these steps:

  • Create a directory named css in your root documentation directory.
  • Copy the main.css file to it.
  • Update it as you see fit.

Note that this functionality is not guaranteed to stay as is in future versions of madness.

Forcing HTTPS Connection

To have Madness redirect HTTP traffic to HTTPS, set this environment variable:


Docker Image

Madness server is also available as a docker image.

This command will start the server on localhost:3000, with the current directory as the markdown documentation folder

$ docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness

For more information about the docker image, see:

You can’t perform that action at this time.