adding jupytext support

[choldgraf]

This adds support for using Jupytext to build/run markdown files. This would
let people store a notebook of content as a text file which makes it much
easier to collaborate on and diff.

Two main changes:

• All md files are now converted to in-memory notebooks before converting to HTML. This will also standardize what pages look like.
• Any md file that is a Jupytext format will be run before being converted to HTML.

cc @mwouts in case he's got ideas for how this could be done better! (though it was awesomely easy with the Python interface :-) )

[mwouts]

Awesome - I love this! It will become so easy to convert pre-existing Markdown books to a Jupyter Book!

I will contribute two very minor comments to the code, and answer your question on how to identify if the file did contain metadata.

@choldgraf , may I ask you two more questions:

• How should Jupyter Book handle the case when two documents have the same name, but one with .md and the other one with an .ipynb extension? Do you plan to ignore the .md one? I am asking as some people may want to push both paired files to their repo.
• Do you plan to support any other Jupytext extension? I am thinking in particular of
  • the .markdown extension, used by Elegant Scipy
  • R Markdown - would be fun to compare Jupyter Book with Bookdown on the same repo!
  • Python scripts with Jupytext metadata, in case a Jupytext user prefer that format over Markdown
  • Sphinx-gallery scripts found in the matplotlib gallery...

[mwouts]

I think you want to test that the metadata notebook_metadata_filter is -all. I will explain this with a bit more detail at mwouts/jupytext#320

[choldgraf]

OK I think I addressed the two suggestions that you gave, thanks for that guidance!

The one thing I'm still not sure on is how to handle multiple files with the same name but different extensions. Right now, it'll loop through these file extensions and stop once it hits an extension that exists in the file system:

https://github.com/jupyter/jupyter-book/pull/280/files#diff-a82c2ce5f9aced2282395a242550e422R15

What do you think about that? The reason I'm preferring ipynb is because this will allow the book to be built without re-running the code each time (AKA, we can cache the outputs).

I think that it's probably OK to leave this open as an issue to tackle in the future once more people have had a chance to play around with it. What do you think?

[mwouts]

Thanks Chris for being so receptive! I'm glad I could help. By the way, I do agree with your choice to give precedence to .ipynb over .md, it makes perfect sense, maybe a follow-up issue is not even required?

[choldgraf]

Cool! I'm gonna merge this one then, and give folks a chance to play around with it a bit before we make it official in a release :-)

[mwouts]

Oh sure... I'm going to try this very soon!! Thanks Chris.