mdcoderunner 1.0.0

A tool for running code blocks in Markdown files.

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

• 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 that you have python3, pip, and g++ installed. If not, follow the instructions below for your platform:

On macOS:

1. Install Homebrew (if you don’t have it):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Install python3 and g++:

   brew install python
   brew install gcc
   

3. Install pip (if not already installed):

   python3 -m ensurepip --upgrade
   

On Linux (Debian/Ubuntu):

1. Update package lists:

   sudo apt-get update
   

2. Install python3, pip, and g++:

   sudo apt-get install -y python3 python3-pip g++
   

On Windows Subsystem for Linux (WSL):

1. Update package lists:

   sudo apt-get update
   

2. Install python3, pip, and g++:

   sudo apt-get install -y python3 python3-pip g++
   

2. Install the Markdown Code Runner Package

After installing the dependencies, install the Markdown Code Runner package via pip:

pip install mdcoderunner

3. Configure Paths

You may need to specify the paths for python3 and g++ in the configuration:

1. Edit config.py (located in the package directory) to specify the paths:

   # config.py
   
   PYTHON_LOCATION = 'python3'  # Adjust this path if necessary
   GPP_LOCATION = 'g++'          # Adjust this path if necessary
   

   • Replace the paths with the correct locations of python3 and g++ on your system.
   • On macOS and Linux, you can typically find the paths using which python3 and which 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

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:

mdcoderunner ./assets/hello_world.md ./assets/hello_world_rendered.md

mdcoderunner ./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.