Jupyter-book: Ensure relative links in markdown work in the HTML

[choldgraf]

@mwcraig mentioned that relative links in the markdown / notebooks sometimes do not resolve properly when the site is converted to HTML. @mwcraig could you provide an example of where this kind of thing breaks so we can try designing around it?

[mwcraig]

Sorry for the delay -- the context for this is that I want links between notebooks that will work if someone clones the notebooks and runs them in Jupyter and I want those links to work between the rendered HTML pages in jupyter book.

An example is at https://github.com/mwcraig/ccd-reduction-and-photometry-guide/blob/master/notebooks/02-01-Calibrating-bias-images.ipynb?short_path=1129ddd#L68

The link [Preface notebook](00-00-Preface.ipynb) does not, by default, work in the rendered book because 00-00-Preface.ipynb isn't part of the rendered book.

I do have the links working in the rendered version of the book; this rendered page is at https://mwcraig.github.io/ccd-as-book/02-01-Calibrating-bias-images.html#data-for-these-examples

In my case I have a separate repo for the source notebooks, which does not store the notebooks with output, and the repo for the book, which has the executed notebooks.

I'll add another comment in a moment with a link to the code I used to transform the links. I'm happy to contribute it here but would need some guidance as to where to put it (also fine if it doesn't make sense for it to be here).

[mwcraig]

Here is the code I wrote for replacing the links. In the workflow I'm using now, this is done after I've run nbconvert to execute the notebooks and generate output.

https://github.com/mwcraig/ccd-reduction-and-photometry-guide/blob/master/notebooks/process_for_book.py#L79

[choldgraf]

hey @mwcraig - any chance you could add your functions to the jupyter-book build process? I think that this is a pretty common issue and it'd be a helpful fix for others! You could put the "find links and replace w/ new extension" stuff here:

https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/utils.py

and then call it just after creating the HTML here:

https://github.com/jupyter/jupyter-book/blob/master/jupyter_book/page.py#L111

What do you think?

[mwcraig]

Sure, I should be able to do that this weekend.

[choldgraf]

Bumping this one to v0.7.0 since I think we shouldn't block 0.6.4 on this one...@mwcraig it'd be awesome to see this functionality in Jupyter Book if you still have the time!

[mwcraig]

Only one more week of classes, only one more week of classes, only one more week of classes...

[choldgraf]

Closing as this should be superceded by beta.jupyterbook.org