A notebook is evidence. It is not yet a publication.

A notebook can contain everything required to produce a result and still fail to explain what the result means.

The code is there. The chart is there. The intermediate output is there. So are three abandoned cells, an environment assumption nobody wrote down, and the final interpretation buried beneath the experiment that happened to work.

That is not a criticism of notebooks. It is a category mistake. A notebook is excellent evidence of computational work. A publication is a designed path through that evidence for someone who was not present when it was produced.

TidyPress’s Python companion exists at that boundary. It does not execute the notebook or claim to turn analysis into truth. It converts the material into an editable MDX draft so the author can do the editorial work explicitly.

Conversion preserves evidence. The human pass creates the argument.

The reader did not watch the analysis happen

Notebook order often records discovery:

1. load a dataset;
2. inspect a strange column;
3. try one transformation;
4. discover it was wrong;
5. plot a distribution;
6. rerun an earlier cell;
7. arrive at the result.

That sequence is valuable to the person investigating. It may be terrible for the person evaluating the conclusion.

The reader needs a different order:

1. What question were you answering?
2. What data and assumptions did you use?
3. What method produced the result?
4. What did the output show?
5. What are the limits?
6. Where can I inspect or reproduce the source?

Publishing is the act of making that second order legible without destroying the first.

What conversion actually preserves

The Python-native command is intentionally small:

tidypress convert analysis.ipynb \
  --output site/src/content/writing/analysis.mdx

It reads the notebook JSON and writes MDX containing:

• notebook Markdown cells;
• fenced code cells using the notebook’s declared language;
• plain-text and error outputs;
• PNG outputs extracted into a sibling asset directory;
• frontmatter containing a title, date, and source notebook name.

A plot emitted by the first code cell becomes a real file and a Markdown image:

site/src/content/writing/
├── analysis.mdx
└── analysis_assets/
    └── cell-1-output-1.png

The result enters the same repository as the notebook. A reviewer can compare the public explanation with the computational source. An image is not trapped inside base64 notebook JSON. The draft can be edited using ordinary Markdown tools and reviewed through an ordinary pull request.

What conversion deliberately does not do

The command does not run the notebook. It does not install its environment, verify determinism, validate a statistical method, or decide which cells deserve to be public. It does not preserve every possible rich MIME output. Today it handles Markdown, code, text, errors, and PNG images.

Those limits matter because an import tool can easily imply more confidence than it has earned. A beautifully rendered notebook with stale outputs is still stale. A converter that silently executes code can change data or contact services during what appeared to be a formatting operation.

TidyPress chooses an inspectable handoff: convert what already exists, then let the author review the draft.

A useful editorial pass

After conversion, the most important work begins. A strong public result usually needs at least these edits:

State the question before the machinery

Open with the decision or uncertainty the analysis addresses. “We compared three cache strategies under burst traffic” gives a reader a reason to care. “Importing pandas and loading the CSV” does not.

Separate method from exploration

Keep code that lets a reader understand or reproduce the method. Remove dead ends unless the dead end teaches something important. If it does, explain why it failed instead of leaving the reader to infer the lesson from cell order.

Interpret every result worth showing

A plot is not a conclusion. Tell the reader what pattern matters, what would have contradicted the hypothesis, and how uncertainty should affect the next decision.

Name the limits

Document missing data, environmental assumptions, small samples, untested conditions, and places where the result should not be generalized. This is not weakness; it is what makes the result usable by someone who was not in the room.

Link the evidence

Keep the notebook, dataset instructions, package version, or repository path close enough that a skeptical reader can inspect them. The public article should not become a polished orphan disconnected from its source.

One repository can hold the result and its context

A lab often publishes through several tools because each object appears to need its own platform. Notebooks live in one viewer. Documentation lives somewhere else. Project pages are maintained on a departmental site. Results are copied into a blog. API notes are generated into another directory.

TidyPress gives those objects distinct public surfaces without separating their authorship:

• the notebook remains evidence in the repository;
• the converted essay can live in writing;
• reproducibility instructions can live in docs;
• the package can appear in projects or works;
• generated source notes can begin a reference section;
• decisions and failed approaches can live in process.

The final build connects them through one navigation system, search index, and domain. The publication becomes a map of the work rather than a copy of its final abstract.

Python is an input tool, not a second renderer

The companion package owns notebook conversion and simple source-comment extraction for Python, TypeScript, and Go. The Node CLI and Astro engine still own site rendering.

This asymmetry is useful. Scientific and data work often begins in Python, so Python should have a direct way to produce authored files. Reimplementing the entire router, MDX component system, theme layer, and static build in Python would create two publishing products that slowly disagree.

The shared artifact is Markdown in Git. Python helps material enter that boundary; one renderer decides how it becomes a site.

Publication is part of the research method

The last step of analysis is often treated as presentation: make the graph cleaner, remove the debugging cells, write a summary.

But forcing a result into a reader’s order exposes methodological questions. Which assumption was essential? Can the method be described without relying on the author’s memory? Does the plot support the sentence placed above it? Could a collaborator locate the exact source that produced it?

Those are not cosmetic questions. They are quality checks created by the act of explanation.

A notebook proves that computation happened. A publication tells another person what happened, why it matters, and how much confidence to place in it. TidyPress does not collapse those roles. It gives the handoff between them a durable, reviewable form.