jupyterlab_advanced_markdown_viewer_extension

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 or is typed in beside it, and its pictures stay on screen instead of loading again
• 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
• Copy the address of a link - Copy link address in the context menu of a link puts the address the link opens on the clipboard
• Copy a picture - Copy image in the context menu of a PNG, JPEG or other raster picture puts the picture on the clipboard, ready to paste into an email or a document

Screenshots

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

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.

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 Comment to mark and write a note in one step. Shift Enter in the note box saves it; Enter on its own starts a new line. The first note you write asks for the initials your notes are signed with, and Set note handle in the command palette changes them afterwards
• Right-click a drawn Mermaid diagram and pick a colour under Mark, or choose Add Comment: the whole picture is covered in the mark's colour, and its row in the notes panel starts with the Mermaid icon
• 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 thread; click the row's top line, or press Enter on the row, to close it again. The eye and the trash at the right of the top line act on the whole mark: the eye shows whether the mark is visible or hidden, and pressing it closes the mark, which hides it until the panel's Show hidden control lists it. The first entry is the comment, every entry after it a reply, listed one after another; each carries an edit icon and an x that deletes it, both shown while the pointer is on the note. The colour swatch at the left of a row rolls the other colours down: pick one to recolour the mark. 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. Where a change from disk has taken a marked passage away, the row says unanchored and a thin bar stands in the preview at the place the mark began, so you can still see where the note belongs
• 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
• Right-click a link in the preview and choose Copy link address. A link to another file gives that file's address on the server, and the paragraph mark beside a hovered heading gives the address of that heading
• Right-click a picture in the preview and choose Copy image to put it on the clipboard at the size of its file. The entry is not offered on an SVG picture or a drawn Mermaid diagram, which jupyterlab_export_svg_as_png_extension copies and saves as PNG, nor on a picture from another website; hold Shift while you right-click to get the browser's own menu, which copies it

Agent skill

The skill in .agents/skills/jupyterlab-advanced-markdown-viewer-extension teaches an AI assistant the marks this extension stores in the file. With it, the assistant can:

• mark passages in the six colours
• comment on a passage or on the whole document
• answer and close your comments
• watch a file for new comments, with the bundled scripts/watch-marks.py

Agents that read .agents/skills find it in a clone of this repository. The skill is not part of the installed package. To use it in Claude Code, run this from the root of the clone:

mkdir -p ~/.claude/skills && ln -sfn "$PWD/.agents/skills/jupyterlab-advanced-markdown-viewer-extension" ~/.claude/skills/jupyterlab-advanced-markdown-viewer-extension

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 @user, and the first note you write asks you for one

Requirements

• JupyterLab >= 4.0.0

Install

To install the extension, execute:

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:

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:

pip uninstall jupyterlab_advanced_markdown_viewer_extension