How can I reference a relative directory in _toc.yml

[canyon289]

Hi,
I'm having trouble getting jupyter book to find my notebook files. I would like to structure my jupyter book as follows

toplevel/
  - jp_book_config/
    - _config.yml
    - _toc.yml
  - notebooks
    - chp_01.ipynb
    - chp_02.ipynb

What's the correct way to reference the notebook files? Here's my current _toc.yml. I run jb build jupyter_book/from the toplevel directory but I get a not found error from toctree.

format: jb-book
root: index
chapters:
  - file: ../notebooks/chp_01.ipynb
  - file: ../notebooks/chp_02.ipynb

What should I set for the filepath string?

And thanks for creating jupyterbook, its quite a nice library!

Here's the versions

Jupyter Book      : 0.12.1
External ToC      : 0.2.3
MyST-Parser       : 0.15.2
MyST-NB           : 0.13.1
Sphinx Book Theme : 0.1.7
Jupyter-Cache     : 0.4.3

[OriolAbril]

In "pure" sphinx that means having separated conf and source directories. All source files for the sphinx project need to be in the source directory or its subdirectories.

I think you'll be able to simulate that with the config and toc flags: https://jupyterbook.org/reference/cli.html#jupyter-book-build when using jupyter build but I'm not completely sure.

[zoldello]

@canyon289 Did you ever figure this out?

[canyon289]

I did not unfortunately

[choldgraf]

You should be able to define other locations for the configuration (_config.yml) and the Table of Contents (_toc.yml) ivia the --config and --toc parameters when you call jupyter-book build.

For example, if you have a folder structure like:

mybook/
├── config
│   ├── _config.yml
│   └── _toc.yml
└── mynotebooks
    ├── index.md
    └── page1.ipynb

You should be able to build the book in the way you describe via:

First, Navigating to the parent folder of mybook/.

Next, running this command:

jupyter-book build mybook/ --toc config/_toc.yml --config config/_config.yml

What about relative paths?

When thinking about sub-folders, relative paths, etc, you should reference those files relative to the root document, not relative to the _config.yml file.

[zoldello]

@choldgraf Thanks. I had to take out
--toc config/_toc.yml

to get it to work. In _toc.yml, I tried to reference mynotebook /page1.ipynb with something like

/mybook/mynotebooks/page1.ipynb
and
/mynotebooks/page1.ipynb .
and
page1.ipynb .

Neither worked and I get an error along the lines - WARNING: toctree contains reference to nonexisting document 'mynotebooks/page1.ipynb' [etoc.ref]

[choldgraf]

The entries in _toc.yml need to be relative to the root document (AKA the first one defined). Where is your root document for that book? A URL that reproduces your problem would be helpful!

[zoldello]

The entries in _toc.yml need to be relative to the root document (AKA the first one defined). Where is your root document for that book? A URL that reproduces your problem would be helpful!

Here is a link to github fork I made of the code
https://github.com/zoldello/nwb_datajoint

The jupyter-book code is in -
./docs/web-doc

The command that built is
clear && jupyter-book build --path-output ./docs/web-doc/ --config ./docs/web-doc/_config.yml docs/web-doc/

What I need to do is reference ./notebooks/* (which contains .ipynb files) and use it in ./docs/web-doc. The _toc.yml file cannot see the files in ./notebooks. I need this to work so I can use those .ipynb files and other files at the root like License file.

Let me know if you need more information.

[choldgraf]

ah - I believe as-is, that won't work. Content files need to be in the same directory, or a sub-directory, of the root document.

One workaround for this is to create files in the locations you want within your book, and use an {include} directive that points to the files you'd like to include. For markdown, if you had these file structures:

book
├── mybook
│   └── index.md
└── othermarkdown
    └── page.md

You could include it by adding a new page in mybook, with the following location:

root/
├── mybook
│   ├── index.md
│   └── page.md
└── othermarkdown
    └── page.md

and adding only the following content to the new page:

```{include} ../othermarkdown/page.md
```

Then you could include the mybook/page in your _toc.yml file and it'll import the content.

I'm not sure how this would work for .ipynb files, but you could try the same approach and see if that works?