Word vs PDF vs Markdown: Which Jupyter Notebook Export Should You Use?
A practical decision guide for exporting a Jupyter notebook: when Word is better than PDF, when Markdown belongs in Git, and when you should refuse to convert at all.
A notebook is a working document. An export is a message to someone who will not open Jupyter. Pick the format for that person, not for search engines.
This is not a catalogue of every converter on the site. It is the decision we wish course handbooks spelled out. Tools: /ipynb-to-docx, /ipynb-to-pdf, /ipynb-to-markdown.
Start with the reader, not the file extension
Ask three questions:
- Will they edit the text, or only read it?
- Must page breaks and figure placement stay frozen?
- Will this live in Git, an LMS, or email?
If they will edit, you want Word (or ODT on a LibreOffice campus). If a portal hashes the file and rejects anything that reflows, you want PDF. If the audience is a repository, you want Markdown — and you probably want outputs stripped first.
Word (.docx) when comments still matter
Word is the format of committees, supervisors, and clients who live in track changes. Headings become real headings. Plots that were saved in the notebook can sit inline. Someone can still rewrite a paragraph without asking you for a new kernel.
Do not use Word when:
- A journal or LMS demands a fixed layout.
- You need a thumbnail or a social card (use JPG).
- The only “reviewer” is Git.
Convert from /ipynb-to-docx after you have run the notebook so outputs exist. Then open the .docx yourself before you send it. Converters are not typesetting engines; they will not match a branded university template. Paste into that template if you must.
PDF when the layout must not drift
PDF is a photograph of intent: page size, order of cells, figures where they were. Graders who print packets, review boards, and “upload one PDF” portals belong here.
PDF is the wrong choice when someone still needs to copy a table into Excel or rewrite your discussion. They will hate you, and they will screenshot anyway.
Use /ipynb-to-pdf. If the PDF is blank where a plot should be, the plot was never saved in the .ipynb. That is a Jupyter problem, not an export problem.
Markdown when Git is the destination
Markdown is how notebooks talk to documentation systems. README files, MkDocs, and pull-request descriptions want text they can diff. A 4 MB PDF in Git is a mistake. A Markdown file with huge base64 images is also a mistake — strip outputs first (/ipynb-output-cleaner) or compress (/ipynb-compressor).
Use /ipynb-to-markdown when the next reader is a human in a text editor or a static site generator. Keep the notebook as the executable source of truth.
Formats we did not pick on purpose
- HTML — a shareable preview when the recipient can open a browser but not Word. Not an archival format.
- EPUB — for reading on a phone or e-reader. Almost never what a grader wants.
- LaTeX — a draft for Overleaf, not a finished paper.
- JPG — a picture of the notebook, useful for slides, useless as a submission.
A short rule of thumb
| Situation | Export |
|-----------|--------|
| Supervisor comments in Word | DOCX |
| LMS / journal / print packet | PDF |
| Repo, wiki, docs site | Markdown (often after stripping outputs) |
| “Just look at this” | Viewer, then HTML if they need a file |
| You still need to run cells | Do not convert — send the .ipynb or a repo |
Keep the notebook. Export a copy. Converts on Jupy Tools process the upload for that request only and do not keep the file. The viewer and diff never need that upload; they stay in the tab.
If you are unsure, export PDF for the deadline and keep Markdown in Git. Those two cover most honest jobs.
FAQ: choosing an export format
Send whatever the syllabus asks for. If it is silent, PDF is the safer frozen hand-in. Word is better if they still comment in track changes. Keep the .ipynb as your working copy.
No. Markdown is for Git, docs sites, and humans who will edit text. PDF is for portals that must not reflow. They solve different jobs.
Only if they were saved in the notebook before you convert. Re-run cells in Jupyter first. A converter cannot invent figures that were never stored.