madness

Madness - Instant Markdown Server

Madness is a command line server for rendering markdown documents in your browser. It is designed to facilitate easy development of internal markdown-based documentation sites.

Screenshots

Install

Using Ruby:

$ gem install madness

Using Homebrew:

$ brew install brew-gem
$ brew gem install madness

Using Docker:

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

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.
• Built-in light and dark theme support.
• Automatic generation of navigation sidebar.
• Automatic generation of Table of Contents (site-wide and per page).
• Can optionally show additional file types in the navigation menu (e.g. PDF files).
• Optional support for [[Short Link]] syntax.
• Optional support for Mermaid diagrams.
• Optional basic authentication.
• Support for extended markdown syntax, such as footnotes and syntax highlighting.

Usage

Go to any directory that contains markdown files and run:

$ madness server

And open in your browser.

For more options, run:

$ madness --help

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 navigation sidebar will show all the sub directories and files in the same directory as the viewed file.

Example structure:

./
├── README.md
├── File.md
├── Another File.md
├── Folder
│   ├── File.md
│   └── image.png
└── Another Folder
    ├── README.md
    └── File.md

Configuration File

Madness uses sensible defaults, so therefore can be executed without configuring anything. Configuration is mostly done by having a file named .madness.yml in your documentation directory.

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

$ madness config new

which will generate this file, with all the default options:

…

mermaid ...

…

Features

Cover Pages

Cover pages are specially named markdown files that serve as the introduction to the contents of a specific directory.

The server will consider any of the following files as cover pages (prioritized):

• A markdown file with the same name as the directory (adjacent to it).
• index.md
• README.md
• readme.md

For example, for a directory named "API Documentation":

• /API Documentation.md
• /API Documentation/index.md
• /API Documentation/README.md
• /API Documentation/readme.md

Search

Madness comes with a full text search page.

Navigation Tree

By default, the sidebar shows the current folder's immediate children. To render the sidebar as a recursive tree of the entire documentation root, enable the nav_tree option:

nav_tree: true

Images and Static Files

You can put images and other asset files 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 README.md and a nice-picture.png, showing it in your README is done by this markdown:

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

Automatic H1

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

Shortlinks

When the shortlinks option is enabled, you may use a shorthand syntax for specifying internal links, where [[Anything]] will be converted to [Anything](Anything), which will then be rendered as an internal link to a file or a directory in the same directory as the file itself.

Mermaid Diagrams and Charts

When the mermaid option is enabled, you can embed Mermaid diagrams in your document using either of the following methods:

Using a code fence with mermaid language specifier:

```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```

**Using a `

### Table of Contents Generation

#### Site-wide

To generate a Table of Contents file for the entire site (for the directories
and files), add something like this to your `.madness.yml` file:

```yaml
toc: Table of Contents.md

…

yaml
# do not ignore any directory
exclude: ~

# ignore only specific directories
exclude: [assets, public]

# ignore using regular expressions
exclude: ['^public$', 'assets']

Controlling Sort Order

To control the sort order of the automatically generated navigation elements, simply prefix your files and directories with digits followed by a dot and a space, just like you would create an ordered list in Markdown. The numbers will be omitted when they are displayed.

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

Note that by default, directories will appear above files. If you wish to change this, set sort_order: mixed in your configuration file.

Displaying Additional File Types

If you wish the navigation and search features to also show other documents and files (for example, PDF files), you may configure the expose_extensions option in the configuration file to contain a comma delimited list of extensions:

expose_extensions: pdf,docx,xlsx,txt

The default value of this option is null (or ~, which is null in YAML).

Basic Authentication

To add basic authentication, use the --auth user:password command line argument or the equivalent auth configuration option.

If you wish to avoid storing the basic authentication credentials in the configuration file, you may use ERB tags to load the credentials from environment variables:

auth: 

Customizing Theme

There are three ways to change how Madness looks.

The built-in theme supports light and dark color schemes. It follows the browser or operating system preference by default, and readers can use the theme toggle to switch between light and dark. The selected preference is stored in the browser for future visits.

Option 1: CSS Overrides

Any CSS file found in the ./css directory of your documentation root will be loaded after the main CSS.

You can use the following command to create a css/colors.css file, which lets you override all colors.

$ madness theme colors

Option 2: Override the entire CSS

If your documentation root contains a file named css/main.css it will be loaded instead of the built-in madness CSS.

You can get the built-in CSS file by running the following command.

$ madness theme css

Option 3: 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.

You can get these files by running the following command.

$ madness theme full 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 (which can also be configured in the configuration file).

$ madness server --theme my_theme

Note that the generated theme contains the SCSS files in the styles subfolder, and the rendered CSS files in the public/css subfolder.

If you wish to use the SCSS files, you will need to render them yourself to the location of your theme styles (e.g. public/css) - you can use any tool to do so, or if you do not have a preference, use SassTool.

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 server

You may create an alias for convenience:

$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'
$ madness --help

or use docker compose:

# docker-compose.yml
services:
  web:
    image: dannyben/madness
    volumes: [".:/docs"]
    ports: ["3000:3000"]
    command: server

For more information about the docker image, see:

• Madness image on Docker Hub
• Madness Dockerfile