Metadata-Version: 2.5
Name: jupyterlab_export_markdown_extension
Version: 1.6.31
Summary: Jupyterlab extension to export markdown file as pdf, docx and html (with embedded images)
Project-URL: Homepage, https://github.com/stellarshenson/jupyterlab_export_markdown_extension
Project-URL: Bug Tracker, https://github.com/stellarshenson/jupyterlab_export_markdown_extension/issues
Project-URL: Repository, https://github.com/stellarshenson/jupyterlab_export_markdown_extension.git
Author-email: Stellars Henson <konrad.jelen@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: beautifulsoup4>=4.7
Requires-Dist: htmldocx>=0.0.6
Requires-Dist: jupyter-server<3,>=2.13.0
Requires-Dist: latex2mathml>=3.0
Requires-Dist: markdown>=3.4
Requires-Dist: matplotlib>=3.5
Requires-Dist: pillow>=9.0
Requires-Dist: playwright>=1.40
Requires-Dist: pygments>=2.0
Requires-Dist: python-docx>=1.0
Requires-Dist: reportlab>=4.0
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: pymupdf; extra == 'test'
Requires-Dist: pypdf; 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_export_markdown_extension

[![GitHub Actions](https://github.com/stellarshenson/jupyterlab_export_markdown_extension/actions/workflows/build.yml/badge.svg)](https://github.com/stellarshenson/jupyterlab_export_markdown_extension/actions/workflows/build.yml)
[![npm version](https://img.shields.io/npm/v/jupyterlab_export_markdown_extension.svg)](https://www.npmjs.com/package/jupyterlab_export_markdown_extension)
[![PyPI version](https://img.shields.io/pypi/v/jupyterlab-export-markdown-extension.svg)](https://pypi.org/project/jupyterlab-export-markdown-extension/)
[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab-export-markdown-extension)](https://pepy.tech/project/jupyterlab-export-markdown-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)

> [!TIP]
> This extension is part of the [stellars_jupyterlab_extensions](https://github.com/stellarshenson/stellars_jupyterlab_extensions) metapackage. Install all Stellars extensions at once: `pip install stellars_jupyterlab_extensions`

Export markdown files to PDF, DOCX, and HTML directly from JupyterLab. No external dependencies required - just `pip install` and go.

![Export Markdown As menu](.resources/screenshot.png)

## Features

- **PDF Export** - Full Unicode and emoji support via reportlab
- **DOCX Export** - Microsoft Word documents with smart image sizing (fit-to-page for large images)
- **HTML Export** - Standalone files with embedded images
- **LaTeX Math** - Native OMML equations in DOCX (editable in Word), KaTeX in HTML, PNG images in PDF
- **GitHub Alerts** - Colored alert boxes for `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` with left border and background shading in DOCX/PDF
- **Mermaid Diagrams** - Rendered server-side to PNG via Playwright Chromium at the configured SVG export width
- **Embedded Images** - Local images automatically converted to base64
- **Syntax Highlighting** - Code blocks with Pygments-powered coloring
- **Wide Tables** - Tables wider than the page wrap within a fitted column layout instead of running past the margin, in PDF, DOCX and HTML
- **Merged Cells** - `colspan` and `rowspan` on raw HTML table cells merge in DOCX and PDF
- **Task Lists** - `- [x]` / `- [ ]` render as checkbox glyphs in HTML, DOCX and PDF
- **Lists and Callouts** - two-space nested lists render as lists, every ordered list restarts at 1, and a bordered `<div>` draws as a box - a uniform border as a frame in its own line style, an accented one with its bar - in DOCX and PDF
- **Inline HTML** - `<span style="color:...">`, `font-weight`, `font-style`, `text-decoration`, `<mark>`, `<del>`, `<ins>`, `<kbd>`, `<font color>`, `align=` and `<div>` render as written in DOCX and PDF
- **Symbol Glyphs** - `★ ☆ ✓ ✗ ☐ ☒`, arrows and box drawing name a font of their own in DOCX, so they look the same in every reader's Word
- **Export Spinner** - Modal dialog shows progress during export operations
- **File Menu Integration** - "Export Markdown As" submenu appears when markdown is active
- **Command Palette** - All export commands available via Ctrl+Shift+C
- **Command Line** - `jupyterlab-export-markdown-extension convert` exports a file to PDF, DOCX and HTML without JupyterLab running
- **Settings** - Configure export font size, SVG export width, math export width, themes, and alert label visibility via Settings Editor
- **Pure Python** - No pandoc, no LaTeX, no system dependencies

## Requirements

- JupyterLab >= 4.0.0
- Python >= 3.10

For PDF export, install required system libraries and emoji font:

```bash
# Ubuntu/Debian
sudo apt-get install libcairo2 libpango-1.0-0 libpangoft2-1.0-0 fonts-noto-color-emoji
```

Mermaid diagrams are rendered client-side using JupyterLab's built-in Mermaid support - no additional installation required. An export driven through the REST endpoints instead of the UI has no browser to render them, so the server renders those diagrams itself with a bundled copy of Mermaid, in the same Playwright Chromium the SVG rasterizer uses - no network access involved.

A diagram that cannot be rendered never fails the export: its source is kept and the response carries an `X-Export-Warnings` header describing what happened, as a JSON array of `{code, count, diagrams, message}`. `code` is one of `chromium-unavailable`, `bundle-missing`, `syntax-error`, `layout-unsupported`, `render-timeout`, `skipped`, `budget-exhausted`, `rasterize-failed` or `render-failed`; `count` is how many diagrams the warning covers, `diagrams` a bounded prefix of their zero-based positions in the document, and `message` the remedy in full - a caller needs nothing beyond the header. An image that is not embedded - its file does not exist or is outside the server root, or its download failed - is reported under the code `image-not-embedded`, with `images`, the first 3 of its paths as written, in place of `diagrams`; HTML keeps such an image's path, DOCX and PDF show a text placeholder. The header is absent when every diagram rendered and every image was embedded, and is listed in `Access-Control-Expose-Headers` so a cross-origin caller can read it.

## Install

```bash
pip install jupyterlab_export_markdown_extension
```

That's it. No really, that's actually it. We spent considerable effort making sure you don't have to install pandoc, LaTeX, or sacrifice a goat to get this working.

## Usage

1. Open a markdown file in JupyterLab
2. Use **File -> Export Markdown As** submenu, or
3. Open command palette (Ctrl+Shift+C) and search "Export Markdown"

## Command Line

The package installs `jupyterlab-export-markdown-extension`, which converts a file without JupyterLab running. `convert` starts a private Jupyter server inside the command and calls the same export endpoints as the menu, so the result matches a UI export made with default settings; the one difference is that Mermaid diagrams render in the server's bundled Mermaid instead of the browser's.

```bash
jupyterlab-export-markdown-extension convert report.md --to pdf docx html
jupyterlab-export-markdown-extension check     # test that Chromium launches
jupyterlab-export-markdown-extension install   # download Chromium and its system libraries
```

- Each document is written beside the source, or to `-o PATH` when there is one format; an existing file is overwritten
- Images are read only from inside `--root` (default: the current directory) - pass a folder that holds the file and every image it links to, such as the repository root; an image that is not embedded is named in a warning on stderr
- Your own Jupyter configuration is not read, so a contents root or log level set there does not change the export
- `--theme`, `--font-size` and `--alert-labels` set what the settings below set in the UI
- `jupyterlab-export-markdown-extension --help` lists the commands, the exit codes and examples; `<command> --help` documents that command's flags and output

An agent skill for AI coding assistants is in [.agents/skills/jupyterlab-export-markdown-extension](.agents/skills/jupyterlab-export-markdown-extension/SKILL.md). `pip install` also copies it to `<sys.prefix>/share/jupyter/agents/skills/jupyterlab-export-markdown-extension`, a folder no agent reads. Link it from there, with the Python that runs JupyterLab:

```bash
mkdir -p ~/.agents/skills && ln -s "$(python -c 'import sys; print(sys.prefix)')/share/jupyter/agents/skills/jupyterlab-export-markdown-extension" ~/.agents/skills/jupyterlab-export-markdown-extension
```

From a clone, link it into Claude Code:

```bash
ln -s "$PWD/.agents/skills/jupyterlab-export-markdown-extension" ~/.claude/skills/jupyterlab-export-markdown-extension
```

## Export Formats

| Format | Library                | Notes                                                            |
| ------ | ---------------------- | ---------------------------------------------------------------- |
| PDF    | reportlab              | Unicode support, compact styling, math as PNG images             |
| DOCX   | python-docx + htmldocx | Native OMML math, smart image sizing, banded tables, alert boxes |
| HTML   | markdown + KaTeX       | Standalone with embedded images, client-side math rendering      |

## Settings

Configure the extension via **Settings -> Settings Editor -> Markdown Export Extension**:

- **Export Font Size** - Base body text size for all three formats: `small` (10pt), `medium` (12pt, default), `large` (13pt). Every other size - headings, tables, code, captions - is a fixed proportion of it, so the whole document scales together
- **SVG Export Pixel Width** - Target pixel width for SVG images and Mermaid diagrams rasterized server-side in DOCX/PDF (default: 1920, range: 400-4096). Height follows the source aspect ratio
- **Math Export Pixel Width (PDF only)** - Target pixel width for math expression images in PDF export (default: 800, range: 200-3000). DOCX uses native OMML equations and HTML uses KaTeX, neither affected by this setting
- **Show Alert Labels** - Display alert type labels (NOTE, TIP, etc.) in exported documents (default: off)

## Uninstall

```bash
pip uninstall jupyterlab_export_markdown_extension
```

## Contributing

If you would like to contribute to this extension, please refer to the [Contributing Guide](CONTRIBUTING.md).

## License

BSD 3-Clause License
