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.
Note: This documentation refers to the 1.0.0 pre-release version
See documentaton for v0.9.9 if you are using an earlier version
$ gem install madness
$ brew install brew-gem $ brew gem install madness
$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'
Go to any directory that contains markdown files and run:
$ madness server
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
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.
./ ├── README.md ├── File.md ├── Another File.md ├── Folder │ ├── File.md │ └── image.png └── Another Folder ├── README.md └── File.md
Madness uses sensible defaults, so therefore can be executed without configuring
anything. Configuration is mostly done by having a file named
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:
# .madness.yml # path to the documentation root path: . # server port port: 3000 # server listen address bind: 0.0.0.0 # enable sidebar sidebar: true # add H1 title to files that do not have one auto_h1: true # append navigation to directory READMEs auto_nav: true # replace <!-- TOC --> in any file with its internal table of contents # set to true to enable it with the default '## Table of Contents' caption, # or set to any string that will be inserted before it as a caption. auto_toc: true # enable syntax highlighter for code snippets highlighter: true # enable the copy to clipboard icon for code snippets copy_code: true # convert [[Links]] to [Links](Links) shortlinks: false # generate a table of contents file with this name, for example: # toc: Table of Contents toc: ~ # path to theme folder, for example: # theme: _theme theme: ~ # open the server URL in the browser open: false # provide user:password for basic authentication, for example: # auth: admin:s3cr3t auth: false # if auth is enabled, specify auth realm name auth_zone: Restricted Documentation # show files with these extensions in the navigation and search, for example: # expose_extensions: pdf,docx,xlsx,txt expose_extensions: ~ # exclude directories that match these regular expressions # note that this is an array exclude: ['^[a-z_\-0-9]+$']
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
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.
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.
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.
Note that for this feature to work, your markdown document must use the #-based heading syntax.
The 'Table of Contents' heading can be customized in the configuration file.
Directories that are made only of lowercase letters, underscoes, dash and/or
/^[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.
This can be configured by using the
exclude configuration option:
# do not ignore any directory exclude: ~ # ignore only specific directories exclude: [assets, public] # ignore using regular expressions exclude: ['^public$', 'assets']
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
If you wish the navigation and search features to also show other documents
and files (for example, PDF files), you may configure the
option in the configuration file to contain a comma delimited list of
The default value of this option is
~, 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 theme full my_theme
my_theme is the folder that will be created.
To use the created theme, simply run Madness with the
$ madness server --theme my_theme
Note that the generated theme contains the SCSS files in the
subfolder, and the rendered CSS files in the
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
If you are looking to implement a smaller CSS change, run:
$ madness theme css
This will create the file
css/main.css in the current directory. Update the
file as you see fit.
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
For more information about the docker image, see: