![]() |
![]() |
![]() |
![]() |
Using Ruby:
$ gem install madness
Using Docker:
$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'
Madness was designed in order to provide easy browsing, viewing and searching for local, markdown based documentation directories.
Go to any directory that contains markdown files and run:
$ madness
And open http://localhost:3000 in your browser.
For more options, run:
$ madness --help
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 index.md
or README.md
in any directory
as the main file describing this directory, where index.md
has priority.
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
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: '0.0.0.0'
sidebar: true
auto_h1: true
auto_nav: true
highlighter: true
line_numbers: true
copy_code: true
toc: Table of Contents
theme: _theme
open: false
expose_extensions: ~
For convenience, you can get a template config file by running:
$ madness create config
Madness comes with a full text search page.
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:

If your markdown document does not start with a level 1 heading, it will be automatically added based on the file name.
To generate a Table of Contents file for the entire site (for the directories
and files), run madness --toc FILENAME
If you have long markdown documents, and you wish to add an inline Table of
Contents for them, simply add an HTML comment <!-- TOC -->
where you want
the Table of Contents to be generated. The inserted list will only consider
H2 and H3 headings.
Directories that are made only of lowercase letters, underscoes, dash and/or
numbers (/^[a-z_\-0-9]+$/
) will not be displayed in the navigation. In
other words, directories must have at least one uppercase letter or a space
to be recognized as a documentation directory.
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. The numbers will be omitted when they are displayed.
./
├── 1. Some file or folder
└── 2. Another file or folder
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).
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: <%= ENV['BASIC_AUTH'] %>
There are two ways to change how Madness looks.
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
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.
If you are looking to implement a smaller CSS change, follow these steps:
css
in your root documentation directory.Note that this functionality is not guaranteed to stay as is in future versions of madness.
To have Madness redirect HTTP traffic to HTTPS, set this environment variable:
$ export MADNESS_FORCE_SSL=1
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
You may create an alias for convenience:
$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'
$ medness --help
For more information about the docker image, see: