{"id":15406861,"url":"https://github.com/dannyben/madman","last_synced_at":"2026-01-08T10:16:50.597Z","repository":{"id":43380535,"uuid":"133925744","full_name":"DannyBen/madman","owner":"DannyBen","description":"The Markdown Swiss Army Knife","archived":false,"fork":false,"pushed_at":"2024-02-27T05:25:49.000Z","size":199,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-01T14:12:08.838Z","etag":null,"topics":["gem","markdown","markdown-preview","markdown-server","ruby"],"latest_commit_sha":null,"homepage":"","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":null,"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}},"created_at":"2018-05-18T08:25:14.000Z","updated_at":"2024-01-12T18:06:35.000Z","dependencies_parsed_at":"2024-10-01T16:26:02.253Z","dependency_job_id":"87c7e708-029b-4929-9900-cb0723c58eeb","html_url":"https://github.com/DannyBen/madman","commit_stats":{"total_commits":138,"total_committers":2,"mean_commits":69.0,"dds":"0.39855072463768115","last_synced_commit":"308b23c77931a91b2ad7b8b30d36905a1310e3f4"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DannyBen%2Fmadman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DannyBen","download_url":"https://codeload.github.com/DannyBen/madman/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249419041,"owners_count":21268551,"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":["gem","markdown","markdown-preview","markdown-server","ruby"],"created_at":"2024-10-01T16:25:59.132Z","updated_at":"2026-01-08T10:16:50.590Z","avatar_url":"https://github.com/DannyBen.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Madman\n==================================================\n\nThe Markdown Swiss Army Knife\n\nInstallation\n--------------------------------------------------\n\n```\n$ gem install madman\n```\n\nOr with Bundler:\n\n```ruby\ngem 'madman', require: false\n```\n\n\n\nFeatures\n--------------------------------------------------\n\n- [x] GitHub-style markdown generation (markup and stylesheet).\n- [x] Convert markdown to HTML file.\n- [x] Ad-hoc server to serve a markdown file locally for preview.\n- [ ] Ad-hoc server to allow editing of a local markdown file.\n- [x] Markdown generation with GitHub API (optional).\n- [x] Table of Contents generation for a folder of markdown files.\n- [x] Web server for an entire folder (like [Madness][1]) with GitHub Pages compatibility.\n- [x] Automatic detection of Right-to-Left markdown files for HTML rendering.\n- [x] Generate navigation README in folders without one.\n- [x] Convert YAML file to an interactive HTML with collapsible sections.\n- [ ] Generate breadcrumbs.\n- [ ] Combine multiple markdown files to one.\n- [ ] Table of Contents generation for a single file.\n\n\n\nUsage\n--------------------------------------------------\n\n\u003c!-- usage --\u003e\n\n```\n$ madman\nCommands:\n  nav      Add site-wide navigation links to README files\n  preview  Serve a markdown or YAML file using a local server\n  readme   Create README in all qualified sub directories\n  render   Render markdown or YAML to HTML\n  serve    Serve a markdown directory using a local server\n```\n\n\u003c!-- usage --\u003e\n\n### Render Markdown or YAML to HTML\n\n\u003c!-- render --\u003e\n\n```\n$ madman render\nUsage:\n  madman render FILE [--github --save OUTFILE]\n  madman render (-h|--help)\n```\n\n\u003c!-- render --\u003e\n\n\u003cdetails\u003e\u003csummary\u003eShow full usage\u003c/summary\u003e\n\u003c!-- render-help --\u003e\n\n```\n$ madman render --help\nRender markdown or YAML to HTML\n\nUsage:\n  madman render FILE [--github --save OUTFILE]\n  madman render (-h|--help)\n\nOptions:\n  --github\n    Render using the GitHub API\n    Requires setting the GITHUB_ACCESS_TOKEN environment variable\n\n  --save OUTFILE\n    Save the output to a file\n\n  -h --help\n    Show this help\n\nParameters:\n  FILE\n    The input markdown or YAML file\n\nEnvironment Variables:\n  GITHUB_ACCESS_TOKEN\n    Your GitHub API access token\n    Generate one here: https://github.com/settings/tokens\n\nExamples:\n  madman render README.md\n  madman render README.md --github\n  madman render README.md --save out.html\n  madman render file.yml --save out.html\n```\n\n\u003c!-- render-help --\u003e\n\u003c/details\u003e\n\n### Preview Markdown or HTML in Browser\n\n\u003c!-- preview --\u003e\n\n```\n$ madman preview\nUsage:\n  madman preview FILE [--port N --bind ADDRESS]\n  madman preview (-h|--help)\n```\n\n\u003c!-- preview --\u003e\n\n\u003cdetails\u003e\u003csummary\u003eShow full usage\u003c/summary\u003e\u003c!-- preview-help --\u003e\n\n```\n$ madman preview --help\nServe a markdown or YAML file using a local server\n\nThis command will start a local server with two endpoints:\n  /         will render the markdown with the default renderer\n  /github   will render with the GitHub API\n\nUsage:\n  madman preview FILE [--port N --bind ADDRESS]\n  madman preview (-h|--help)\n\nOptions:\n  -p --port N\n    Set server port [default: 3000]\n\n  -b --bind ADDRESS\n    Set server listen address [default: 0.0.0.0]\n\n  -h --help\n    Show this help\n\nParameters:\n  FILE\n    The input markdown or YAML file\n\nEnvironment Variables:\n  GITHUB_ACCESS_TOKEN\n    Your GitHub API access token\n    Required only if you wish to use the '/github' endpoint\n    Generate one here: https://github.com/settings/tokens\n\nExamples:\n  madman preview README.md\n  madman preview README.md -p4000\n  madman preview file.yml\n```\n\n\u003c!-- preview-help --\u003e\u003c/details\u003e\n\n\n### Personal Wiki (Serve a complete Markdown folder)\n\n\u003c!-- serve --\u003e\n\n```\n$ madman serve\nUsage:\n  madman serve DIR [--port N --bind ADDRESS --github]\n  madman serve (-h|--help)\n```\n\n\u003c!-- serve --\u003e\n\n\u003cdetails\u003e\u003csummary\u003eShow full usage\u003c/summary\u003e\u003c!-- serve-help --\u003e\n\n```\n$ madman serve --help\nServe a markdown directory using a local server\n\nUsage:\n  madman serve DIR [--port N --bind ADDRESS --github]\n  madman serve (-h|--help)\n\nOptions:\n  --github\n    Use the GitHub API renderer instead of the default one\n\n  -p --port N\n    Set server port [default: 3000]\n\n  -b --bind ADDRESS\n    Set server listen address [default: 0.0.0.0]\n\n  -h --help\n    Show this help\n\nParameters:\n  DIR\n    The directory containing markdown files\n\nEnvironment Variables:\n  GITHUB_ACCESS_TOKEN\n    Your GitHub API access token\n    Required only if you wish to use the '/github' endpoint\n    Generate one here: https://github.com/settings/tokens\n\nExamples:\n  madman serve\n  madman serve path/to/docs -p4000 --github\n```\n\n\u003c!-- serve-help --\u003e\u003c/details\u003e\n\n\n### Inject Site Navigation (Table of Contents)\n\n\u003c!-- nav --\u003e\n\n```\n$ madman nav\nUsage:\n  madman nav DIR [options]\n  madman nav (-h|--help)\n```\n\n\u003c!-- nav --\u003e\n\n\u003cdetails\u003e\u003csummary\u003eShow full usage\u003c/summary\u003e\u003c!-- nav-help --\u003e\n\n```\n$ madman nav --help\nAdd site-wide navigation links to README files\n\nThis command generates a Table of Contents for a directory, and injects it to a\nfile. In addition, it supports recursive execution, which will add a Table of\nContents to all README files (or a filename of your choice) in all the\nsubfolders, creating nagigation pages for an entire Markdown site.\n\nUsage:\n  madman nav DIR [options]\n  madman nav (-h|--help)\n\nOptions:\n  -f --force\n    Inject TOC to all README files, even if they do not have a marker\n\n  -m --marker TEXT\n    Look for an HTML comment with \u003c!-- TEXT --\u003e [default: nav]\n\n  -d --depth N\n    The depth of the table of contents [default: 1]\n\n  -v --verbose\n    Show the updated README content\n\n  -t --target NAME\n    Set the target filename to look for. [default: README.md]\n\n  -r --recursive\n    Inject to all target files\n\n  -y --dry\n    Do not save the updated files, just show what will happen\n\n  -h --help\n    Show this help\n\nParameters:\n  DIR\n    The directory containing markdown files\n\nExamples:\n  madman nav\n  madman nav path/to/docs --force --marker toc\n  madman nav path/to/docs --dry -v -d2\n```\n\n\u003c!-- nav-help --\u003e\u003c/details\u003e\n\n\n### Generate README files with H1\n\n\u003c!-- readme --\u003e\n\n```\n$ madman readme\nUsage:\n  madman readme DIR [--dry]\n  madman readme (-h|--help)\n```\n\n\u003c!-- readme --\u003e\n\n\u003cdetails\u003e\u003csummary\u003eShow full usage\u003c/summary\u003e\u003c!-- readme-help --\u003e\n\n```\n$ madman readme --help\nCreate README in all qualified sub directories\n\nThis command generates README.md files in all subdirectories. Each file will\nreceive an H1 caption with the name of the folder it resides in. This command is\ndesigned to assist in preparing a folder for table of contents injection.\n\nUsage:\n  madman readme DIR [--dry]\n  madman readme (-h|--help)\n\nOptions:\n  -y --dry\n    Only show what will be created, don't make any changes\n\n  -h --help\n    Show this help\n\nParameters:\n  DIR\n    The directory containing markdown files\n\nExamples:\n  madman readme .\n  madman readme path/to/docs --dry\n```\n\n\u003c!-- readme-help --\u003e\u003c/details\u003e\n\n\n[1]: https://github.com/DannyBen/madness\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fmadman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannyben%2Fmadman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannyben%2Fmadman/lists"}