# Convert IPYNB to Markdown

Convert Jupyter .ipynb JSON to Markdown with fenced code blocks, markdown cells, outputs, errors, HTML tables, and embedded image data URIs. Browser-only.

## Run it

- **CLI:** `gizza tool ipynb-to-markdown '{"cells":[{"cell_type":"markdown","source":["# Title\n"]},{"cell_type":"code","execution_count":1,"source":["print(2 + 2)"],"outputs":[{"output_type":"stream","name":"stdout","text":["4\n"]}]}],"metadata":{"language_info":{"name":"python"}},"nbformat":4,"nbformat_minor":5}'`
- **Web:** https://gizza.ai/tools/ipynb-to-markdown/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/ipynb-to-markdown/tool.json

## Inputs

- `notebook` — Notebook JSON (.ipynb contents) _(field)_
- `include_code` — Include code cells as fenced blocks _(field)_
- `include_outputs` — Include stored outputs (stdout, results, errors, images) _(field)_
- `include_markdown` — Include markdown/raw cells _(field)_
- `show_prompts` — Show execution-count prompts (In [n] / Out [n]) _(field)_
- `image_mode` — Image handling _(field)_

## Output

- Markdown (text)

## Query parameters

Open the tool pre-filled and auto-run via URL:

- `notebook` — Notebook JSON (.ipynb contents)
- `include_code` — Include code cells as fenced blocks
- `include_outputs` — Include stored outputs (stdout, results, errors, images)
- `include_markdown` — Include markdown/raw cells
- `show_prompts` — Show execution-count prompts (In [n] / Out [n])
- `image_mode` — Image handling

Example: `https://gizza.ai/tools/ipynb-to-markdown/?notebook=%7B%22cells%22%3A%5B%7B%22cell_type%22%3A%22markdown%22%2C%22source%22%3A%5B%22%23%20Title%5Cn%22%5D%7D%2C%7B%22cell_type%22%3A%22code%22%2C%22execution_count%22%3A1%2C%22source%22%3A%5B%22print%282%20%2B%202%29%22%5D%2C%22outputs%22%3A%5B%7B%22output_type%22%3A%22stream%22%2C%22name%22%3A%22stdout%22%2C%22text%22%3A%5B%224%5Cn%22%5D%7D%5D%7D%5D%2C%22metadata%22%3A%7B%22language_info%22%3A%7B%22name%22%3A%22python%22%7D%7D%2C%22nbformat%22%3A4%2C%22nbformat_minor%22%3A5%7D&include_code=true&include_outputs=true&include_markdown=true&show_prompts=true&image_mode=embed`

---

## Export a Jupyter notebook as Markdown

Paste the JSON contents of an `.ipynb` file and this tool turns the notebook into a
single Markdown document. Markdown cells are emitted as Markdown, code cells become
fenced code blocks using the notebook language, and stored outputs can be rendered
below the cell just like a notebook export.

Use it when you want a clean README, blog draft, lab note, or documentation page
from a notebook without installing Python or running `nbconvert` locally.

### What gets converted

- **Markdown/raw cells** are copied verbatim, including headings, lists, and links.
- **Code cells** become fenced blocks such as ```` ```python ````.
- **Stream outputs** (`stdout` / `stderr`) and plain results are rendered in text
  fences.
- **Rich results** prefer Markdown, then images, then HTML tables, then LaTeX, then
  plain text.
- **Errors** are rendered as stripped tracebacks so ANSI colors do not leak into
  the Markdown.
- **Image outputs and attachments** can be embedded as inline `data:` URIs,
  replaced with a short placeholder, or omitted.

### Worked example

A notebook with one markdown cell and one code cell:

```json
{"cells":[
  {"cell_type":"markdown","source":["# Demo\n","Some notes"]},
  {"cell_type":"code","execution_count":1,
   "source":["print(2 + 2)"],
   "outputs":[{"output_type":"stream","name":"stdout","text":["4\n"]}]}
],"metadata":{"language_info":{"name":"python"}},"nbformat":4,"nbformat_minor":5}
```

becomes:

````markdown
# Demo

Some notes

```python
print(2 + 2)
```

```
4
```
````

Turn off **Include code cells** to get a no-input export that keeps outputs, or turn
off **Include stored outputs** for a code-only notebook-to-Markdown conversion.

## FAQ

<details>
<summary>Is this the same as converting a notebook to a Python script?</summary>

No. A script export focuses on runnable code and usually drops notebook outputs.
This tool is a document export: it preserves markdown cells and, by default,
renders stored outputs such as stdout, rich results, errors, and images. Use
`ipynb-to-script` when you want a `.py`; use this when you want a readable `.md`.

</details>

<details>
<summary>What happens to plots and image outputs?</summary>

By default, image outputs are embedded as inline `data:` URIs so the Markdown is a
single self-contained string. If you do not want large base64 blocks, set **Image
handling** to **placeholder** for `*[image output]*` notes or **omit** to drop image
outputs entirely. A sidecar `_files/` image directory is not produced because this
tool returns one Markdown value.

</details>

<details>
<summary>Can it keep outputs but hide the code?</summary>

Yes. Turn off **Include code cells** and leave **Include stored outputs** on. That
matches the common no-input export shape: prose plus outputs, without the source
code that produced them.

</details>

<details>
<summary>Does it execute the notebook?</summary>

No. It reads the JSON already stored in the `.ipynb` file. Only outputs that are
present in the notebook are rendered. If a notebook was saved after clearing its
outputs, this converter cannot recreate them.

</details>

<details>
<summary>Why are some rich outputs rendered as HTML?</summary>

Notebook outputs can carry many MIME representations. Markdown is chosen first,
then images, then HTML, then LaTeX, then plain text. Keeping HTML is useful for
DataFrame tables and other rich displays because raw HTML is valid inside Markdown.

</details>

### Limits & edge cases

- Input must be valid Jupyter notebook JSON with a `cells` array (nbformat v4 is
  the primary target; legacy v3 markdown cells are tolerated).
- The tool does not run code, fetch external files, or evaluate widgets.
- Very large embedded images can produce large Markdown because base64 image data
  is included inline when `image_mode=embed`.
- Binary sidecar files from `nbconvert` are represented as inline data URIs,
  placeholders, or omitted; no ZIP or `_files/` directory is generated.
- Unknown cell types are ignored, and empty cells are skipped.

## Related tools

- [BibTeX Formatter & Validator](https://gizza.ai/tools/bibtex-format/): Free BibTeX formatter and validator — pretty-print, sort and align .bib bibliography entries in your browser. Consistent indentation, no sign-up, no upload.
- [Citation Generator](https://gizza.ai/tools/citation-generator/): Free APA 7, MLA 9, Chicago and Harvard citation generator — format author, title, year, journal and URL into a correct reference right in your browser.
- [Document Splitter](https://gizza.ai/tools/document-splitter/): Split a long Markdown or HTML document into separate files, one per top-level heading. Runs entirely in your browser, no upload, no sign-up.
- [ENEX to Markdown Converter](https://gizza.ai/tools/enex-to-markdown/): Convert Evernote ENEX exports to Markdown or plain text with titles, dates, tags, source URLs, and attachment summaries — locally in your browser.
- [HTML to Markdown](https://gizza.ai/tools/html-to-markdown/): Convert HTML into clean Markdown instantly in your browser — preserves headings, links, lists, code blocks, tables, and emphasis. Free, private, no upload, no sign-up.