Metadata-Version: 2.5
Name: jupyterlab_advanced_markdown_viewer_extension
Version: 1.0.11
Summary: Live Markdown preview for JupyterLab: an open rendered Markdown document follows the file on disk without a reload, with changes typed in on a green background, removed text shown red before it goes, and a tab cue
Project-URL: Homepage, https://github.com/stellarshenson/jupyterlab_advanced_markdown_viewer_extension
Project-URL: Bug Tracker, https://github.com/stellarshenson/jupyterlab_advanced_markdown_viewer_extension/issues
Project-URL: Repository, https://github.com/stellarshenson/jupyterlab_advanced_markdown_viewer_extension.git
Author-email: Stellars Henson <konrad.jelen+github@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: jupyter,jupyterlab,jupyterlab-extension
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: jupyter-server<3,>=2.13.0
Requires-Dist: jupyterlab-colourful-tab-extension>=1.1.21
Requires-Dist: jupyterlab-edit-markdown-at-content-extension>=1.0.24
Requires-Dist: jupyterlab-export-markdown-extension>=1.6.28
Requires-Dist: jupyterlab-github-markdown-alerts-extension>=1.0.25
Requires-Dist: jupyterlab-markdown-insert-content-extension>=1.1.28
Requires-Dist: jupyterlab-markdown-switch-tab-scrolling-fix>=1.0.18
Requires-Dist: jupyterlab-markdown-syntax-rendering-fix>=1.0.2
Requires-Dist: jupyterlab-markdown-viewer-toc-fix>=1.0.15
Requires-Dist: jupyterlab-paste-content-as-markdown-extension>=1.0.8
Requires-Dist: jupyterlab-refresh-view-extension>=1.2.33
Requires-Dist: watchdog<7,>=4
Provides-Extra: dev
Requires-Dist: jupyter-builder>=1.2.0; extra == 'dev'
Requires-Dist: jupyterlab>=4; extra == 'dev'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-jupyter[server]>=0.6.0; extra == 'test'
Description-Content-Type: text/markdown

# jupyterlab_advanced_markdown_viewer_extension

