| Name | runmd JSON |
| Version |
0.14.0
JSON |
| download |
| home_page | None |
| Summary | A CLI tool to run or list code blocks from Markdown files. |
| upload_time | 2024-10-19 07:25:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<a href="">
<img alt="RunMD Logo" src="./docs/static/runmd.svg" height="128" />
</a>
<h3 align="center">A CLI Tool for Executing Code Blocks in Markdown Files.</h3></br>
</p>
RunMD is a command-line tool designed to extract and execute code blocks from Markdown files. It's particularly useful for managing and running code snippets embedded in documentation or notes.
> **⚠** RunMD is intended for use with scripting languages only (e.g., Shell, Python, Ruby, JavaScript). It does not support compiled languages (e.g., C, C++, Java) as it cannot handle compilation and execution steps.
>
> **⚠** RunMD is different from interactive notebooks like [Jupyter](https://jupyter.org/) or [Zepplin](https://zeppelin.apache.org/). Each code block is independent and executed separately.
## Prerequisites
Before you begin, ensure you have the following installed:
- Python 3.9 or later
- pip (Python package installer)
- Git (for cloning the repository)
## Installation
### From Python Package Index
```console
pip install runmd
```
### From GitHub release
```console
pip install git+https://github.com/PageotD/runmd@0.10.1
```
### From source
Clone the GitHub repository:
```console
git clone https://github.com/PageotD/runmd.git
cd runmd
```
Install Build and Wheel Dependencies:
```console
pip install build wheel
```
Build and Install RunMD
```console
python -m build
pip install dist/runmd-<version>-py3-none-any.whl
```
## Initialize
```console
runmd init
```
## Usage
### Synopsis
```bash
runmd [COMMAND] [OPTIONS]
```
### Commands
**`RUN`**
Executes specified code blocks in a Markdown file.
```bash
runmd run [blockname] [--tag TAG] [--file FILE] [--env VAR=value ...]
```
* `blockname`: The name of the code block to run, or "all" to run all blocks.
* `-t [TAG], --tag [TAG]`: Specify the tag of the code blocks to run.
* `-f [FILE], --file [FILE]`: Specify the path to the Markdown file containing the code blocks.
* `--env VAR=value ...`: Optional environment variables to set during the execution.
</br>
**`SHOW`**
Displays the content of a specified code block.
```bash
runmd show [blockname] [--file FILE]
```
* `blockname`: The name of the code block to display.
* `-f [FILE], --file [FILE]`: Specify the path to the Markdown file.
</br>
**`LIST`**
Lists all the code blocks in a Markdown file.
```bash
runmd list [tag] [--file FILE]
```
* `-t [TAG], --tag [TAG]`: Optional tag to filter the list of code blocks.
* `-f [FILE], --file [FILE]`: Specify the path to the Markdown file.
</br>
**`HIST`**
Displays or clears the history of runmd commands.
```bash
runmd hist [id] [--clear]
```
* `id`: command line entry in history to execute.
* `--clear`: Clears definitely all the command line entries in history.
**`VAULT`**
Encrypt/Decrypt a markdown file using a password.
```console
runmd vault --encrypt README.md --outfile README.enc
```
```console
runmd vault --decrypt README.enc --outfile README.dec
```
* `-e [FILE], --encrypt [FILE]`: Encrypt the specified markdown file.
* `-d [FILE], --decrypt [FILE]`: Decrypt the encrypted file.
* `-o [FILE], --outfile [FILE]`: Optional output file name (default: add `.vault` suffix to input file name).
</br>
### Other options
Other options are quite standard:
* **`--help`**: to show the help message
* **`--version`**: to get the installed version of runmd
Display the version of
### Add executable code block
To add an executable code block to your Markdown file, use the following syntax:
```markdown
# My executable code block
```sh {name=export-echo,tag=example}
EXPORT MYSTR="a simple export and echo"
echo $MYSTR
```
```
### List Code Blocks
To list all code block names in Markdown files within the current directory:
```console
runmd list
```
### Show a Specific Code Block
To display the content of a specific code block:
```console
runmd show <code-block-name>
```
### Run a Specific Code Block
To execute a specific code block by name:
```console
runmd run <code-block-name>
```
### Run all code blocks with a given tag
To execute a specific code block by name:
```console
runmd run -t <tag>
```
### Run all code blocks
To execute a specific code block by name:
```console
runmd run all
```
### Run a Specific Code Block with nvironment variable
To execute a specific code block by name:
```console
runmd run <code-block-name> --env <KEY1>=<VALUE1> <KEY2=VALUE2>
```
### Run all code blocks
To execute all code blocks in Markdown files within the current directory:
```console
runmd run all
```
## Configuration
You can customize how different scripting languages are executed by creating a configuration file at ~/.config/runmd/config.json. Here’s an example configuration:
```json
{
"sh": {
"command": "bash",
"options": ["-c"]
},
"python": {
"command": "python",
"options": []
},
"ruby": {
"command": "ruby",
"options": []
}
}
```
## Troubleshooting
* **No Output**: Ensure the Markdown code blocks are correctly formatted and the specified commands are valid for the environment.
* **Permission Denied**: Check if you have the required permissions to execute the commands in the code blocks.
Raw data
{
"_id": null,
"home_page": null,
"name": "runmd",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Damien Pageot <damien.pageot+runmd@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cf/1f/1e1d17cf740c2cae9316ddab61b75304e8b76b45d45eb621647901df3c60/runmd-0.14.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"\">\n <img alt=\"RunMD Logo\" src=\"./docs/static/runmd.svg\" height=\"128\" />\n </a>\n <h3 align=\"center\">A CLI Tool for Executing Code Blocks in Markdown Files.</h3></br>\n</p>\n\n\nRunMD is a command-line tool designed to extract and execute code blocks from Markdown files. It's particularly useful for managing and running code snippets embedded in documentation or notes.\n\n> **\u26a0** RunMD is intended for use with scripting languages only (e.g., Shell, Python, Ruby, JavaScript). It does not support compiled languages (e.g., C, C++, Java) as it cannot handle compilation and execution steps.\n>\n> **\u26a0** RunMD is different from interactive notebooks like [Jupyter](https://jupyter.org/) or [Zepplin](https://zeppelin.apache.org/). Each code block is independent and executed separately.\n\n## Prerequisites\n\nBefore you begin, ensure you have the following installed:\n- Python 3.9 or later\n- pip (Python package installer)\n- Git (for cloning the repository)\n\n## Installation\n\n### From Python Package Index\n```console\npip install runmd\n```\n\n### From GitHub release\n\n```console\npip install git+https://github.com/PageotD/runmd@0.10.1\n```\n\n### From source\n\nClone the GitHub repository:\n\n```console\ngit clone https://github.com/PageotD/runmd.git\ncd runmd\n```\n\nInstall Build and Wheel Dependencies:\n```console\npip install build wheel\n```\n\nBuild and Install RunMD\n```console\npython -m build\npip install dist/runmd-<version>-py3-none-any.whl\n```\n\n## Initialize\n```console\nrunmd init\n```\n\n## Usage\n\n### Synopsis\n\n```bash\nrunmd [COMMAND] [OPTIONS]\n```\n\n### Commands\n\n**`RUN`**\n\nExecutes specified code blocks in a Markdown file.\n```bash\nrunmd run [blockname] [--tag TAG] [--file FILE] [--env VAR=value ...]\n```\n* `blockname`: The name of the code block to run, or \"all\" to run all blocks.\n* `-t [TAG], --tag [TAG]`: Specify the tag of the code blocks to run.\n* `-f [FILE], --file [FILE]`: Specify the path to the Markdown file containing the code blocks.\n* `--env VAR=value ...`: Optional environment variables to set during the execution.\n\n</br>\n\n**`SHOW`**\n\nDisplays the content of a specified code block.\n\n```bash\nrunmd show [blockname] [--file FILE]\n```\n\n* `blockname`: The name of the code block to display.\n* `-f [FILE], --file [FILE]`: Specify the path to the Markdown file.\n\n</br>\n\n**`LIST`**\n\nLists all the code blocks in a Markdown file.\n\n```bash\nrunmd list [tag] [--file FILE]\n```\n\n* `-t [TAG], --tag [TAG]`: Optional tag to filter the list of code blocks.\n* `-f [FILE], --file [FILE]`: Specify the path to the Markdown file.\n\n</br>\n\n**`HIST`**\n\nDisplays or clears the history of runmd commands.\n\n```bash\nrunmd hist [id] [--clear]\n```\n\n* `id`: command line entry in history to execute.\n* `--clear`: Clears definitely all the command line entries in history.\n\n**`VAULT`**\n\nEncrypt/Decrypt a markdown file using a password.\n\n```console\nrunmd vault --encrypt README.md --outfile README.enc\n```\n\n```console\nrunmd vault --decrypt README.enc --outfile README.dec\n```\n\n* `-e [FILE], --encrypt [FILE]`: Encrypt the specified markdown file.\n* `-d [FILE], --decrypt [FILE]`: Decrypt the encrypted file.\n* `-o [FILE], --outfile [FILE]`: Optional output file name (default: add `.vault` suffix to input file name).\n\n</br>\n\n### Other options\n\nOther options are quite standard:\n* **`--help`**: to show the help message\n* **`--version`**: to get the installed version of runmd\n\nDisplay the version of \n### Add executable code block\n\nTo add an executable code block to your Markdown file, use the following syntax:\n\n```markdown\n# My executable code block\n ```sh {name=export-echo,tag=example}\n EXPORT MYSTR=\"a simple export and echo\"\n echo $MYSTR\n ```\n```\n\n### List Code Blocks\n\nTo list all code block names in Markdown files within the current directory:\n\n```console\nrunmd list\n```\n\n### Show a Specific Code Block\nTo display the content of a specific code block:\n\n```console\nrunmd show <code-block-name>\n```\n\n### Run a Specific Code Block\n\nTo execute a specific code block by name:\n\n```console\nrunmd run <code-block-name>\n```\n\n### Run all code blocks with a given tag\n\nTo execute a specific code block by name:\n\n```console\nrunmd run -t <tag>\n```\n\n### Run all code blocks\n\nTo execute a specific code block by name:\n\n```console\nrunmd run all\n```\n\n### Run a Specific Code Block with nvironment variable\n\nTo execute a specific code block by name:\n\n```console\nrunmd run <code-block-name> --env <KEY1>=<VALUE1> <KEY2=VALUE2>\n```\n\n### Run all code blocks\n\nTo execute all code blocks in Markdown files within the current directory:\n\n```console\nrunmd run all\n```\n\n## Configuration\n\nYou can customize how different scripting languages are executed by creating a configuration file at ~/.config/runmd/config.json. Here\u2019s an example configuration:\n\n```json\n{\n \"sh\": {\n \"command\": \"bash\",\n \"options\": [\"-c\"]\n },\n \"python\": {\n \"command\": \"python\",\n \"options\": []\n },\n \"ruby\": {\n \"command\": \"ruby\",\n \"options\": []\n }\n}\n```\n\n## Troubleshooting\n\n* **No Output**: Ensure the Markdown code blocks are correctly formatted and the specified commands are valid for the environment.\n* **Permission Denied**: Check if you have the required permissions to execute the commands in the code blocks.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI tool to run or list code blocks from Markdown files.",
"version": "0.14.0",
"project_urls": {
"Homepage": "https://github.com/pageotd/runmd"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a48f49e27b70c5fa8c4f192053e3e197a6e2bded50d66ac4c5f86f97f67bac0",
"md5": "59913ad5ce3e3bc72a5c8a3c68f4dc05",
"sha256": "4304aac719767aff4e804e656185f42977055cc66ee018dfda33346f5bf3cc71"
},
"downloads": -1,
"filename": "runmd-0.14.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59913ad5ce3e3bc72a5c8a3c68f4dc05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22174,
"upload_time": "2024-10-19T07:25:49",
"upload_time_iso_8601": "2024-10-19T07:25:49.736442Z",
"url": "https://files.pythonhosted.org/packages/9a/48/f49e27b70c5fa8c4f192053e3e197a6e2bded50d66ac4c5f86f97f67bac0/runmd-0.14.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cf1f1e1d17cf740c2cae9316ddab61b75304e8b76b45d45eb621647901df3c60",
"md5": "28e859511a1a9a05ad7a614494afa7dd",
"sha256": "73c2ab5c45df900d8bc84bab917b04cbc55647932356f6fb329ac3e1dcfbfffc"
},
"downloads": -1,
"filename": "runmd-0.14.0.tar.gz",
"has_sig": false,
"md5_digest": "28e859511a1a9a05ad7a614494afa7dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25261,
"upload_time": "2024-10-19T07:25:51",
"upload_time_iso_8601": "2024-10-19T07:25:51.388634Z",
"url": "https://files.pythonhosted.org/packages/cf/1f/1e1d17cf740c2cae9316ddab61b75304e8b76b45d45eb621647901df3c60/runmd-0.14.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-19 07:25:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pageotd",
"github_project": "runmd",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "runmd"
}
