qCode

qCode is an extension for Quarto that adds an interactive Python IDE to your page with the ability to run code directly in the browser, as well as search documentation for Python functions and methods.

Add the extension to your Quarto project:

quarto add skyfroger/qcode

After installation, connect the qcode filter in the YAML header of the document or in the project's _quarto.yml.

To localize the extension's UI elements, specify the lang attribute in YAML. English is used by default. Russian is also available:

lang: ru

To make a Python code block interactive, use sk-python as the code block type:

```sk-python
for letter in "Hello, world":
    print(letter)
```

Code inside such a block will be placed into an interactive development environment with support for:

• Code execution - running Python scripts in the browser via Pyodide.
• Data input - interactive input() directly in the output window.
• Syntax highlighting - editor based on Ace Editor.
• Function detection - automatic AST analysis to detect function calls from the documentation.
• Execution stop - interruption of infinite loops and long computations.

Each editor contains buttons:

Button	Purpose
	Run code
	Stop execution
	Clear execution results
	Restore original code
	Copy code to clipboard
	Save code to file script.py

The current status is displayed in the upper right corner of the editor:

Status	Description
Ready	Editor is loaded and ready
Running	Code is being executed
Waiting for input	Script is waiting for user input
Error	An error occurred during execution
Finished	Script executed without errors
Stopped	Execution was interrupted by user

Below the editor, a list of functions and methods detected in the code is displayed. Clicking any function opens a modal window with its documentation.

To add a documentation search field for Python, use a block with the .sk-api-search class:

:::{.sk-api-search}
The documentation contains standard Python language functions and built-in type methods.
:::

Search works in real-time mode (with 300 ms debounce). Results are displayed in a dropdown list. Clicking a result opens a modal window with detailed function documentation.

The modal window contains:

• Function signature - name, parameters, and return type.
• Black box diagram - visualization of input parameters and output value.
• Description - textual description of the function.
• Parameters - list of parameters with types, default values, and descriptions.
• Return value - type and description of the result.
• Examples - usage examples with input code and expected output.
• Link to official documentation.

The modal window has toggles:

Toggle	Description
	Show/hide optional parameters
	Show/hide type hints
	Show/hide black box diagram

Settings are saved to localStorage and apply to all modal windows.

1. Filter in YAML. Don't forget to add filters: - qcode to the document header.
2. Multiple editors. A page can contain multiple sk-python blocks - each gets its own editor with an independent execution environment.
3. Interrupting execution. To stop an infinite loop, use the "Stop" button (if the browser supports SharedArrayBuffer).
4. Security. Code runs in an isolated Pyodide environment inside the browser, without access to the user's file system.

The following third-party libraries and modules were used in the development of the extension:

• Alpine.js for UI reactivity. MIT license.
• Ace for embedding the code editor. BSD License.
• Pyodide for running Python code in the browser. MPL-2.0 License.
• Prism for syntax highlighting outside of the Ace editor. MIT License.
• prism-theme-github - GitHub theme for Prism. MIT License.
• Fuse.js for searching interactive documentation.
• lua-tinyyaml for parsing yaml files with programming language documentation.

The extension's functionality and appearance were inspired by the following projects:

• naquiz extension for Quarto - the idea of ​​using Alpine.js for interface reactivity.
• pyodide extension for Quarto - the idea of ​​using pyodide for code execution. The first version of my extension used the Skulpt library.
• PyTamaro - the idea of ​​interactive documentation in the IDE. The editor displays a list of standard functions used in the code. The idea of ​​choosing the level of documentation detail was also taken from this project: diagrams, optional parameters, and data types.