http://copr.fedorainfracloud.org/coprs/npmccallum/nbde/ Look at the installation instructions of the above repo. The markdown is correct. However, code blocks have newlines stripped. Also, it resets the numbering on the ordered lists.
It would also be nice to get syntax highlighting support. Maybe we need to use a better markdown library? Perhaps something that supports all of the GitHub extensions.
I had a look at it and did some improvement on it (http://copr.fedorainfracloud.org/coprs/npmccallum/nbde/) but could not quite fix everything (i.e. list numbering resets seemed to be at least very hard to fix). We are using https://pythonhosted.org/Markdown/. We could perhaps consider some other lib. I agree that could be beneficial.
We have switched to using python-CommonMark and the resetting of numbering should be now fixed. Syntax highlighting is also on now but it doesn't work extremely well on shell snippets :(. Perhaps we could find some improvements there if new bug is filled for that.