A worked example: one sample notebook, five exports

This is a walkthrough of one real file, not a slogan about conversion. The file is the public sample notebook published with these guides. It is three cells long. You can download it, open it as text, and follow every claim. Where a format cannot represent part of the notebook, the walkthrough says so. A small honest example is more useful than a screenshot of a perfect report.

What is in the file

Open the .ipynb in a text editor first.

The notebook declares nbformat 4. Metadata names a Python 3 kernel and records language_info with the name python and a version string 3.11.0. That version is a note about the file we wrote. It does not install Python 3.11 for you.

Cell one is Markdown. The source is a title, “Sample notebook,” and two short paragraphs explaining that the file has no secrets and no plot images.

Cell two is Markdown. It is a heading, “What is stored in this file,” and a list of four bullets: two Markdown cells, one code cell, one saved stdout output, and kernel metadata that is only a hint.

Cell three is code. The source is:

title = "Jupy Tools sample"
print(title)
print(2 + 2)

execution_count is 1. The single output is a stream on stdout. The text is:

Jupy Tools sample
4

There is no display_data, no PNG, no HTML table, no error output, and no widget state. If an export shows a chart for this file, something is wrong, because the chart was never stored. If an export shows the two lines above, it included saved output. If it shows only the three lines of code, it included source and dropped outputs. Both can be correct, and they are different choices.

The file does not import third-party packages. A requirements list extracted from it should be empty or nearly empty. That is a feature of the example. It stops people from confusing “no imports found” with “the tool broke.”

What you should see in a viewer

A viewer that understands nbformat should show the title, the bullet list, the code with some kind of monospace formatting, and the two-line output under the code. It should not ask you to run anything in order to see that output. The output is already in the file.

It should not show a kernel status that implies code is executing. Nothing is executing. If the viewer offers to run cells, that is a different product from a reader, and this file’s result will not change unless you run it.

If the viewer shows only raw JSON, it is not rendering cells. You can still read the notebook, but you are doing the rendering yourself. That is the same activity as the text-editor pass above.

PDF

Export the sample to PDF with outputs included.

You should get more than one short block of text, but you should not get a long document. The title and the second heading should be distinguishable from body text if the converter maps Markdown headings. The code should be monospace or otherwise visually distinct from the paragraphs. The stdout lines should appear after the code, not instead of the code.

You should not get page after page of whitespace. You should not get an image. You should not get a second copy of the output that contradicts 4.

What this PDF cannot do: open as a notebook, re-run print(2 + 2), or prove that Python 3.11 is installed on the reader’s computer. The version string in metadata may or may not be printed. Many PDF exporters omit notebook metadata on purpose because it is not part of the reading experience. Absence of “python 3.11” on the page is not a failed export.

If you export again with outputs turned off, the two stdout lines should disappear and the code should remain. If both disappear, the tool dropped the code cell, and that is a bug or a setting you did not mean to use.

Word and ODT

Export to .docx or .odt with outputs included.

Open the document in a word processor. You should be able to place the cursor in the paragraph under the title and type. That is the point of this format. The code may be a styled paragraph or a content control that looks like a block. The words Jupy Tools sample and 4 should be present as text you can search for with the editor’s find command. If find cannot see them, they were flattened into a picture. That would be a poor Word export of this file, because the source outputs are plain text, not images.

Comments you add in Word stay in the document. They do not travel back into the .ipynb. If you need both, keep both files.

A round trip that starts from this Word file and tries to rebuild a notebook can recover headings and the code lines only by guessing. It will not restore execution_count: 1 or the stream output object. Expect a new notebook that resembles the prose and the code, not a clone of the JSON.

Markdown

Export to Markdown with outputs included.

You should see a level-one heading, a level-two heading, a fenced code block containing the three Python lines, and some representation of the stdout text. The fence language may say python. The output may be a quote, a second fence, or a paragraph, depending on the converter. What matters is that the words are there and that the code is still code, not a JPEG.

There will be no .png beside this export, because the notebook has no image output. If the converter always writes an images/ folder, that folder can be empty. Do not treat an empty images folder as a failure on this particular file.

Without outputs, the fenced code remains and the lines Jupy Tools sample and 4 go away unless the converter also echoed the source. Read the file. Do not assume.

HTML

Export to HTML and open it in a browser.

The title should be a heading. The list in the second cell should be a list. The code should be in a pre or code element so spaces are preserved. The output text should be selectable with the mouse. View the page source if you want to confirm the text is real text.

The page should not need a network call to show these three cells. The sample has no remote images. If the HTML file references a stylesheet on another machine, the words should still be readable when you are offline. Styling may look plainer. That is acceptable.

Nothing in this HTML should try to run Python in the browser. If a script from a notebook widget ran, this sample would be the wrong file to discover that, because it has no widget. Use a notebook that actually contains a widget before you trust an HTML export with interactive output.

Python

Export to a .py script.

You should see the three lines of code, or those lines plus comment lines that quote the Markdown. You should not see a valid Python program whose only content is the Markdown paragraphs with the code deleted. You should not see the stdout glued into the script as if it were source, unless you explicitly asked for outputs as comments.

Running the script with a normal Python 3 interpreter should print:

Jupy Tools sample
4

That run is you executing the script. The export did not do it. If your Python is older than 3, this particular script still works, because it uses no 3.11-only syntax. The metadata version is not a constraint on the script.

If you convert that .py back to .ipynb, you will get cells and no saved output, unless the reverse converter fabricated an output by running code. A converter that does not claim to execute should not invent the stream. You would run the new notebook yourself to get [1] again.

What this file will never show you

The sample will not teach you whether a matplotlib figure survives. There is no figure. Test that with a notebook you already know contains image/png in a display_data output, or add a plot, run it, save, and export that file.

The sample will not teach you LaTeX math, RTL text, or very long code lines. Those are real wrapping problems in PDF and slides. Add one cell with a long line or a formula when you need to see them.

The sample will not teach you environment export. There are no imports. A requirements extract that returns nothing is the correct result.

The sample will not teach you repair. The JSON is valid. If you want to see a repair tool behave, make a copy and delete a comma on purpose. Do not learn repair by feeding it a healthy file and expecting a dramatic change.

How to use the file on a tool page

Download jupy-tools-sample.ipynb. Upload that file, not a renamed copy of a different notebook. Compare the result with the section above for the format you chose. If the tool has a switch for outputs, try both positions. The difference should be exactly the two-line stream, not a change to the Markdown.

When your own notebook disagrees with this walkthrough, the usual reasons are: outputs were empty because the cell was never run; images were on screen but not saved; a setting excluded code or Markdown; or the file is not nbformat JSON. The format limits in what exports keep and drop are the list to check next. The structure in what an .ipynb file contains is how you confirm the input before you blame the export.