Add a brief guide to choosing between .md and .ipynb#1969
Conversation
|
choldgraf
changed the title
.md and .ipynb
Thanks! It's a good document, but doesn't fully address my use case and needs, where us tutorial repo maintainers decided on markdown (exactly for the pros listed here), but then the user comes panicking and starts a debate that they don't want to use markdown. |
| @@ -0,0 +1,31 @@ | |||
| # How to choose between `.ipynb` and `.md` when writing Jupyter notebooks | |||
|
|
|||
| You can work with Jupyter notebooks in both the `.ipynb` format as well as in a text-based format like [MyST Markdown](./notebooks-with-markdown.md). This is a brief guide to help you choose when to use one vs. the other. | |||
There was a problem hiding this comment.
Maybe add one more sentence that working in jupyper/jupyterlab the user experience will be the same, they don't usually notice the difference between the formats assuming the required dependencies, jupytext and maybe jupyerlab-myst, are installed.
|
What's the main thing we are missing here @bsipocz ? Could you suggest one or two "section headers" and I can try to flesh it out with content? |
Co-authored-by: Brigitta Sipőcz <b.sipocz@gmail.com>
|
@bsipocz I added an extra section about reading/writing the two formats. I think that addresses your question. What do you think? |
bsipocz
left a comment
bsipocz
left a comment
There was a problem hiding this comment.
Thanks @choldgraf, this new edits addressed my points.
|
|
||
| **`.md`** is a plain text file with markdown inside. It is more human-readable, and slightly less-structurd than JSON files. It focused on the **input cells** and **markdown cells** of a Jupyter Notebook, as well as **human-generated metadata** (like cell tags). Markdown notebooks **do not store outputs**. If you execute a cell with a Markdown-based Jupyter Notebook, then outputs will exist in your interactive session but not be saved to the `.md` file. This makes **code review and version control much easier** because you're only looking at markdown and some human-generated syntax for code cells. Finally, Jupyter UIs require installing either [Jupytext](https://jupytext.readthedocs.io/) or [JupyterLab-MyST](https://github.com/jupyter-book/jupyterlab-myst) to read markdown-based notebooks. | ||
|
|
||
| ### When to lean towards `.ipynb` |
There was a problem hiding this comment.
What about in a situation where you are interested in users being able to use the notebook on a JupyterHub instance? I guess this is effectively covered in the Out-of-the-box Jupyter UI support: but is it an example of a use case where .ipynb would be preferable?
There was a problem hiding this comment.
I think it depends less on the interaction context and more the nature of the work. If you're using a hub to share fast reproducible notebooks, then .md is probably preferred (and the image author should ensure that the relevant plugins are installed). Otherwise, you'd probably lean towards ipynb files.
There was a problem hiding this comment.
Got it. I guess I am thinking about instances in an instructional context (such as Berkeley's DataHub), but I guess that the request can be made to make sure that the relevant packages are available across the JupyterHub instance for the .md notebook rendering (or less ideally they can be installed locally each time).
There was a problem hiding this comment.
for instructional context I very strongly prefer md as those material coming from well curated and version controlled repos and are written with the purpose that the users are interacting with it, rather than a frozen in time science product. (e.g. I'm ok with an ipynb as an attachment to a paper or similar when it's more like a showcase that stuff did run at some time; rather than the all should still work and reproduce).
|
@choldgraf - when will this end up in the deployed website? I cannot really tell that from the configs, or if the website is tied to a released version or is from |
|
At the moment, I believe that the only way to update the mystmd.org docs is for @rowanc1 to manually deploy it. I've got this issue tracking the need to share that ability with other team members but we haven't actioned it yet: So for now there's nothing I can do. Rowan usually does this when there is a new release and/or whenever he has some spare cycles to do it. |
|
We do this on version releases, yes. Can get it done soon. |
…k#1969) * Add a brief guide to choosing between and * Update docs/md-vs-ipynb.md Co-authored-by: Brigitta Sipőcz <b.sipocz@gmail.com> * comments --------- Co-authored-by: Brigitta Sipőcz <b.sipocz@gmail.com>
5 participants
This is a brief guide to give users an idea for when to choose between markdown-based notebooks and
ipynbfiles. It's inspired by a conversation with @bsipocz in this discussion thread. The goal of this page isn't to tell users what to do, but to help them understand the pros/cons of each approach, and when they should consider using each format.@bsipocz if you have any thoughts (recognizing that we can't be too opinionated here, I'd rather give information than tell people they're "doing it wrong") on how we can make this content more useful, please provide suggestions!