Madman
The Markdown Swiss Army Knife
Installation
$ gem install madman
Or with Bundler:
gem 'madman', require: falseFeatures
- GitHub-style markdown generation (markup and stylesheet).
- Convert markdown to HTML file.
- Ad-hoc server to serve a markdown file locally for preview.
- Ad-hoc server to allow editing of a local markdown file.
- Markdown generation with GitHub API (optional).
- Table of Contents generation for a folder of markdown files.
- Web server for an entire folder (like Madness) with GitHub Pages compatibility.
- Automatic detection of Right-to-Left markdown files for HTML rendering.
- Generate navigation README in folders without one.
- Convert YAML file to an interactive HTML with collapsible sections.
- Generate breadcrumbs.
- Combine multiple markdown files to one.
- Table of Contents generation for a single file.
Usage
$ madman
Commands:
nav Add site-wide navigation links to README files
preview Serve a markdown or YAML file using a local server
readme Create README in all qualified sub directories
render Render markdown or YAML to HTML
serve Serve a markdown directory using a local server
Render Markdown or YAML to HTML
$ madman render
Usage:
madman render FILE [--github --save OUTFILE]
madman render (-h|--help)
$ madman render --help
Render markdown or YAML to HTML
Usage:
madman render FILE [--github --save OUTFILE]
madman render (-h|--help)
Options:
--github
Render using the GitHub API
Requires setting the GITHUB_ACCESS_TOKEN environment variable
--save OUTFILE
Save the output to a file
-h --help
Show this help
Parameters:
FILE
The input markdown or YAML file
Environment Variables:
GITHUB_ACCESS_TOKEN
Your GitHub API access token
Generate one here: https://github.com/settings/tokens
Examples:
madman render README.md
madman render README.md --github
madman render README.md --save out.html
madman render file.yml --save out.html
Preview Markdown or HTML in Browser
$ madman preview
Usage:
madman preview FILE [--port N --bind ADDRESS]
madman preview (-h|--help)
$ madman preview --help
Serve a markdown or YAML file using a local server
This command will start a local server with two endpoints:
/ will render the markdown with the default renderer
/github will render with the GitHub API
Usage:
madman preview FILE [--port N --bind ADDRESS]
madman preview (-h|--help)
Options:
-p --port N
Set server port [default: 3000]
-b --bind ADDRESS
Set server listen address [default: 0.0.0.0]
-h --help
Show this help
Parameters:
FILE
The input markdown or YAML file
Environment Variables:
GITHUB_ACCESS_TOKEN
Your GitHub API access token
Required only if you wish to use the '/github' endpoint
Generate one here: https://github.com/settings/tokens
Examples:
madman preview README.md
madman preview README.md -p4000
madman preview file.yml
Personal Wiki (Serve a complete Markdown folder)
$ madman serve
Usage:
madman serve DIR [--port N --bind ADDRESS --github]
madman serve (-h|--help)
$ madman serve --help
Serve a markdown directory using a local server
Usage:
madman serve DIR [--port N --bind ADDRESS --github]
madman serve (-h|--help)
Options:
--github
Use the GitHub API renderer instead of the default one
-p --port N
Set server port [default: 3000]
-b --bind ADDRESS
Set server listen address [default: 0.0.0.0]
-h --help
Show this help
Parameters:
DIR
The directory containing markdown files
Environment Variables:
GITHUB_ACCESS_TOKEN
Your GitHub API access token
Required only if you wish to use the '/github' endpoint
Generate one here: https://github.com/settings/tokens
Examples:
madman serve
madman serve path/to/docs -p4000 --github
Inject Site Navigation (Table of Contents)
$ madman nav
Usage:
madman nav DIR [options]
madman nav (-h|--help)
$ madman nav --help
Add site-wide navigation links to README files
This command generates a Table of Contents for a directory, and injects it to a
file. In addition, it supports recursive execution, which will add a Table of
Contents to all README files (or a filename of your choice) in all the
subfolders, creating nagigation pages for an entire Markdown site.
Usage:
madman nav DIR [options]
madman nav (-h|--help)
Options:
-f --force
Inject TOC to all README files, even if they do not have a marker
-m --marker TEXT
Look for an HTML comment with <!-- TEXT --> [default: nav]
-d --depth N
The depth of the table of contents [default: 1]
-v --verbose
Show the updated README content
-t --target NAME
Set the target filename to look for. [default: README.md]
-r --recursive
Inject to all target files
-y --dry
Do not save the updated files, just show what will happen
-h --help
Show this help
Parameters:
DIR
The directory containing markdown files
Examples:
madman nav
madman nav path/to/docs --force --marker toc
madman nav path/to/docs --dry -v -d2
Generate README files with H1
$ madman readme
Usage:
madman readme DIR [--dry]
madman readme (-h|--help)
$ madman readme --help
Create README in all qualified sub directories
This command generates README.md files in all subdirectories. Each file will
receive an H1 caption with the name of the folder it resides in. This command is
designed to assist in preparing a folder for table of contents injection.
Usage:
madman readme DIR [--dry]
madman readme (-h|--help)
Options:
-y --dry
Only show what will be created, don't make any changes
-h --help
Show this help
Parameters:
DIR
The directory containing markdown files
Examples:
madman readme .
madman readme path/to/docs --dry