Metadata-Version: 2.4
Name: uvnote
Version: 0.2.0
Summary: Stateless, deterministic notebooks with uv and Markdown
Project-URL: Homepage, https://github.com/drbh/uvnote
Project-URL: Repository, https://github.com/drbh/uvnote
Project-URL: Issues, https://github.com/drbh/uvnote/issues
Author: drbh
License: MIT
Keywords: markdown,notebook,python,reproducible,uv
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: flask>=3.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markdown>=3.5.0
Requires-Dist: pygments>=2.16.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# uvnote

> [!NOTE]
> uvnote is pre v1, so things are subject to change

<img width="2164" height="1392" alt="uvnotescreen" src="https://github.com/user-attachments/assets/5571a2a0-d849-4078-8395-436943d93082" />


`uvnote` is a "Stateless, deterministic notebooks with uv and Markdown."

In other words, its a alternative for Jupyter notebooks that is more lightweight, more reproducible, and more portable.

`uvnote` is kinda like a combination of a Markdown file and a Jupyter notebook and a static site generator.

## Concept

The premise is simple:

- you write normal markdown files with python code blocks
- each code block is expanded to a [uv/PEP 723 script](https://docs.astral.sh/uv/guides/scripts/#running-scripts)
- the output of each script is capture and rendered in the markdown file.
- all data/scripts are hashed and cached (in `.uvnote/cache`) so everything can be inspected and intelligently re-run when needed.
- no magic runtimes (relies on uv)
- no hidden state (cells are not stateful, they are just scripts)
- no special file formats (just plain markdown)

## Cool features

okay, so the core concept is simple (embed uv scripts in markdown), but there are some cool features that make `uvnote` more powerful than just that!

- interactive auto fading drawing tools to help present the note to others in an engaging way
- automatically generate a table of contents/links artifacts for easy navigation
- light/dark mode
- simplify syntax for dependencies (e.g. `deps=numpy,pandas` in code block header will be expanded to the PEP 723 metadata)
- and again NO MAGIC, so if you want to change css or add custom HTML you can easily do that.

## How to use

Currently, the recommended way to use `uvnote` is to directly run the script from GitHub using `uvx`, this will download and run the latest version of `uvnote` without needing to install anything until we have a proper release.

```bash
uvx uvnote
# Latest version
# uvx https://github.com/drbh/uvnote.git
```

outputs

```text
Usage: uvnote [OPTIONS] COMMAND [ARGS]...

  uvnote: Stateless, deterministic notebooks with uv and Markdown.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  build          Build static HTML from markdown file.
  build-loading  Build HTML with loading placeholders for stale cells.
  cache-prune    Prune cache to target size using LRU eviction.
  clean          Clear cache and site files.
  export         Export cell files and their dependencies to a directory.
  graph          Show dependency graph for markdown file.
  run            Run cells from markdown file.
  serve          Watch markdown file, rebuild on changes, and serve HTML...
```

### Preview

> [!NOTE]
> the vscode extension may be deprecated in the future as uvnote as the serve command can be used to serve a live preview.

If you're a `vscode` user, you can use the `uvnote-preview` extension to preview your uvnote files directly in VSCode.

https://github.com/drbh/uvnote-preview


https://github.com/user-attachments/assets/59a470e2-c3f6-46b7-b3ad-b4a0085b8dda


