Metadata-Version: 2.4
Name: cutiepynb
Version: 1.1.0
Summary: Add colorful headings and a table of contents to Jupyter notebooks.
Author-email: Elisa Márquez-Zavala <emarquez@lcg.unam.mx>
License-Expression: MIT
Project-URL: Homepage, https://github.com/emarquezz/cutiepynb
Project-URL: Documentation, https://emarquezz.github.io/cutiepynb
Project-URL: Issues, https://github.com/emarquezz/cutiepynb/issues
Project-URL: Changelog, https://github.com/emarquezz/cutiepynb/blob/main/docs/changelog.md
Keywords: jupyter,notebook,markdown,table-of-contents,styling
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: palette
Requires-Dist: seaborn>=0.12; extra == "palette"
Provides-Extra: test
Requires-Dist: nbformat>=5.7; extra == "test"
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: seaborn>=0.12; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Dynamic: license-file

# cutiepynb 💖

[![PyPI](https://img.shields.io/pypi/v/cutiepynb.svg)](https://pypi.org/project/cutiepynb/)
[![CI](https://github.com/emarquezz/cutiepynb/actions/workflows/ci.yml/badge.svg)](https://github.com/emarquezz/cutiepynb/actions/workflows/ci.yml)
[![Documentation](https://github.com/emarquezz/cutiepynb/actions/workflows/docs.yml/badge.svg)](https://emarquezz.github.io/cutiepynb/)
[![Python](https://img.shields.io/pypi/pyversions/cutiepynb.svg)](https://pypi.org/project/cutiepynb/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Turn an ordinary Jupyter notebook into a colorful, easy-to-navigate notebook.
`cutiepynb` styles Markdown headings, adds stable anchors, and generates a
linked table of contents. The base package has no runtime dependencies.

Prefer not to install anything? The browser app can also fix heading titles and
levels. Its native JavaScript formatter starts immediately and runs locally in
your tab—there is no Python runtime or notebook upload:
[open cutiepynb studio](https://emarquezz.github.io/cutiepynb/app/).


## Before and after

<table>
  <tr>
    <th>Before</th>
    <th>After</th>
  </tr>
  <tr>
    <td><img src="https://raw.githubusercontent.com/emarquezz/cutiepynb/main/docs/images/example_1.jpeg" alt="Notebook before cutiepynb" width="420"></td>
    <td><img src="https://raw.githubusercontent.com/emarquezz/cutiepynb/main/docs/images/example_2.jpeg" alt="Notebook after cutiepynb" width="420"></td>
  </tr>
</table>

## Install

```bash
python -m pip install cutiepynb
```

## Quick start

From the terminal:

```bash
cutiepynb analysis.ipynb \
  --color "#5D2197" \
  --color "#AB1A7C" \
  --color "#DE2227"
```

This creates `analysis_chulo.ipynb` and leaves the original untouched. Existing
output is protected; use `--force` only when you intend to replace it.

Or from Python:

```python
from cutiepynb import process_notebook

output = process_notebook(
    "analysis.ipynb",
    colors=["#5D2197", "#AB1A7C", "#DE2227"],
)
print(output)
```

`cutiepy_nb(...)`, the original API, is still available for existing notebooks.

## Highlights

- Colors heading levels with your own CSS color palette.
- Generates a nested table of contents with unique links.
- Handles several headings in one Markdown cell.
- Ignores headings inside code cells and fenced Markdown examples.
- Produces the same result when safely run more than once.
- Lets the browser studio rename headings, change H1–H6 levels, and recolor
  notebooks it styled earlier.
- Supports both a Python API and a command-line interface.
- Uses seaborn palettes through the optional `cutiepynb[palette]` extra.
- Includes a private-by-design browser studio that never executes notebook code.
- Keeps the native browser formatter aligned with Python through shared
  transformation fixtures.

Read the [full tutorial](https://emarquezz.github.io/cutiepynb/tutorial/) for
custom output paths, in-place editing, seaborn palettes, recoloring, and
in-memory transformations.

## Development

```bash
git clone https://github.com/emarquezz/cutiepynb.git
cd cutiepynb
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
pytest
mkdocs serve
```

Released under the [MIT License](LICENSE).
