{"id":13903116,"url":"https://github.com/andrewbrey/mdrb","last_synced_at":"2025-07-05T21:42:21.991Z","repository":{"id":65408156,"uuid":"591805345","full_name":"andrewbrey/mdrb","owner":"andrewbrey","description":"Turn your Markdown documentation into executable runbooks.","archived":false,"fork":false,"pushed_at":"2024-10-19T21:26:36.000Z","size":6946,"stargazers_count":32,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T12:04:15.239Z","etag":null,"topics":["cli","deno","markdown","runbook"],"latest_commit_sha":null,"homepage":"https://jsr.io/@andrewbrey/mdrb","language":"TypeScript","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/andrewbrey.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2023-01-21T23:14:25.000Z","updated_at":"2024-10-19T21:27:52.000Z","dependencies_parsed_at":"2024-01-14T04:40:18.220Z","dependency_job_id":"a9bb0d38-4fc8-4d51-9215-c7d6dd5aaeea","html_url":"https://github.com/andrewbrey/mdrb","commit_stats":{"total_commits":96,"total_committers":1,"mean_commits":96.0,"dds":0.0,"last_synced_commit":"27f5f3b4ff31902fdc31a9c2f443dd429d905604"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrey%2Fmdrb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrey%2Fmdrb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrey%2Fmdrb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewbrey%2Fmdrb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewbrey","download_url":"https://codeload.github.com/andrewbrey/mdrb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249771990,"owners_count":21323213,"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":["cli","deno","markdown","runbook"],"created_at":"2024-08-06T22:01:37.817Z","updated_at":"2025-04-19T19:06:29.105Z","avatar_url":"https://github.com/andrewbrey.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","cli"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\t\u003cbr\u003e\n\t\t\u003cimg src=\".github/logo.png\" style=\"aspect-ratio: 1681 / 460; max-width: 500px;\" alt=\"mdrb logo which consists of underlined text spelling out a period followed by the letters m, d, r, and b as well as a small cartoon dinosaur sitting at a computer\"\u003e\n\t\u003cbr\u003e\n\tMarkdown Run Book\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eTurn your Markdown documentation into executable runbooks.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/andrewbrey/mdrb/actions/workflows/ci.yml\"\u003e\n\t\t\u003cimg src=\"https://github.com/andrewbrey/mdrb/workflows/ci/badge.svg\" alt=\"github actions status badge\"\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://jsr.io/@andrewbrey/mdrb\"\u003e\n\t\t\u003cimg src=\"https://jsr.io/badges/@andrewbrey/mdrb\" alt=\"jsr status badge\" /\u003e\n\t\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\n- 🦕 Built with and runs on [Deno](https://deno.land)\n- 🌀 Blend documentation with code execution; bring your `README.md` developer setup to life without losing the\n  narrative format\n- ✅ Execute `TypeScript` and `JavaScript` fenced code blocks as a multi-step \"runbook\"\n- ✨ Automatic availability of [@david/dax](https://jsr.io/@david/dax) within code blocks to simplify cross-platform\n  shell execution\n- ⬇ Works with local and remote Markdown files and even Markdown content piped to `stdin`\n\n## Motivation and How it Works\n\nHow many times have you had to follow along with a set of steps in a `README.md` in order to setup your development\nenvironment to work on a project? Copy-and-Paste-ing from the `README` to your terminal back and forth, hoping you do\neach step correctly and don't miss something gets old; wouldn't it be nice if you could just _execute_ the code in that\n`README`? Well, that's what `mdrb` allows you to do!\n\nWhen provided a Markdown file (or a remote URL that points to one, or pipe the content of one through `stdin`) to\n`mdrb`, it does the following:\n\n1. Extract all of the _fenced_ code blocks which are annotated with a valid `TypeScript` or `JavaScript` language code\n   (`typescript`, `ts`, `javascript`, and `js`)\n1. Pull out the code from each and do a bit of processing to allow it to work seamlessly with `Deno`\n   - for example, references to `import.meta.url` need to be rewritten with the litteral value of the source Markdown\n     file\n1. (_optionally, but by default_) add an import of the bundled version of [dax](https://jsr.io/@david/dax) to the code\n   that will be executed\n   - From the `dax` module the `$` object is exposed automatically to your code blocks, allowing them to transparently\n     reference the functions and features (of which there are many) of `$` - most important of which is the execution of\n     cross-platform shell commands.\n1. Execute the code blocks according to the chosen mode; by default the \"`runbook`\" mode is used, which treats each code\n   block as an isolated script and execution is paused awaiting your confirmation before going on.\n   - \"`isolated`\" mode is the same as \"`runbook`\" mode, except that there is no pause to prompt between each code block.\n     This is the mode used instead of `runbook` for all _piped_ content due to the absence of a `tty`.\n   - \"`single`\" mode concatenates your code blocks together as if they were all a single script and executes the\n     resulting _single_ block. In this mode, your code blocks can depend on each other, but be careful about things like\n     re-declaring variables across code blocks - at runtime, they aren't isolated from each other!\n\n## Installation\n\n```sh\ndeno install --global -Arfn mdrb jsr:@andrewbrey/mdrb\n```\n\n\u003e Note: if you prefer not to bake `--allow-all` permissions (with the `-A` flag) into the installed command, you can\n\u003e specify alternate permissions, e.g. `deno install --global --allow-net -rfn mdrb jsr:@andrewbrey/mdrb` but be aware\n\u003e that this means you will be prompted for permissions at runtime.\n\n## Demos\n\n### Local Markdown\n\n\u003e Within the source repository for `mdrb`, execute `mdrb` on the local [demo.md file](demo.md). This results in\n\u003e executing the 3 included (`ts/js`) code blocks as a \"runbook\", pausing execution after each step awaiting user\n\u003e confirmation to proceed.\n\n\u003cimg src=\".github/demos/usage-basic/demo.gif\" alt=\"demonstration of using mdrb to execute the demo markdown file included in the source repository\"\u003e\n\n### Remote Markdown\n\n\u003e Just like when we referenced the local `demo.md` file, we can also just reference the demo Markdown by a URL.\n\n🧪 Try it yourself with:\n\n```sh\nmdrb https://raw.githubusercontent.com/andrewbrey/mdrb/refs/heads/main/demo.md\n```\n\n\u003cimg src=\".github/demos/usage-remote/demo.gif\" alt=\"demonstration of using mdrb to execute the demo markdown file referenced by its URL\"\u003e\n\n\u003e Note that in this demo, we used \"`isolated`\" mode instead of the default \"`runbook`\" mode which omits the pauses for\n\u003e confirmation between code blocks\n\n### Piped Markdown\n\n\u003e We can also pipe the Markdown content to `mdrb`\n\n\u003cimg src=\".github/demos/usage-remote-pipe/demo.gif\" alt=\"demonstration of using mdrb to execute the demo markdown file referenced by its URL and piping the content via standard input\"\u003e\n\n\u003e Note that for this demo, even though we didn't manually specify \"`isolated`\" mode, `mdrb` used it instead of the\n\u003e normal default of \"`runbook`\" mode because the prompts will fail if we don't have a `tty`\n\n### Using `dax`\n\n\u003e There are a **ton** of useful things you can do with `dax`, so here's a little showcase of _some_ of what you can do\n\u003e with the automatically added `$` object.\n\n\u003cimg src=\".github/demos/usage-dax/demo.gif\" alt=\"demonstration of using the automatically included dollar object within markdown code blocks\"\u003e\n\n### Skipping automatic `dax` addition\n\n\u003e If you don't want `dax` to be automatically added to your code blocks, you can pass the `--dax=false` option\n\n\u003cimg src=\".github/demos/usage-no-dax/demo.gif\" alt=\"demonstration of the fact that you can pass dax equals false to the mdrb command line and the dollar object will not be added\"\u003e\n\n### Step Configuration\n\nIt is possible to (_optionally_) configure your code blocks using an HTML `\u003cdetails data-mdrb\u003e` element which comes\nimmediately before your code blocks. Each `ts / js` fenced code block can have its own configuration (though one is not\nrequired). The contents of your code block configuration can change aspects of how `mdrb` will execute.\n\nBy providing configuration within a preceding `\u003cdetails data-mdrb\u003e` element, most places where Markdown is rendered will\ndisplay the configuration information natively as a collapsed dropdown.\n\nThe configuration syntax supports two features within a `\u003cdetails data-mdrb\u003e` element:\n\n- a value which specifies a \"step name / title\", and this is provided as the `\u003csummary\u003e` element directly inside of the\n  `\u003cdetails data-mdrb\u003e`.\n- a value which is [TOML](https://toml.io/) formatted configuration placed inside of a `\u003cpre\u003e` element below the\n  `\u003csummary\u003e` element.\n  \u003e **Warning** the `\u003cpre\u003e` _must have_ a newline before it (a blank line between the `\u003csummary\u003e` and the `\u003cpre\u003e`) and\n  \u003e its content _must not be_ indented (otherwise the Markdown parser will classify the content as an \"indented code\n  \u003e block\" which is another feature of Markdown)\n\nIf you include the `\u003cdetails data-mdrb\u003e` element for step configuration (again, it's optional), you may specify within\nit both a `\u003csummary\u003e` and a `\u003cpre\u003e`, only a `\u003csummary\u003e`, only a `\u003cpre\u003e`, or neither. Basically, everything about this\nstep configuration is optional and `mdrb` will use default values in the absence of user-provided configuration\noverrides.\n\n#### Important Notes About Configuration\n\nHere is an example of a valid, and configured, step:\n\n````md\n\u003e ... preceding Markdown content\n\n\u003cdetails data-mdrb\u003e\n\u003csummary\u003eLog a diagnostic message\u003c/summary\u003e\n\u003c/details\u003e\n\n```ts\nconsole.log(\"hello from this configured step!\");\n```\n\n\u003e ... the rest of the Markdown\n````\n\nPlease note the following:\n\n- The `\u003cdetails\u003e` element has an attribute of `data-mdrb`, which is required to signal to `mdrb` that this `\u003cdetails\u003e`\n  is meant to configure a code block\n- The `\u003csummary\u003e` element is nested inside of the `\u003cdetails data-mdrb\u003e` element\n\nWith this configuration in place, when executed this Markdown will show (with the first line dimmed in your terminal):\n\n```\nstep 1 of 1 // Log a diagnostic message\n\nhello from this configured step!\n```\n\nHere is an example of a step with a \"full\" configuration:\n\n````md\n\u003e ... preceding Markdown content\n\n\u003cdetails data-mdrb\u003e\n\u003csummary\u003eLog a diagnostic message\u003c/summary\u003e\n\n\u003cpre\u003e\ndescription = '''\n# important step\n\n\u003e I can have blockquotes!\n\nbasic demonstration of the fact that\nyou can log to the console with code\nblocks.\n'''\n\u003c/pre\u003e\n\u003c/details\u003e\n\n```ts\nconsole.log(\"hello from this configured step!\");\n```\n\n\u003e ... the rest of the Markdown\n````\n\nIn this example notice the following:\n\n- The `\u003cpre\u003e` has a blank line before it separating it from the `\u003csummary\u003e`\n- The text content of the `\u003cpre\u003e` is not indented _at all_ and is valid `TOML`\n- This example has a single key-value pair, showing the ability to use multiline `TOML` strings as well as the fact that\n  the `description` key can contain Markdown content\n\nToday, the only key from the `\u003cpre\u003e` which may be used when specified is the `description`. This key can have either a\nsingle-line value or a multi-line value, and further, the value can contain Markdown which will be beautifully rendered\nin the terminal when you use \"`runbook`\" mode _or_ when you use \"`isolated`\" mode with the `--isolated-desc=true` flag.\n\nBeyond the `description` key, no other configuration values are used, even if they are well defined according to these\nrules, however in the future, there may be additions to the way you can configure `mdrb` execution exposed through these\nconfiguration values.\n\nSome possible examples of things which may be included are:\n\n- Skip the automatic addition of `dax` for a given code block\n- Conditionally skip a code block entirely (say, for instance, if you were on Windows or Mac but not on Linux)\n- Your ideas? Make an issue or PR and it will be considered\n\n## Prior Art\n\n- https://github.com/jacobdeichert/mask\n- https://github.com/c4spar/deno-dzx\n- https://github.com/google/zx\n\n## License\n\n[MIT](./LICENSE). Copyright (c) [Andrew Brey](https://andrewbrey.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewbrey%2Fmdrb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewbrey%2Fmdrb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewbrey%2Fmdrb/lists"}