Skip to content

docs: update readme #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 19 commits into from
Oct 31, 2025
Merged

docs: update readme #49

Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
976da84
docs: update reamde plus placeholder for logo
Yggdrasill501 Oct 25, 2025
2ef77fd
docs: update readme
Yggdrasill501 Oct 30, 2025
422d969
Merge branch 'main' into filipzitny/mar-249-readme-for-deepnotejupyte…
Yggdrasill501 Oct 30, 2025
5adccb1
docs: fix styles and indent
Yggdrasill501 Oct 30, 2025
f393473
fix: lint and format
Yggdrasill501 Oct 30, 2025
3feabf0
fix: lint and format
Yggdrasill501 Oct 30, 2025
4518555
fix: pritier write
Yggdrasill501 Oct 30, 2025
639f0ca
fix: links
Yggdrasill501 Oct 30, 2025
b1b8e9c
docs: update cover image
Yggdrasill501 Oct 30, 2025
9c9a405
docs: docs update
Yggdrasill501 Oct 30, 2025
11751bb
Merge branch 'main' into filipzitny/mar-249-readme-for-deepnotejupyte…
jamesbhobbs Oct 31, 2025
6527f5c
docs: rm mention of 3.9 as it's deprecated today
jamesbhobbs Oct 31, 2025
5ebcd45
docs: revert removal of compatibility section
jamesbhobbs Oct 31, 2025
de12263
docs: rm trademark breaching logo use before merge
jamesbhobbs Oct 31, 2025
c25ed04
docs: add paceholder title while awaiting trademark compliant image
jamesbhobbs Oct 31, 2025
005349a
docs: add missed capital letter
jamesbhobbs Oct 31, 2025
31f767c
chore: prettier write
jamesbhobbs Oct 31, 2025
d66ff66
docs: slight trademark clarification
jamesbhobbs Oct 31, 2025
af79de7
docs: improve wording
jamesbhobbs Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 127 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,57 +1,140 @@
# jupyterlab_deepnote
# JupyterLab Deepnote

<div align="center">

