Code-Runner Automation

The notebook (ipynb) to web (html) conversion system automatically generates a “code-runner” web experience from code cells.

JavaScript Code Cells

  • %%js: required for code cell testing
  • JavaScript/Java: // CODE_RUNNER: <challenge text>

Code Runner Challenge

Personalize your student record.

View IPYNB Source 
%%js

// CODE_RUNNER: Personalize your student record.

// Simple person object with key-value pairs
const person = {
    name: "Jane",
    age: 16
};
console.log(person);
Lines: 1 Characters: 0
Output
Click "Run" in code control panel to see output ...

Practical Example: Fix the Syntax Error

Here’s a lesson example to fix a syntax error.

Code Runner Challenge

Fix the syntax errors. Run the code to get a hint!

View IPYNB Source 
%%js

// CODE_RUNNER: Fix the syntax errors. Run the code to get a hint!

console.log(Office hours 10-10:30))
Lines: 1 Characters: 0
Output
Click "Run" in code control panel to see output ...

Practical Example: JavaScript Loop

A JavaScript example where students complete a loop.

Code Runner Challenge

Complete the for loop to print numbers 1 through 5. Fill in the missing parts of the loop.

View IPYNB Source 
%%js

// CODE_RUNNER: Complete the for loop to print numbers 1 through 5. Fill in the missing parts of the loop.

// Complete the for loop
for (let i = ???; i <= ???; i++) {
  console.log(i);
}
Lines: 1 Characters: 0
Output
Click "Run" in code control panel to see output ...

Build Process

When you run make or the notebook conversion script:

  1. The script detects CODE_RUNNER comments in code cells
  2. Extracts the challenge text from the comment
  3. Generates a unique runner_id based on the permalink + index
  4. Strips magic commands (%%js, %%python) and CODE_RUNNER comments from the code
  5. Clears Jupyter outputs from cells with CODE_RUNNER (since code-runner provides interactive execution)
  6. Injects a code-runner block after the code cell in the generated markdown

Testing Notebooks

  • In Notebook: Run cells normally, see outputs using Help-Toggle Developer Tools
  • On Website: Viewers can modify, run code, and view outputs localhost and deployed
  • No Duplication: Code exists is in both places, but only requires development in notebook (IPYNB)

Migrating Notebooks

If you have existing IPYNB lessons with code cell that only run in VSCode:

  • You will need to enable your repo for Code Runner support
  • Add to frontmatter of the page codemirror: true
  • Add a comment to the top of desired code-runner cell // CODE_RUNNER: <challenge text>
  • Run make, view, and test on localhost
  • Commit the change to production

The system will automatically generate the code-runner blocks in the page that enable interaction on the Web.