Report on issues

notebook.md

@@ -36,31 +36,43 @@ code.
 Ideas can change, and many turn to a form of version control to track
 changes.
 
-![PhD Comics by Jorge Cham]
-(https://swcarpentry.github.io/git-
-novice/fig/phd101212s.png)
+![PhD Comics by Jorge Cham][phdcomic]
 
-
-However, the underlying format of notebooks is
-JSON. It is relatively difficult to see changes to JSON objects in classic tools
-like [diff](http://man7.org/linux/man-pages/man1/diff.1.html).
+However, the underlying format
+of notebooks is
+JSON. It is relatively difficult to see changes to JSON objects
+in classic tools
+like [diff][diff].
 
 There is still
-not consensus on how to put Jupyter notebooks in version control. 
+not consensus on how to put
+Jupyter notebooks in version control. 
 See
-[here](https://stackoverflow.com/questions/18734739/using-ipython-notebooks-
-under-version-control), 
-[here](https://nextjournal.com/schmudde/how-to-version-
-control-jupyter), 
-[here](https://towardsdatascience.com/version-control-with-
-jupyter-notebooks-f096f4d7035a), with varied solutions like
-[nbdime](https://nbdime.readthedocs.io/en/latest/),
-[nbstripout](https://github.com/kynan/nbstripout), or
-[jupytext](https://github.com/mwouts/jupytext). 
+[here][j1], 
+[here][j2], 
+[here][j3],
+with varied solutions like
+[nbdime][nbdime],
+[nbstripout][nbstripout], or
+[jupytext][jupytext]. 
 
 Here, I will use
 [notedown](https://github.com/aaren/notedown) to work with `.md` files in
 Jupyter Lab, and use [git](https://git-scm.com/) for version control.
+[phdcomic]: https://swcarpentry.github.io/git-novice/fig/phd101212s.png
+[diff]:
+http://man7.org/linux/man-pages/man1/diff.1.html
+[j1]:
+https://stackoverflow.com/questions/18734739/using-ipython-notebooks-under-
+version-control
+[j2]: https://nextjournal.com/schmudde/how-to-version-control-
+jupyter
+[j3]: https://towardsdatascience.com/version-control-with-jupyter-
+notebooks-f096f4d7035a
+[nbdime]: https://nbdime.readthedocs.io/en/latest/
+[nbstripout]: https://github.com/kynan/nbstripout
+[jupytext]:
+https://github.com/mwouts/jupytext
 
 ```{.python .input  n=5}
 bool("Markdown") and bool("Jupyter")
@@ -79,13 +91,15 @@ bool("Markdown") and bool("Jupyter")
 ]
 ```
 
-
 ## Setup
 First, boot up Jupyter Lab.
 
 Let's install notedown [directly from the
-notebook](https://jakevdp.github.io/blog/2017/12/05/installing-python-packages-
-from-jupyter/):
+notebook][jakevdp]:
+
+[jakevdp]:
+https://jakevdp.github.io/blog/2017/12/05/installing-python-packages-from-
+jupyter/
 
 ```{.python .input  n=3}
 import sys
@@ -126,15 +140,61 @@ LINE_TO_ADD = "c.NotebookApp.contents_manager_class = 'notedown.NotedownContents
 
 <br/>
 
-If you're following along, you can relaunch Jupyter, and create a new Markdown
+If you're following along, you can relaunch Jupyter, and create a new
+Markdown
 file. Once you create the file,
-right-click and `Open With -> Notebook`.
+right-click and `Open With ->
+Notebook`.
 !["Open With" image](open-with.png)
 
+## Issues
+Not everything is perfect. Here are the issues I've seen:
+1. **Links
+wrap, and occasionally get spaces added to them.** This makes it harder to click
+Markdown links, because they no longer work. One solution is to reference links
+(see examples [here][md-cheat]).
+2. **Sometimes, Markdown cells get pasted
+together.** It can be easier to edit Markdown cells in smaller chunks. To
+separate them, I sometimes add little code snippets.
+3. **Github doesn't render
+the markdown as a notebook!** Maybe if more people use it, they can try it out.
+As a compromise, I converted to notebook-output.pdf for you to read online :)
+This was done with the below code:
+```
+notedown notebook.md > notebook-
+output.ipynb
+jupyter nbconvert --to html notebook-output.ipynb
+```
+[md-cheat]:
+https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#links
+
+```{.python .input}
+
+```
+
+```{.python .input  n=25}
+for i in range(3):
+    print("~"*9 + (":-)" if i==1 else "~~~") + "~"*9)
+```
+
+```{.json .output n=25}
+[
+ {
+  "name": "stdout",
+  "output_type": "stream",
+  "text": "~~~~~~~~~~~~~~~~~~~~~\n~~~~~~~~~:-)~~~~~~~~~\n~~~~~~~~~~~~~~~~~~~~~\n"
+ }
+]
+```
+
 ## Sample project
 
 ## Thanks!
 
 Check out the latest [Jupyter Lab
 interface](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html)
 for working with notebooks in a friendly, responsive way.
+
+```{.python .input}
+
+```