Metadata-Version: 2.1
Name: mkdocs-pyscript
Version: 0.0.5
Summary: Add PyScript to your mkdocs site
Home-page: https://github.com/jeffersglass/mkdocs-pyscript
Author: Jeff Glass
Author-email: mail@jeff.glass
License: APACHE
Keywords: mkdocs,pyscript
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs >=1.4.0
Requires-Dist: beautifulsoup4 >=4.1

# mkdocs-pyscript
`mkdocs-pyscript` is a plugin for [mkdocs](https://mkdocs.org/) that allows you to transform [code blocks](https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks) into executable Python scripts that run in the user's browser, with no backend server, using [PyScript](https://github.com/pyscript/pyscript).

## Installation

Install the plugin into your environment using `pip`, or your favorite environment manager that ues PYPI:

```sh
pip3 install mkdocs-pyscript
```

Enable the plugin by adding it to `mkdocs.yaml`:

```
plugins:
    - mkdocs-pyscript
```

## Usage

With this plugin enabled, all Python [fenced code blocks](https://www.mkdocs.org/user-guide/writing-your-docs/#fenced-code-blocks) (type `py` or `python` or any other label that maps to `lang-python`) will have an added LOAD button in the lower-right corrner. When clicked, the code block will be transformed into an editable code snippet (using [codemirror](https://codemirror.net/)). When the user clicks on the green "run" arrow in the lower right corner, or pressed SHIFT+ENTER when focused, will run the inner Python code using PyScript.

The included code is run in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), so as not to block the main thread. Each snippet is run in a separate web worker; variables, objects, and names are not shared between executions of the same cell.

## Configuration

`mkdocs-pyscript` supports  options that can be set in `mkdocs.yaml` to control the behavior of the plugin

### `pyscript_version`

The `pyscript_version` property of the plugin controls the version of PyScript that is loaded. If not specified, the current default version is `snapshots/2023.09.1.RC2`.


To support both pre-release snapshots and released versions of PyScript, the provided value is inserted into the following string:

```py
SCRIPT = f'https://pyscript.net/{pyscript_version}/core.js'
```

That is, to load a specific release or snapshot, use:
```yaml
#Load a release
plugins:
    - mkdocs-pyscript:
        pyscript_version: "releases/2023.10.1"

#Load a snapshot
plugins:
    - mkdocs-pyscript:
        pyscript_version: "snapshots/2023.09.1.RC2"

#Load the most recent (unstable) build:
plugins:
    - mkdocs-pyscript:
        pyscript_version: "unstable"
```

### `selective`

By default, `mkdocs-pyscript` turns *all* blocks with type `py` or `python` into exectuable code snippets. To cause only selected blocks to be transformed:

  1. Set the `selective` property to `true`:
```yaml
plugins:
    - mkdocs-pyscript:
        selective: true
```
  2. Specify `.pyscript` as an additional class for the codeblocks that you want to be runnable:

````py
```{.py .pyscript}
print("Hello, world!")
```
````
