NBDEV with starting jekyll locally has broken links

Hi there,
to reproduce my problem with broken links to the module pages,
I’ve installed the actual nbdev dev version (1.0.2) and created a test project (nbdev_new test) with the necessary changes in settings.ini.
After a nbdev_build_lib and nbdev_build_docs, I’ve started the docs locally with “make docs_serve”.

The link to the core module was broken, because in the directory “_site” the file is not in the root and named core.html but it exists in core/index.html.

I’ve uploaded some additional screenshots.
The same problem exists in my personal ongoing nbdev project

Thanks a lot for help


There was recently a commit that changed the way the default sidebarbar is built. The way it worked before was to link to “core”. A browser would interpret such a link to go to “core/index.html”.

However, said commit changed the links in the sidebar to instead go to “core.html”. The easy fix for now is:

  1. Go to your docs folder, edit _config.yml
  2. At the bottom there’s a line that says “permalink: pretty”. Uncomment that line.
  3. Re-generate your documentation

This works because without the permalink:pretty option, jekyll creates the module pages as “module.html”, not “module/index.html”.

I’ve opened an issue on github that describes this problem. I’m not sure why the change was made in the first place, so I can’t really guess what a good (permanent) solution would be. Is anyone aware of a “discussion place” for nbdev related topics?

1 Like

Thank you Olli for help and for the github issue.
(By the way “fastai users -> nbdev & fastpages”?)

Best regards