Add PyScript to your mkdocs site
Project description
mkdocs-pyscript
mkdocs-pyscript
is a plugin for mkdocs that allows you to transform code blocks into executable Python scripts that run in the user's browser, with no backend server, using PyScript.
Installation
Install the plugin into your environment using pip
, or your favorite environment manager that ues PYPI:
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 (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). 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, 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:
SCRIPT = f'https://pyscript.net/{pyscript_version}/core.js'
That is, to load a specific release or snapshot, use:
#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:
- Set the
selective
property totrue
:
plugins:
- mkdocs-pyscript:
selective: true
- Specify
.pyscript
as an additional class for the codeblocks that you want to be runnable:
```{.py .pyscript}
print("Hello, world!")
```
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs_pyscript-0.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 45f1bd3975f1d6a1063110694dafa4d7f85256e3322ecd5561662e3064a38f18 |
|
MD5 | 6b88b9a9c2024ac0c34c280edd4b4802 |
|
BLAKE2b-256 | 3192c955a8852a3bbd209d17e2a4927712b383a1028225886329d62fe2710c50 |