Broken image links when publishing bookdown on GitHub pages

[neuranna]

This issue was raised earlier:

Troubleshooting broken images in bookdown hosted on gh-pages

Hi everyone, I'm having some issues getting image content to render on a bookdown site that we've been developing. The image paths appear to be correct, but the images aren't showing up on the rendered document. I've been hosting this document on a gh-pages branch that's built with Travis. PNGs are stored within a folder called /images, and figures generated with R code and knitr are stored in _main_files/figure_html/.... I've tried changing the output directory for these figures to main_files (i.e. remove the first underscore) without success. Has anyone encountered this before? Any insights would be greatly appreciated. The github repository can be found here.

But the solution didn't work for me (late 2020), so I'm sharing my own here.

Issue: bookdown saves images generated by the R code to a directory called /_main_files/figure-html. However, GitHub's default site generator jekyll ignores all directories starting with an underscore (_), so the image links broke when I tried to view the site online.

Solution: The problem can be solved by adding an empty file to the directory called .nojekyll, which disables jekyll. This works for us, since bookdown already generates a standalone site and doesn't need jekyll. What helped me specifically was adding .nojekyll to the same directory as the index.html file - usually it's the docs/ directory.

Hope this is useful.

[jtbayly]

You’ll also find this step mentioned in the bookdown book instructions for setting up a gh-pages workflow.

[neuranna]

Alas, I originally put .nojekyll in the root folder, which did not do the trick. And then it took me some time to track down the underscore issue and link it back to jekyll.

[jtbayly]

Ah. Yes, it has to be in the root directory of the content being served by Github Pages, which I think would be wherever index.html is, regardless of how everything is setup. Good catch.