That being said, another format that I like a lot is Markdown. It is a great format for writing documentation, and it can be edited/previewed in many editors and platforms[^1]. It naturally accepts all the programming languages that one can use in Jupyter. But there again, it’s easy to start, i.e. decide to represent Markdown cells as text, and include code cells within Markdown code cells prefixed with
```python, but it’s harder to go to the next step and decide how to separate consecutive Markdown cells, how to represent notebook or cell metadata, or as you mention, define which part of the code are executable, or not.
For now in Jupytext we have given the precedence to the principle that the text version should look like the notebook when previewed, and hence used e.g. HTML comments to represent the cell breaks and include the metadata, but that does make manual typing a bit cumbersome.
Regarding the idea of companion files, @takluyver, we did implement that in Jupytext, and it really is a great idea. It’s so convenient to be able to edit any of the representations, either text or
.ipynb. Also the complete notebook (with outputs and metadata) is always available in the
Finally, a word on outputs. I like very much the idea of saving them in a companion folder, in addition to the Markdown file, and I’d be curious to work on that when time permits. This way, we would avoid the duplication of the notebook inputs. And, if thinks were done well, we could directly use that representation of the notebook as the input for a Jekyll or Hugo blog post or chapter… But maybe that leads to too many other questions (e.g. how to include the ouputs in a Markdown file?)!
[^1]: for that reason I have a preference for Markdown with
.md extension rather than for R Markdown with