A notebook has two halves of a life. In the first you run it. In the second somebody reads it, usually on a machine with no .NET on it and no intention of getting any.
The reading half is where notebook workflows pick up a service: somewhere to upload to, an export step, a copy that drifts from the file the moment you commit again. Our answer is an edit to the address bar.
Take the address of a notebook in a public repository:
https://github.com/DataficationSDK/Verso/blob/main/samples/showcase/slide-studio/slide-studio.verso
Change the host to www.versonotebooks.com/share/github:
https://www.versonotebooks.com/share/github/DataficationSDK/Verso/blob/main/samples/showcase/slide-studio/slide-studio.verso
That link opens the notebook as a page: its prose, its code, and the outputs the file was saved with, which here is a table of regional numbers, a bar chart, and a printed summary line. Everything after the host is untouched, so you can make the change in the address bar without looking anything up. If you would rather paste than edit, the share page has a box that does the swap.
GitLab and gists follow the same shape:
https://gitlab.com/group/project/-/blob/main/analysis.verso
https://www.versonotebooks.com/share/gitlab/group/project/blob/main/analysis.verso
https://gist.github.com/user/2b1f0c9e4a
https://www.versonotebooks.com/share/gist/user/2b1f0c9e4a/analysis.verso
GitLab projects nested several groups deep work as written. A gist needs the file name on the end, because it can hold more than one file.
What the page does, and what it will not do
Nothing is uploaded. There is no copy of your notebook on our side to go stale, because the page is built from the file already in your repository. Commit a change and the link shows it.
Nothing is executed, on the page or anywhere else. The notebook renders as a document, in a sandbox with no access to the site around it. A cell that expects a live kernel shows only what it last saved, and a reader who wants to run it downloads the file.
Which means the page shows whatever the file already contains. A notebook saved with its outputs shows its charts, tables, images, and diagrams. One committed after clearing outputs shows the code alone. Worth knowing before you paste a link into a review: strip outputs before committing and the reader gets source and nothing else.
Three formats, no conversion step
| Format | How the page reads it | Outputs shown |
|---|---|---|
.verso |
The native format, read as written | Whatever the file was saved with |
.ipynb |
Read directly, including older notebooks | Whatever the file was saved with |
.md |
Split into cells the way the editor splits one | None, the format does not persist outputs |
The Jupyter row is the one that surprises people. There is no convert-then-share step: point a share link at an .ipynb in a public repository and it reads.
The Markdown rule is the one the editor uses. Prose stays prose, and a top-level fenced block tagged with a language Verso knows becomes a cell of that language, so a shared .md is cut into the same cells you see in the editor. A bare fence, or one tagged with a language Verso does not run, stays prose.
Relative links and images keep working
A markdown cell that says  is asking for the file beside it in your repository, and that is where the page fetches it from, so a notebook that leans on a folder of figures reads the same here as at home. Relative links work the same way: one pointing at another notebook, or at a Markdown or Jupyter file, opens as a page here rather than on the forge, so you can read a folder of notebooks straight through. Everything else opens on the forge, and a full address is left exactly as you wrote it. Every page carries a View source button.
The catch is the obvious one. Those files have to be public too. A figure in a private repository is no more reachable than the notebook would be.
A link that keeps showing what it showed
A link to a branch shows whatever that branch holds today, which is what you want in a README. A link that has to keep showing the same thing, in a paper or an issue thread, should name a commit instead:
https://www.versonotebooks.com/share/github/owner/repo/blob/9f2c1ab.../analysis.verso
GitHub writes that link for you: press y while viewing the file and the address bar swaps the branch name for the commit it points at. Copy it then, and the link keeps showing what it showed the day you shared it.
A badge, and a link preview
Every shared page offers the markdown for a badge, ready to paste into a README beside the notebook:
[](https://www.versonotebooks.com/share/github/owner/repo/blob/main/analysis.verso)
Share links also carry the notebook's title and opening paragraph as page metadata, so pasting one into Slack, Discord, or a social post produces a card describing the notebook. The title comes from the notebook's own when it has one, otherwise from the file name.
The limits, stated up front
Files have to be public and under 5 MB. Private repositories are not reachable by design: there is no place to put a token, so there is nothing to leak. Notebook pages also ask search engines not to index them, because they reproduce files that belong to other people. A share link is meant to be handed to someone.
Why we built it this way
The alternatives all involve a copy. Export to HTML and the copy is stale the next time you run the notebook. Upload to a service and the copy lives somewhere else, with its own permissions and its own account to keep.
A URL that names the file in your repository makes nothing. It is a view, in the database sense: nothing to keep in sync, nothing to revoke, nothing to migrate when the repository moves. The link breaks when the file moves, which is what you want from a pointer.
The quickest way to find out whether it suits your repository is to open a notebook on GitHub, edit the host, and press Enter. The Sharing a Notebook guide covers every URL form, and it went out alongside the 1.2 releases.