uvnote 0.2.0

Stateless, deterministic notebooks with uv and Markdown

uvnote

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

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
• 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.

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

outputs

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