{"id":15406803,"url":"https://github.com/dannyben/madness","last_synced_at":"2025-05-15T17:07:00.402Z","repository":{"id":9090466,"uuid":"60835604","full_name":"DannyBen/madness","owner":"DannyBen","description":"Instant Markdown Server","archived":false,"fork":false,"pushed_at":"2025-03-21T08:04:42.000Z","size":4181,"stargazers_count":146,"open_issues_count":2,"forks_count":19,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-11T00:39:22.824Z","etag":null,"topics":["documentation-tool","gem","markdown","markdown-server","markdown-to-html","ruby"],"latest_commit_sha":null,"homepage":"https://madness.dannyb.co","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DannyBen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"DannyBen"}},"created_at":"2016-06-10T08:59:33.000Z","updated_at":"2025-05-10T07:55:40.000Z","dependencies_parsed_at":"2024-02-23T10:26:13.798Z","dependency_job_id":"02183fac-8c4c-4251-a6e8-689d1ec510d2","html_url":"https://github.com/DannyBen/madness","commit_stats":{"total_commits":582,"total_committers":13,"mean_commits":44.76923076923077,"dds":"0.43470790378006874","last_synced_commit":"c7d7263672dbc8437604700f4333f80d6d59232c"},"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DannyBen","download_url":"https://codeload.github.com/DannyBen/madness/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384987,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation-tool","gem","markdown","markdown-server","markdown-to-html","ruby"],"created_at":"2024-10-01T16:25:27.426Z","updated_at":"2025-05-15T17:06:55.394Z","avatar_url":"https://github.com/DannyBen.png","language":"Ruby","funding_links":["https://github.com/sponsors/DannyBen"],"categories":[],"sub_categories":[],"readme":"[![Madness Logo](assets/header.png)](https://github.com/dannyben/madness)\n\n# Madness - Instant Markdown Server\n\n[![Gem Version](https://badge.fury.io/rb/madness.svg)](https://badge.fury.io/rb/madness)\n[![Build Status](https://github.com/DannyBen/madness/workflows/Test/badge.svg)](https://github.com/DannyBen/madness/actions?query=workflow%3ATest)\n[![Maintainability](https://api.codeclimate.com/v1/badges/fa440dc4dbf895734d74/maintainability)](https://codeclimate.com/github/DannyBen/madness/maintainability)\n\n---\n\nMadness is a command line server for rendering markdown documents in your\nbrowser. It is designed to facilitate easy development of internal\nmarkdown-based documentation sites.\n\n\u003c!-- MADNESS_TOC --\u003e\n\n## Screenshots\n\n[![Screenshots](assets/screenshots.gif)](assets/screenshots.gif)\n\n## Install\n\n**Using Ruby:**\n\n```shell\n$ gem install madness\n```\n\n**Using Homebrew:**\n\n```shell\n$ brew install brew-gem\n$ brew gem install madness\n```\n\n**Using Docker:**\n\n```shell\n$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'\n```\n\n## Feature Highlights\n\n- Easy to use.\n- Built-in full text search.\n- Compatible with how markdown files are displayed on GitHub and GitHub pages.\n- Configure with a configuration file or command arguments.\n- Fully customizable theme.\n- Automatic generation of navigation sidebar.\n- Automatic generation of Table of Contents (site-wide and per page).\n- Can optionally show additional file types in the navigation menu (e.g. PDF\n  files).\n- Optional support for `[[Short Link]]` syntax.\n- Optional support for Mermaid diagrams.\n- Optional basic authentication.\n- Support for extended markdown syntax, such as footnotes and syntax\n  highlighting.\n\n## Usage\n\nGo to any directory that contains markdown files and run:\n\n```shell\n$ madness server\n```\n\nAnd open \u003chttp://localhost:3000\u003e in your browser.\n\nFor more options, run:\n\n```shell\n$ madness --help\n```\n\n## Directory Conventions\n\nMadness expects to be executed in a documentation directory.\n\nA documentation directory contains only markdown files (`*.md`) and sub\ndirectories that contain more markdown files.\n\nThe navigation sidebar will show all the sub directories and files in the same\ndirectory as the viewed file.\n\nExample structure:\n\n```\n./\n├── README.md\n├── File.md\n├── Another File.md\n├── Folder\n│   ├── File.md\n│   └── image.png\n└── Another Folder\n    ├── README.md\n    └── File.md\n```\n\n## Configuration File\n\nMadness uses sensible defaults, so therefore can be executed without configuring\nanything. Configuration is mostly done by having a file named `.madness.yml` in\nyour documentation directory.\n\nFor convenience, you can generate a template config file by running:\n\n```shell\n$ madness config new\n```\n\nwhich will generate this file, with all the default options:\n\n```yaml\n# .madness.yml\n\n# path to the documentation root\npath: .\n\n# server port\nport: 3000\n\n# server listen address\nbind: 0.0.0.0\n\n# set a server root path, for example:\n# base_uri: /docs\nbase_uri: ~\n\n# set the underlying markdown renderer:\n# renderer: redcarpet    # default renderer\n# renderer: pandoc       # pandoc renderer, requires pandoc command\nrenderer: redcarpet\n\n# choose navigation sort order:\n# sort_order: dirs_first     # alphabetic directories then alphabetic files\n# sort_order: mixed          # alphabetic regardless of type\nsort_order: dirs_first\n\n# enable sidebar\nsidebar: true\n\n# add H1 title to files that do not have one\nauto_h1: true\n\n# append navigation to directory READMEs\nauto_nav: true\n\n# replace \u003c!-- TOC --\u003e in any file with its internal table of contents\n# set to true to enable it with the default '## Table of Contents' caption,\n# or set to any string that will be inserted before it as a caption.\nauto_toc: true\n\n# enable syntax highlighter for code snippets\nhighlighter: true\n\n# enable mermaid diagramming and charting\n# put your diagram code inside \u003cdiv class='mermaid'\u003e...\u003c/div\u003e\nmermaid: false\n\n# enable the copy to clipboard icon for code snippets\ncopy_code: true\n\n# convert [[Links]] to [Links](Links)\nshortlinks: false\n\n# generate a table of contents file with this name, for example:\n# toc: Table of Contents\ntoc: ~\n\n# path to theme folder, for example:\n# theme: _theme\ntheme: ~\n\n# enable a link to the page's source at the bottom of each page by setting\n# a URL pattern here. Use '%{path}' anywhere in the string to get the\n# URI-encoded path of the page.\n# source_link: http://example.com/%{path}\nsource_link: ~\n\n# if source_link is enabled, you can change the default link label\n# source_link_label: Edit Page\nsource_link_label: Page Source\n\n# if source_link is enabled, you can change its position (top / bottom)\n# source_link_pos: top\nsource_link_pos: bottom\n\n# open the server URL in the browser\nopen: false\n\n# provide user:password for basic authentication, for example:\n# auth: admin:s3cr3t\nauth: false\n\n# if auth is enabled, specify auth realm name\nauth_zone: Restricted Documentation\n\n# show files with these extensions in the navigation and search, for example:\n# expose_extensions: pdf,docx,xlsx,txt\nexpose_extensions: ~\n\n# exclude directories that match these regular expressions\n# note that this is an array\nexclude: ['^[a-z_\\-0-9]+$']\n```\n\n## Features\n\n### Cover Pages\n\nCover pages are specially named markdown files that serve as the introduction\nto the contents of a specific directory.\n\nThe server will consider any of the following files as cover pages (prioritized):\n\n- A markdown file with the same name as the directory (adjacent to it).\n- `index.md`\n- `README.md`\n- `readme.md`\n\nFor example, for a directory named \"API Documentation\":\n\n- `/API Documentation.md`\n- `/API Documentation/index.md`\n- `/API Documentation/README.md`\n- `/API Documentation/readme.md`\n\n### Search\n\nMadness comes with a full text search page.\n\n### Images and Static Files\n\nYou can put images and other asset files anywhere in your documentation\nfolder.\n\nWhen linking to other pages or images in your documentation folder, simply\nuse the URL relative to the markdown file. \n\nFor example, if you have a folder named `subfolder` that contains a \n`README.md` and a `nice-picture.png`, showing it in your `README` is done by\nthis markdown:\n\n```markdown\n![alt text](nice-picture.png)\n```\n\nIf you wish to link to images or pages in a different folder, simply specify\nthe path relative to the homepage:\n\n```markdown\n![alt text](/images/nice-picture.png)\n```\n\n### Automatic H1\n\nIf your markdown document does not start with a level 1 heading, it\nwill be automatically added based on the file name.\n\n### Shortlinks\n\nWhen the `shortlinks` option is enabled, you may use a shorthand syntax for \nspecifying internal links, where `[[Anything]]` will be converted to\n`[Anything](Anything)`, which will then be rendered as an internal link to a\nfile or a directory in the same directory as the file itself.\n\n### Mermaid Diagrams and Charts\n\nWhen the `mermaid` option is enabled, you can embed Mermaid diagrams in your\ndocument using either of the following methods:\n\n1. **Using a `\u003cdiv\u003e` block with `mermaid` class**:\n\n   ```html\n   \u003cdiv class=\"mermaid\"\u003e\n     graph TD;\n     A--\u003eB;\n     A--\u003eC;\n     B--\u003eD;\n     C--\u003eD;\n   \u003c/div\u003e\n   ```\n\n2. **Using a code fence with `mermaid` language specifier**:\n\n   ````markdown\n   ```mermaid\n   graph TD;\n   A--\u003eB;\n   A--\u003eC;\n   B--\u003eD;\n   C--\u003eD;\n   ```\n   ````\n\n### Table of Contents Generation\n\n#### Site-wide\n\nTo generate a Table of Contents file for the entire site (for the directories\nand files), add something like this to your `.madness.yml` file:\n\n```yaml\ntoc: Table of Contents.md\n```\n\nThis directive will (re)generate the specified file whenever you start the\nserver.\n\n#### In-page\n\nIf you have long markdown documents, and you wish to add an inline Table of\nContents for them, simply add an HTML comment `\u003c!-- TOC --\u003e` where you want\nthe Table of Contents to be generated. The inserted list will only consider\nH2 and H3 headings.\n\nNote that for this feature to work, your markdown document must use the #-based\nheading syntax.\n\nThe 'Table of Contents' heading can be customized in the configuration file.\n\n### Hidden Directories\n\nDirectories that are made only of lowercase letters, underscoes, dash and/or\nnumbers (`/^[a-z_\\-0-9]+$/`) will not be displayed in the navigation. In\nother words, directories must have at least one uppercase letter or a space\nto be recognized as a documentation directory.\n\nThis can be configured by using the `exclude` configuration option:\n\n```yaml\n# do not ignore any directory\nexclude: ~\n\n# ignore only specific directories\nexclude: [assets, public]\n\n# ignore using regular expressions\nexclude: ['^public$', 'assets']\n```\n\n### Controlling Sort Order\n\nTo control the sort order of the automatically generated navigation elements,\nsimply prefix your files and directories with digits followed by a dot and a \nspace, just like you would create an ordered list in Markdown. The numbers\nwill be omitted when they are displayed.\n\n```\n./\n├── 1. Some file or folder\n└── 2. Another file or folder\n```\n\nNote that by default, directories will appear above files. If you wish to\nchange this, set `sort_order: mixed` in your configuration file.\n\n### Displaying Additional File Types\n\nIf you wish the navigation and search features to also show other documents\nand files (for example, PDF files), you may configure the `expose_extensions`\noption in the configuration file to contain a comma delimited list of\nextensions:\n\n```yaml\nexpose_extensions: pdf,docx,xlsx,txt\n```\n\nThe default value of this option is `null` (or `~`, which is `null` in YAML).\n\n### Basic Authentication\n\nTo add basic authentication, use the `--auth user:password` command line argument or the equivalent `auth` configuration option.\n\nIf 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:\n\n```yaml\nauth: \u003c%= ENV['BASIC_AUTH'] %\u003e\n```\n\n## Customizing Theme\n\nThere are three ways to change how Madness looks. \n\n### Option 1: CSS Overrides\n\nAny CSS file found in the `./css` directory of your documentation root will \nbe loaded *after* the main CSS.\n\nYou can use the following command to create a `css/colors.css` file, which lets\nyou override all colors.\n\n```shell\n$ madness theme colors\n```\n\n### Option 2: Override the entire CSS\n\nIf your documentation root contains a file named `css/main.css` it will be \nloaded instead of the built-in madness CSS.\n\nYou can get the built-in CSS file by running the following command.\n\n```shell\n$ madness theme css\n```\n\n### Option 3: Change CSS and HTML (Slim)\n\nIn order to have complete control over the CSS and generated HTML, you\ncan override the views and styles. Views are provided as Slim templates, \nand CSS is provided as SCSS.\n\nYou can get these files by running the following command.\n\n```shell\n$ madness theme full my_theme\n```\n\nWhere `my_theme` is the folder that will be created.\n\nTo use the created theme, simply run Madness with the `--theme my_theme`\noption (which can also be configured in the configuration file).\n\n```shell\n$ madness server --theme my_theme\n```\n\nNote that the generated theme contains the SCSS files in the `styles`\nsubfolder, and the rendered CSS files in the `public/css` subfolder.\n\nIf you wish to use the SCSS files, you will need to render them yourself\nto the location of your theme styles (e.g. `public/css`) - you can use\nany tool to do so, or if you do not have a preference, use\n[SassTool][sasstool].\n\n\n## Docker Image\n\nMadness server is also available as a docker image.\n\nThis command will start the server on localhost:3000, with the current \ndirectory as the markdown documentation folder\n\n```shell\n$ docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness server\n```\n\nYou may create an alias for convenience:\n\n```shell\n$ alias madness='docker run --rm -it -v $PWD:/docs -p 3000:3000 dannyben/madness'\n$ madness --help\n```\n\nor use docker compose:\n\n```yaml\n# docker-compose.yml\nservices:\n  web:\n    image: dannyben/madness\n    volumes: [\".:/docs\"]\n    ports: [\"3000:3000\"]\n    command: server\n```\n\nFor more information about the docker image, see:\n\n- [Madness image on Docker Hub][dockerhub]\n- [Madness Dockerfile][dockerfile]\n\n\n[dockerhub]: https://hub.docker.com/r/dannyben/madness/\n[dockerfile]: https://github.com/DannyBen/madness/blob/master/Dockerfile\n[css]: https://github.com/DannyBen/madness/blob/master/app/public/css/main.css\n[sasstool]: https://github.com/DannyBen/sasstool\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fmadness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannyben%2Fmadness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fmadness/lists"}