Metadata-Version: 2.1
Name: mdcoderunner
Version: 0.3.2
Summary: A tool for running code blocks in Markdown files.
Home-page: https://github.com/SivaSankarS365/Markdown-code-runner
Author: Siva Sankar Sajeev
Author-email: sivasankars365@gmail.com
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# Markdown Code Runner

Markdown Code Runner is a tool designed for processing Markdown files with executable code blocks. It automatically executes these blocks and inserts the output into the Markdown file, making it ideal for note-taking and documentation purposes. This tool supports custom inputs, runtime measurement, and caching mechanisms.

## Features

![Parse and run code in markdown files](https://github.com/SivaSankarS365/Markdown-code-runner/raw/main/assets/imgs/demo1.png)

![Supports custom predefined inputs or inputs from stdio](https://github.com/SivaSankarS365/Markdown-code-runner/raw/main/assets/imgs/demo2.png)

![Supports runtime measurement](https://github.com/SivaSankarS365/Markdown-code-runner/raw/main/assets/imgs/timeit.jpeg)

- **Execute Code Blocks**: Automatically runs code within Markdown files and inserts the output.
- **Custom Inputs**: Supports predefined inputs or inputs from standard I/O.
- **Runtime Measurement**: Measures and displays runtime statistics for code blocks.
- **Cache Control**: Allows selective caching of outputs to avoid rerunning code blocks unnecessarily.

## Installation

Markdown Code Runner supports macOS, Linux, and Windows Subsystem for Linux (WSL).

1. **Install Dependencies**:

   - Ensure you have `python3` and `g++` installed.
   - Install Python dependencies:

     ```bash
     pip install -r requirements.txt
     ```
2. **Configure Paths**:

   - Edit `config.py` to specify the paths for `python3` and `g++`.

## Definitions

### Code Blocks

A code block in Markdown Code Runner consists of three components: code, input, and output.

#### Example Code Block

````
<codeStart/>

```python
a = input()
print("hello world", a)
```

```input
Siva
```

```output
hello world Siva
```

<codeEnd/>
````

### Special Elements

- **`<codeStart/>`**: Marks the beginning of a code block.
- **`<codeEnd/>`**: Marks the end of a code block.

#### Skipping Code Blocks

To skip a code block during execution, add the `skip` class:

```
<codeStart class="skip"/>
...
<codeEnd/>
```

#### Avoiding Cache

To force a code block to rerun every time without caching the output, use the `nocache` class:

```
<codeStart class="nocache"/>
...
<codeEnd/>
```

#### Runtime Measurement

To measure runtime statistics for a code block, use the `timeit` class in conjunction with `nocache`:

```
<codeStart class="timeit nocache"/>
...
<codeEnd/>
```

## Usage

```bash
usage: mdcoderunner.py [-h] [--clear-outputs] [--create-code-tags] [--clear-code-tags] input_path [output_path]

Process a Markdown file with executable code blocks.

positional arguments:
  input_path          Path to the input Markdown file.
  output_path         Path to the output Markdown file (optional). If not provided, the input file will be
                      overwritten.

optional arguments:
  -h, --help          Show this help message and exit.
  --clear-outputs     Clear all code outputs in the Markdown file.
  --create-code-tags  Wrap code blocks in <codeStart/> and <codeEnd/> tags.
  --clear-code-tags   Remove <codeStart/> and <codeEnd/> tags from code blocks.
```

## Example Usage

To process a Markdown file, run the following commands:

```bash
python3 mdcoderunner.py ./assets/hello_world.md ./assets/hello_world_rendered.md
```

```bash
python3 mdcoderunner.py ./assets/demo.md ./assets/demo_rendered.md
```

## Inspiration

Markdown Code Runner was developed as a tool for preparing for technical interviews, particularly for learning Data Structures and Algorithms (DSA). The goal was to create a lightweight, non-interactive alternative to Jupyter notebooks, enabling seamless note-taking and code execution within Markdown files. This project was built in a single day of focused development.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.
