jupyter-book: Allow content that is not in a subdirectory of the book

I would like to organize my project like this:

TopLevelOfRepo
    mybookname
        _toc.yml
    notebooks
        chap00.ipynb

In _toc.yml, I expected to be able to write

- file: ../notebooks/chap00

But that doesn’t work – it says it can’t find chap00.ipynb.

Is there a reason for this restriction? Or am I doing something wrong?

About this issue

Original URL
State: open
Created 4 years ago
Reactions: 2
Comments: 17 (8 by maintainers)

Most upvoted comments

@redelmann Since opening this issue, I have found that I actually prefer to copy files from other directories into my jupyter-book build directory. In some cases I have to change file names; in other cases I run scripts to make changes in the notebooks themselves. And it helps me keep versioning straight. Not sure if this helps with your use-case, though.

AllenDowney on May 20, 2021

Just a quick note on cluttering up the repository. @AllenDowney you mentioned that Jupyter Book will create a lot of extra files - just a note that these will all be in a _build folder, and generally speaking you wouldn’t include that folder with your github repo anyway (usually folks set up a github action to auto-deploy the repo to a website or something, see here for some ideas).

That means your repository on github could just look like

page1.ipynb
page2.md
...
_config.yml
_toc.yml

and when you build the book, it would create a _build folder that you wouldn’t need to check into git. That’s the only folder that Jupyter Book will generate. (this is different from what Jupyter Book used to do, which included all of the files for a Jekyll website in the root of the repo, but it now uses Sphinx so we don’t have to do that anymore 😃 )

Just wanted to clarify that in case it wasn’t clear!

choldgraf on Sep 15, 2020

@phaustin Cool. That looks really good!

One minor thing: in the footer the spelling of my name is Allan rather than Allen.

Let me know when you are ready for readers and I will tweet about it.

Fixed thanks – I’ll be putting together a more comprehensive website about our plans for scaling all of this up and will let you know. We should have something to share prior to the AMS meeting in January: https://ams.confex.com/ams/101ANNUAL/11python/papers/viewonly.cgi?password=582729&username=384767

phaustin on Sep 15, 2020