[![GitHub Actions](https://github.com/stellarshenson/jupyterlab_advanced_markdown_viewer_extension/actions/workflows/build.yml/badge.svg)](https://github.com/stellarshenson/jupyterlab_advanced_markdown_viewer_extension/actions/workflows/build.yml)
[![npm version](https://img.shields.io/npm/v/jupyterlab_advanced_markdown_viewer_extension.svg)](https://www.npmjs.com/package/jupyterlab_advanced_markdown_viewer_extension)
[![PyPI version](https://img.shields.io/pypi/v/jupyterlab-advanced-markdown-viewer-extension.svg)](https://pypi.org/project/jupyterlab-advanced-markdown-viewer-extension/)
[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab-advanced-markdown-viewer-extension)](https://pepy.tech/project/jupyterlab-advanced-markdown-viewer-extension)
[![JupyterLab 4](https://img.shields.io/badge/JupyterLab-4-orange.svg)](https://jupyterlab.readthedocs.io/en/stable/)
[![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
[![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)

See the changes an AI agent, or any other program, makes to a Markdown file as it makes them. The JupyterLab Markdown Preview shows each change without a reload: added text is typed in on green, and removed text is struck through on red, then deleted. While the agent works, you can mark passages and write notes on them, stored in the Markdown file itself.

## Features

- **Changes show as they are written** - the Markdown Preview shows a change to the file within half a second, with no reload
- **Watch each change happen** - added text is typed in on green; removed text is struck through on red, then deleted
- **Your place is kept** - the preview keeps the same text in view when the file changes outside it
- **See which tab changed** - a half-filled circle for a new change, a red square for a change held back or dropped where it met your unsaved edits, a cross for a deleted file
- **Unsaved edits are kept** - a change from disk lands around your unsaved edits; where it overlaps or sits right beside them your text stands and the tab shows a red square; when the part that is dropped adds or removes a code fence or an HTML comment marker, such as a mark, none of the change is shown; save to keep your version, or choose File, Reload Markdown File from Disk to take the file's
- **Mark and note while the agent writes** - six colours, notes on a passage or on the whole document, all listed beside the preview
- **Notes are stored in the file** - as HTML comments that other Markdown renderers do not show; a note line an agent adds appears in the thread
- **Copy the document, or one passage of it, for an email** - **Copy Content** in the preview's context menu puts the selected passage on the clipboard as basic HTML, or the whole rendered document when nothing is selected, without the theme's colours, the marks' paint or any styling

## Screenshots

The screenshots use a dark theme; the colours of changes and marks change with the active JupyterLab theme.

![A change being typed into the Markdown Preview](docs/images/animation-01.png)

A change arriving from disk: "Monday." is struck through on red before it is deleted, "Tuesday." has been typed in on green, and two new lines are still being typed. The half-filled circle on the report.md tab shows that the file changed.

![The notes panel beside the preview](docs/images/notes-01-panel.png)

Notes beside the preview: a note on the whole document, then three marked passages. Each note shows who wrote it and when, and all of them are stored in report.md as HTML comments.

## Usage

- Right-click a Markdown file in the file browser and choose **Open With**, then **Markdown Preview**. From then on a change arriving from disk is highlighted, and the tab shows an icon until you look
- Select a passage in the preview, right-click and pick a colour under **Mark**; or select with caret browsing (F7) and press Ctrl Shift M (Cmd Shift M on macOS). Choose **Add note** to mark and write a note in one step
- Press the plus in the notes panel header for a note on the document as a whole; the panel is shown from the badge at the top right of the preview or from Show notes in the context menu. The context menu and the palette offer no entry for the document note itself
- Click a row in the panel to reveal its passage and open its notes, colours and removal control; the caret at the header's left edge collapses the panel to a strip of ticks, the cross hides it. With the panel hidden, the notes badge at the top right of the preview brings it back
- Right-click the preview and choose **Copy Content** to put the selected passage on the clipboard as basic HTML, or the whole rendered document when nothing is selected: headings, lists, tables, links and code, with no colours or styling, ready to paste into an email. A selected table row keeps the table its cells sit in, and a selected fenced block keeps the line breaks of its program. The same entry is in the command palette

## Limitations

- A file open only in an editor is not followed; open it in the Markdown Preview. A preview opened over unsaved edits after the file had already changed holds that change back, and a save then meets JupyterLab's own File Changed dialog
- On network drives, Windows drives under WSL2 and other mounts that raise no file events, the first change can take up to 10 seconds to show; after it, the file is checked every second
- A line an agent appends during the few milliseconds a mark is being written can be lost
- With unsaved edits, a new mark stays in the document and reaches the file with your next save
- With live updates off, or without the server extension, a mark is saved through JupyterLab, whose File Changed dialog can appear if an agent wrote in between; Revert keeps the agent's text and drops the new mark
- Showing, collapsing or hiding the notes panel stores that state in the file as an HTML comment

## Settings

All settings live under Settings, Advanced Settings Editor, Advanced Markdown Viewer.

- `enabled` - on by default; off, the preview keeps what it showed until the document is reloaded; marks and notes have their own setting
- `pollInterval` - the interval of the fallback check for filesystems that raise no file events, in seconds; file events through the server extension are the primary path, so a lower value does not make updates faster
- `highlight` - green and red backgrounds on changed text
- `highlightVisibility` - how strong those two backgrounds are: Low, Medium or High, Medium by default
- `fadeDuration` - how long the highlight stays on changed text, in milliseconds; it rises over 0.5 s and fades away over the last 0.75 s
- `animation` - on by default; changes play out as typing
- `animationSpeed` - typing and deletion speed in characters per second on average, 75 by default; 0 shows a change at once
- `animationJitter` - how far each character's time may stray from the even time at that speed, as a share of that time, from 0 to 1, 0.25 by default; 0 types evenly
- `tabCue` - the markers on the document tab
- `notes` - on by default; off, the panel, the marks and the marking entries are hidden and the markers in the file are left alone
- `author` - the handle a note line opens with, without the leading @; empty writes `@author`

## Requirements

- JupyterLab >= 4.0.0

## Install

To install the extension, execute:

```bash
pip install jupyterlab_advanced_markdown_viewer_extension
```

## The Markdown suite

The install above brings ten more extensions with it. Each fixes or adds one thing in JupyterLab's
Markdown handling, and this extension is built to work beside all of them:

| Extension                                        | What it adds                                                                     |
| ------------------------------------------------ | -------------------------------------------------------------------------------- |
| `jupyterlab_markdown_viewer_toc_fix`             | Table of Contents navigation and anchor links work in the Markdown Viewer        |
| `jupyterlab_markdown_switch_tab_scrolling_fix`   | A Markdown file stops scrolling by itself when you switch tabs while images load |
| `jupyterlab_markdown_syntax_rendering_fix`       | Syntax colours in rendered fenced code blocks with no editor open                |
| `jupyterlab_github_markdown_alerts_extension`    | GitHub alert blocks render, such as `> [!NOTE]` and `> [!WARNING]`               |
| `jupyterlab_edit_markdown_at_content_extension`  | Opens the editor at the line you were reading in the preview                     |
| `jupyterlab_markdown_insert_content_extension`   | Inserts reusable content blocks, starting with a generated table of contents     |
| `jupyterlab_paste_content_as_markdown_extension` | Pastes formatted clipboard content as Markdown                                   |
| `jupyterlab_export_markdown_extension`           | Exports a Markdown file to PDF, DOCX and HTML                                    |
| `jupyterlab_refresh_view_extension`              | A Refresh View command reloads a file from disk, keeping the scroll position     |
| `jupyterlab_colourful_tab_extension`             | Pastel tab colours, so many open documents stay tellable apart                   |

Each one also works on its own. The version floors are simply what each sibling was published at
when the family was surveyed; none of them is imported, required or linked by this extension's
code, so an older one degrades rather than breaks.

## Uninstall

To remove the extension, execute:

```bash
pip uninstall jupyterlab_advanced_markdown_viewer_extension
```
