{"id":13502902,"url":"https://github.com/FauconFan/mdbook-cmdrun","last_synced_at":"2025-03-29T12:33:15.320Z","repository":{"id":45783937,"uuid":"511594156","full_name":"FauconFan/mdbook-cmdrun","owner":"FauconFan","description":"A mdbook preprocessor for runnning arbitrary (shell) commands in a markdown file","archived":false,"fork":false,"pushed_at":"2024-09-08T14:27:06.000Z","size":137,"stargazers_count":32,"open_issues_count":4,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-08T18:42:24.223Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/FauconFan.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-07T16:09:18.000Z","updated_at":"2024-10-03T12:33:38.000Z","dependencies_parsed_at":"2024-01-18T23:25:50.331Z","dependency_job_id":"f88c5be3-794b-418b-b515-6e50db660dbe","html_url":"https://github.com/FauconFan/mdbook-cmdrun","commit_stats":{"total_commits":25,"total_committers":2,"mean_commits":12.5,"dds":"0.040000000000000036","last_synced_commit":"ed334dc1cbc2f933e8e2546819d2e1a3ad446c5f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FauconFan%2Fmdbook-cmdrun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FauconFan%2Fmdbook-cmdrun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FauconFan%2Fmdbook-cmdrun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FauconFan%2Fmdbook-cmdrun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FauconFan","download_url":"https://codeload.github.com/FauconFan/mdbook-cmdrun/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222495265,"owners_count":16993289,"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":[],"created_at":"2024-07-31T22:02:29.242Z","updated_at":"2024-10-31T22:31:00.858Z","avatar_url":"https://github.com/FauconFan.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"[![Workflow Status](https://github.com/FauconFan/mdbook-cmdrun/actions/workflows/main.yml/badge.svg)](https://github.com/FauconFan/mdbook-cmdrun/actions?query=workflow%3A%22main%22)\n![Crates.io](https://img.shields.io/crates/l/mdbook-cmdrun)\n\n# mdbook-cmdrun\n\nThis is a preprocessor for the [rust-lang mdbook](https://github.com/rust-lang/mdBook) project. This allows to run arbitrary (shell) commands and include the output of these commands within the markdown file.\n\n## Getting started\n\n```sh\ncargo install mdbook-cmdrun\n```\n\nYou also have to activate the preprocessor, put this in your `book.toml` file:\n```toml\n[preprocessor.cmdrun]\n```\n\n\u003e :warning: This preprocessor presents a security risk, as arbitrary commands can be run. Be careful with the commands you run.\n\u003e To list all the commands that will be run within an mdbook, you can run the following command:\n\u003e ```sh\n\u003e grep -r '\u003c!-- cmdrun' . | sed 's/.*\u003c!-- cmdrun \\(.*\\) --\u003e.*/\\1/'\n\u003e ``````\n\n\n## How to\n\nLet's say we have these two files:\n\nMarkdown file: file.md\n```markdown\n# Title\n\n\u003c!-- cmdrun seq 1 10 --\u003e\n\n\u003c!-- cmdrun python3 script.py --\u003e\n\n```\n\nPython file: script.py\n```python\ndef main():\n    print(\"## Generated subtitle\")\n    print(\"  This comes from the script.py file\")\n    print(\"  Since I'm in a scripting language,\")\n    print(\"  I can compute whatever I want\")\n\nif __name__ == \"__main__\":\n    main()\n\n```\n\nThe preprocessor will call seq then python3, and will produce the resulting file:\n\n```markdown\n# Title\n\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n\n## Generated subtitle\n  This comes from the script.py file\n  Since I'm in a scripting language,\n  I can compute whatever I want\n\n\n```\n\n## Details\n\nWhen the pattern `\u003c!-- cmdrun $1 --\u003e\\n` or `\u003c!-- cmdrun $1 --\u003e` is encountered, the command `$1` will be run using the shell `sh` like this: `sh -c $1`.\nAlso the working directory is the directory where the pattern was found (not root).\nThe command invoked must take no inputs (stdin is not used), but a list of command lines arguments and must produce output in stdout, stderr is ignored.\n\nAs of July 2023, mdbook-cmdrun runs on Windows platforms using the `cmd` shell!\n\n## Examples\n\nThe following is valid:\n\n````markdown\n\n\u003c!-- cmdrun python3 generate_table.py --\u003e\n\n```rust\n\u003c!-- cmdrun cat program.rs --\u003e\n```\n\n```diff\n\u003c!-- cmdrun diff a.rs b.rs --\u003e\n```\n\n```console\n\u003c!-- cmdrun ls -l . --\u003e\n```\n\n## Example of inline use inside a table\n````markdown\nItem | Price | # In stock\n---|---|---\nJuicy Apples | \u003c!-- cmdrun node price.mjs apples --\u003e | *\u003c!-- cmdrun node quantity.mjs apples  --\u003e*\nBananas | *\u003c!-- cmdrun node price.mjs bananas --\u003e* | \u003c!-- cmdrun node quantity.mjs bananas --\u003e\n````\n\nWhich gets rendered as:\n````markdown\nItem | Price | # In stock\n---|---|---\nJuicy Apples | 1.99 | *7*\nBananas | *1.89* | 5234\n````\n\nSome more examples are implemented, and are used as regression tests. You can find them [here](https://github.com/FauconFan/mdbook-cmdrun/tree/master/tests/regression/).\nAt the moment of writing, there are examples using:\n- Shell\n- Bash script\n- Batch script\n- Python3\n- Node\n- Rust\n\n\n## Contributors\n\nI would like to thank [@exsjabe](https://github.com/exsjabe) for his valuable help with integrating Windows support and inline cmdrun calls.\n\nCurrent version: 0.7.1  \nLicense: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFauconFan%2Fmdbook-cmdrun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFauconFan%2Fmdbook-cmdrun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFauconFan%2Fmdbook-cmdrun/lists"}