[![CI](https://github.com/deepnote/jupyterlab-deepnote/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/deepnote/jupyterlab-deepnote/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/deepnote/jupyterlab-deepnote/graph/badge.svg?token=OV32VZNOJ2)](https://codecov.io/gh/deepnote/jupyterlab-deepnote)
[![PyPI](https://img.shields.io/pypi/v/jupyterlab-deepnote.svg)](https://pypi.org/project/jupyterlab-deepnote/)
[![Python Version](https://img.shields.io/pypi/pyversions/jupyterlab-deepnote.svg)](https://pypi.org/project/jupyterlab-deepnote/)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

A third-party Deepnote extension for JupyterLab that provides a read‑only viewer for Deepnote `.deepnote` files.
## A third-party extension for JupyterLab for viewing Deepnote projects (`.deepnote` files) directly in JupyterLab

> **Note:** This is an unofficial, community-developed extension and is not affiliated with or endorsed by Project Jupyter. JupyterLab is a trademark of LF Charities, Inc.
> **Note:** This is an unofficial, community-developed extension and is not affiliated with or endorsed by Project Jupyter. Jupyter, JupyterLab and the Jupyter logos are trademarks or registered trademarks of LF Charities, used by Deepnote Inc with permission.

## Requirements
[Installation](#installation) • [Usage](#usage) • [Development](#development) • [License](#license) • [Deepnote](https://deepnote.com) • [GitHub community](https://github.com/deepnote/deepnote)

- Python 3.9 or higher
- JupyterLab >= 4.4.0, < 5.0.0
</div>

## Install
---
Comment on lines +1 to +19
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify image element is present and properly sized in the header.

The header structure looks good—heading on line 1, badges, disclaimer, and navigation all properly placed. However, the provided code diff does not show an <img> tag in the centered div (lines 3–17). Past feedback indicated the image was replaced and resized. Either the image is missing from the diff view or it was inadvertently removed.

Verify the image element is present and confirm it has a max-width style constraint as suggested in prior feedback:

If the image is missing, it should be restored inside the centered <div> with appropriate width constraints.

🏁 Script executed:

#!/bin/bash
# Check if README.md contains an img tag in the header section (first 50 lines)
head -50 README.md | grep -i '<img'
echo "---"
# Also look for any image reference in the full file
grep -i '<img' README.md

Length of output: 115

🏁 Script executed:

#!/bin/bash
# Search for img tags in README.md (any location)
echo "=== Checking for <img> tags in README.md ==="
rg -n '<img' README.md || echo "No <img> tags found"
echo ""
echo "=== First 50 lines of README.md ==="
head -50 README.md

Length of output: 2727

🏁 Script executed:

#!/bin/bash
# Search for img tags in README.md across full file
echo "=== Searching for <img> tags in README.md ==="
rg -n '<img' README.md || echo "No <img> tags found"

echo ""
echo "=== Displaying first 25 lines of README.md ==="
head -25 README.md

echo ""
echo "=== Checking header section (lines 1-20) for any image-related content ==="
head -20 README.md | grep -i 'image\|img\|src\|logo' || echo "No image-related content found in header"

Length of output: 2647

Add missing image element to header.

The header currently has no image element. Every <img> tag search across the file returns nothing. The centered div (lines 3–17) contains only badges and text. If an image was supposed to be restored per prior feedback with a max-width constraint, it needs to be added to the header section.

🤖 Prompt for AI Agents 
In README.md around lines 1 to 19, the header is missing the intended image
element; add an <img> tag inside the centered div (above or beside the badges)
with appropriate alt text and a source (relative path or URL), and apply the
max-width constraint (e.g., style="max-width: 320px;" or a CSS class) so the
image scales correctly; ensure the image tag is HTML-safe for GitHub README and
keep it within the existing centered div so it displays in the header.


Install the extension using pip:
Deepnote is the data notebook for the AI era. `jupyterlab-deepnote` is a JupyterLab extension that enables you to open and view [Deepnote](https://deepnote.com) project files (`.deepnote` format) directly within JupyterLab. This extension provides a seamless read-only viewer for Deepnote notebooks, allowing you to explore Deepnote projects without leaving your JupyterLab environment.

```bash
pip install jupyterlab_deepnote
```
### Key features

## Usage
- 📂 **Open Deepnote files**: View `.deepnote` project files containing Deepnote notebooks in JupyterLab
- 📓 **Multi-notebook support**: Switch between multiple notebooks within a single `.deepnote` file
- 👁️ **Read-only mode**: View notebook content safely without modifying the original `.deepnote` file
- 🔄 **Seamless integration**: Works natively with JupyterLab's notebook interface
- 🎨 **Deepnote block support**: Renders Deepnote-specific block types as Jupyter cells

After installation you can:
## Installation

- Open Deepnote files (`.deepnote`) containing Deepnote projects in JupyterLab
- Switch between notebooks inside a `.deepnote` file
- View content in **read‑only** mode (no editing or saving back to the `.deepnote` file)
### Requirements

## Troubleshooting
- **Python**: 3.10 or higher
- **JupyterLab**: 4.0.0 or higher

If you encounter issues with the extension, verify that both the server and frontend extensions are properly installed and enabled.
### Install via pip

Check server extensions:
Install the extension using pip, see our [PyPI page](https://pypi.org/project/jupyterlab-deepnote/):

```bash
jupyter server extension list
pip install jupyterlab-deepnote
```

Check frontend extensions:
The extension will be automatically enabled after installation.

### Verify installation

Check that the extension is properly installed and enabled:

```bash
# Check server extension
jupyter server extension list

# Check frontend extension
jupyter labextension list
```

You should see `jupyterlab_deepnote` listed in both outputs.

## Usage

### Opening Deepnote files

1. **Launch JupyterLab**:

```bash
jupyter lab
```

2. **Open a `.deepnote` file**:
- Use the file browser to navigate to your `.deepnote` file
- Double-click the file to open it in the notebook viewer

3. **Switch between notebooks** (if the `.deepnote` file contains multiple notebooks):
- Use the notebook picker dropdown in the toolbar
- Select the notebook you want to view

## Architecture

This extension consists of two main components:

- **Server extension**: Handles `.deepnote` file parsing and conversion to Jupyter notebook format. Not all the blocks are supported; visit [docs](https://deepnote.com/docs?utm_source=github&utm_medium=github&utm_campaign=github&utm_content=readme_main) to learn more
- **Frontend extension**: Provides the JupyterLab UI integration and notebook picker widget

The extension uses a custom content provider to intercept `.deepnote` file requests and transform them into Jupyter-compatible notebook content.

## Troubleshooting

### Extension not loading

If the extension doesn't appear to be working:

1. **Verify installation**:

```bash
jupyter server extension list
jupyter labextension list
```

2. **Rebuild JupyterLab** (if installed from source):

```bash
jupyter lab build
```

3. **Check for errors**:

```bash
jupyter lab --debug
```

### Common issues

- **`.deepnote` files not opening**: Ensure the file extension is exactly `.deepnote`
- **Missing notebooks**: Verify the `.deepnote` file contains valid YAML-formatted Deepnote project data
- **Extension conflicts**: Try disabling other notebook-related extensions temporarily

### Getting help

If you encounter issues:

1. Check the [GitHub Issues](https://github.com/deepnote/jupyterlab-deepnote/issues) for similar problems
2. Review the [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
3. Open a new issue with detailed information about your environment and the problem

## Uninstall

To remove the extension, run:
To remove the extension:

```bash
pip uninstall jupyterlab_deepnote
```

After uninstalling, restart JupyterLab for the changes to take effect.

## Compatibility

### JupyterLab Version Support
Expand Down Expand Up @@ -83,6 +166,26 @@ This extension follows semantic versioning for its own API:

Note: This extension does **not** support JupyterLab 3.x or earlier versions.

## Contributing
## Development

For development setup, testing, and contributing guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.

## Related projects

- [Deepnote](https://deepnote.com)
- [Deepnote Open Source](https://github.com/deepnote/deepnote)
- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Deepnote.vscode-deepnote)
- [Cursor extension](https://open-vsx.org/extension/Deepnote/vscode-deepnote)
- [Windsurf extension](https://open-vsx.org/extension/Deepnote/vscode-deepnote)

---

<div align="center">

Made with 💙 by the Deepnote team

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
</div>