# Plaque
A local-first notebook system for Python, inspired by
[Clerk](https://clerk.vision/) for Clojure. Plaque turns regular Python files
into interactive notebooks with real-time updates and smart dependency
tracking.
## Features
- **Local-first**: Uses plain Python files as the source - and your own editor - no special file formats
- **Live Updates**: Browser preview updates in real-time as you edit
- **Rich Output**: Supports Markdown, LaTeX equations, plots, DataFrames, and more
- **Flexible Format**: Supports both `# %%` markers and multiline comments for cells
- **Python-native**: Use standard Python syntax for both code and documentation
## Principles
Many systems support reactive notebooks, like [clerk](https://clerk.vision/),
[marimo](https://marimo.io/),
[observable](https://observablehq.com/framework/),
[pluto](https://plutojl.org/), etc. Plaque is meant to be a simple thing that
provides 80% of the utility with a very simple package. The core idea is that
your files should only run as they would if you ran them from scratch from top
to bottom, but we don't actually have to rerun every cell every time. Instead,
we only ever re-execute any cell you modify and any cells later in the document.
In this way, you can have most of the benefits for reactivity and live
updating, but still get caching and some gaurentee that you don't have to
re-evaluate expensive computations.
## Usage
Plaque supports two different styles for creating notebooks:
### 1. Traditional Cell Markers
Using `# %%` markers, similar to VS Code notebooks:
```python
# Code cell
x = 42
print(f"The answer is {x}")
# %% [markdown]
# # This is a markdown cell
#
# With support for:
# - Lists
# - **Bold text**
# - And more!
# %%
# Another code cell
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
```
### 2. Multiline Comments as Cells
Using Python's multiline strings (`"""` or `'''`) for documentation:
```python
"""
# Getting Started
This notebook demonstrates using multiline comments as markdown cells.
All standard markdown features are supported:
1. **Bold text**
2. *Italic text*
3. Code blocks
4. LaTeX equations: $E = mc^2$
"""
# Code is automatically treated as a code cell
x = 42
print(f"The answer is {x}")
"""
## Data Visualization
Now let's make a plot:
"""
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [1, 4, 9])
plt.show()
"""
The plot shows a quadratic relationship between x and y.
"""
```
Both styles support:
- Markdown formatting with bold, italic, lists, etc.
- LaTeX equations (both inline and display)
- Code syntax highlighting
- Rich output (plots, DataFrames, etc.)
### Guidelines for Multiline Comments
When using multiline comments as cells:
1. Top-level comments become markdown cells
2. Function/method docstrings remain as code
3. You can mix code and documentation freely
4. Both `"""` and `'''` are supported
## Installation
You can install Plaque using either pip or uv:
### Install directly from GitHub
```bash
# Using pip
pip install git+https://github.com/alexalemi/plaque.git
# Using uv (recommended)
uv pip install git+https://github.com/alexalemi/plaque.git
```
### Install from PyPI (coming soon)
```bash
# Using pip
pip install plaque
# Using uv
uv pip install plaque
```
### Local Development
```bash
# Clone the repository
git clone https://github.com/alexalemi/plaque.git
cd plaque
# Install in development mode
uv pip install -e .
# or
pip install -e .
```
### Development Setup with Dependencies
For development work with testing and additional tools:
```bash
# Clone the repository
git clone https://github.com/alexalemi/plaque.git
cd plaque
# Create and activate a virtual environment (optional)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install with development dependencies
uv pip install -e ".[dev]"
# or
pip install -e ".[dev]"
```
## Running a Notebook
To render a notebook:
```bash
# Generate static HTML
plaque render my_notebook.py
# Generate static HTML with custom output path
plaque render my_notebook.py output.html
# Start a live re-render with caching.
plaque watch my_notebook.py
# Start live server with auto-reload
plaque serve my_notebook.py
# Specify a custom port (default is 5000)
plaque serve my_notebook.py --port 8000
# Open browser automatically
plaque serve my_notebook.py --open
```
Raw data
{
"_id": null,
"home_page": null,
"name": "plaque",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "clerk, interactive, jupyter, local-first, markdown, notebook, python",
"author": null,
"author_email": "Alex Alemi <alexalemi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/97/1f/49f3ba1d0c64f1f85f087b84fd4a3783d574053c458f11576194ea3706db/plaque-0.1.0.tar.gz",
"platform": null,
"description": "# Plaque\n\nA local-first notebook system for Python, inspired by\n[Clerk](https://clerk.vision/) for Clojure. Plaque turns regular Python files\ninto interactive notebooks with real-time updates and smart dependency\ntracking.\n\n## Features\n\n- **Local-first**: Uses plain Python files as the source - and your own editor - no special file formats\n- **Live Updates**: Browser preview updates in real-time as you edit\n- **Rich Output**: Supports Markdown, LaTeX equations, plots, DataFrames, and more\n- **Flexible Format**: Supports both `# %%` markers and multiline comments for cells\n- **Python-native**: Use standard Python syntax for both code and documentation\n\n## Principles\n\nMany systems support reactive notebooks, like [clerk](https://clerk.vision/),\n[marimo](https://marimo.io/),\n[observable](https://observablehq.com/framework/),\n[pluto](https://plutojl.org/), etc. Plaque is meant to be a simple thing that\nprovides 80% of the utility with a very simple package. The core idea is that\nyour files should only run as they would if you ran them from scratch from top\nto bottom, but we don't actually have to rerun every cell every time. Instead,\nwe only ever re-execute any cell you modify and any cells later in the document.\n\nIn this way, you can have most of the benefits for reactivity and live\nupdating, but still get caching and some gaurentee that you don't have to\nre-evaluate expensive computations. \n\n## Usage\n\nPlaque supports two different styles for creating notebooks:\n\n### 1. Traditional Cell Markers\n\nUsing `# %%` markers, similar to VS Code notebooks:\n\n```python\n# Code cell\nx = 42\nprint(f\"The answer is {x}\")\n\n# %% [markdown]\n# # This is a markdown cell\n#\n# With support for:\n# - Lists\n# - **Bold text**\n# - And more!\n\n# %%\n# Another code cell\nimport matplotlib.pyplot as plt\nplt.plot([1, 2, 3], [1, 4, 9])\nplt.show()\n```\n\n### 2. Multiline Comments as Cells\n\nUsing Python's multiline strings (`\"\"\"` or `'''`) for documentation:\n\n```python\n\"\"\"\n# Getting Started\n\nThis notebook demonstrates using multiline comments as markdown cells.\nAll standard markdown features are supported:\n\n1. **Bold text**\n2. *Italic text*\n3. Code blocks\n4. LaTeX equations: $E = mc^2$\n\"\"\"\n\n# Code is automatically treated as a code cell\nx = 42\nprint(f\"The answer is {x}\")\n\n\"\"\"\n## Data Visualization\n\nNow let's make a plot:\n\"\"\"\n\nimport matplotlib.pyplot as plt\nplt.plot([1, 2, 3], [1, 4, 9])\nplt.show()\n\n\"\"\"\nThe plot shows a quadratic relationship between x and y.\n\"\"\"\n```\n\nBoth styles support:\n- Markdown formatting with bold, italic, lists, etc.\n- LaTeX equations (both inline and display)\n- Code syntax highlighting\n- Rich output (plots, DataFrames, etc.)\n\n### Guidelines for Multiline Comments\n\nWhen using multiline comments as cells:\n1. Top-level comments become markdown cells\n2. Function/method docstrings remain as code\n3. You can mix code and documentation freely\n4. Both `\"\"\"` and `'''` are supported\n\n## Installation\n\nYou can install Plaque using either pip or uv:\n\n### Install directly from GitHub\n\n```bash\n# Using pip\npip install git+https://github.com/alexalemi/plaque.git\n\n# Using uv (recommended)\nuv pip install git+https://github.com/alexalemi/plaque.git\n```\n\n### Install from PyPI (coming soon)\n\n```bash\n# Using pip\npip install plaque\n\n# Using uv\nuv pip install plaque\n```\n\n### Local Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/alexalemi/plaque.git\ncd plaque\n\n# Install in development mode\nuv pip install -e .\n# or\npip install -e .\n```\n\n### Development Setup with Dependencies\n\nFor development work with testing and additional tools:\n\n```bash\n# Clone the repository\ngit clone https://github.com/alexalemi/plaque.git\ncd plaque\n\n# Create and activate a virtual environment (optional)\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install with development dependencies\nuv pip install -e \".[dev]\"\n# or\npip install -e \".[dev]\"\n```\n\n## Running a Notebook\n\nTo render a notebook:\n\n```bash\n# Generate static HTML\nplaque render my_notebook.py\n\n# Generate static HTML with custom output path\nplaque render my_notebook.py output.html\n\n# Start a live re-render with caching.\nplaque watch my_notebook.py\n\n# Start live server with auto-reload\nplaque serve my_notebook.py\n\n# Specify a custom port (default is 5000)\nplaque serve my_notebook.py --port 8000\n\n# Open browser automatically\nplaque serve my_notebook.py --open\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A local-first notebook system for Python, inspired by Clerk for Clojure",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/alexalemi/plaque#readme",
"Homepage": "https://github.com/alexalemi/plaque",
"Issues": "https://github.com/alexalemi/plaque/issues",
"Repository": "https://github.com/alexalemi/plaque"
},
"split_keywords": [
"clerk",
" interactive",
" jupyter",
" local-first",
" markdown",
" notebook",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18bdca51c3e5996a82c9c3c933c21892ca9f3059e164753db9f5dafd5acbf47e",
"md5": "81c38366f42c5902eb9fc556d8786ce4",
"sha256": "5c252d569cb59d6ae90d293dbc32253cf44a47b709290f801494a9dfffc0421a"
},
"downloads": -1,
"filename": "plaque-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81c38366f42c5902eb9fc556d8786ce4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 24208,
"upload_time": "2025-07-15T22:40:56",
"upload_time_iso_8601": "2025-07-15T22:40:56.318564Z",
"url": "https://files.pythonhosted.org/packages/18/bd/ca51c3e5996a82c9c3c933c21892ca9f3059e164753db9f5dafd5acbf47e/plaque-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "971f49f3ba1d0c64f1f85f087b84fd4a3783d574053c458f11576194ea3706db",
"md5": "56558650703c18c98cd7d621bb984377",
"sha256": "8a9e1fec3436b060eef595da7f8a3dedcb7f76534e3223967b57f744c36f0447"
},
"downloads": -1,
"filename": "plaque-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "56558650703c18c98cd7d621bb984377",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 147849,
"upload_time": "2025-07-15T22:40:57",
"upload_time_iso_8601": "2025-07-15T22:40:57.451214Z",
"url": "https://files.pythonhosted.org/packages/97/1f/49f3ba1d0c64f1f85f087b84fd4a3783d574053c458f11576194ea3706db/plaque-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 22:40:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexalemi",
"github_project": "plaque#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "plaque"
}
JSON
