I have a Jupyter notebook that I want to display on GitHub. The notebook contains a table of contents section with anchor links that point to different headings throughout the document. When I run this notebook on my local machine using Jupyter, all the internal navigation works perfectly. I can click any link in the TOC and it jumps right to that section.
But when I upload the same notebook file to my GitHub repository, the internal linking stops working completely. Every time I click on one of these anchor links, instead of scrolling to the target section, GitHub redirects me to the main repository page.
This is really frustrating because the navigation is important for users to move around the notebook easily. Has anyone encountered this issue before? What’s the best way to make internal links work properly in GitHub-hosted notebooks?
Hit this same issue last year sharing research notebooks with my team. GitHub strips out HTML content for security reasons, which kills anchor functionality. I fixed it by switching to GitHub’s built-in markdown heading links - they auto-generate anchors you can reference with #heading-name-with-dashes. Had to redo my TOC but navigation worked again. You could also convert notebooks to GitHub Pages with Jekyll. More upfront work but keeps all the interactive stuff including proper anchors. Plus the pages look better and load way faster than GitHub’s default notebook viewer.
GitHub’s notebook renderer breaks anchor links - it strips out the HTML that makes internal navigation work.
Hit this same issue documenting our API. Wasted hours messing with markdown and HTML anchors, but GitHub kept breaking them.
Real fix? Automate publishing to a platform that actually handles anchors. I built a workflow that pulls notebooks from GitHub and auto-publishes to proper hosting.
Keep your source in GitHub but serve notebooks somewhere that preserves functionality. The workflow watches for changes, processes them, and deploys to hosting that keeps your TOC links working.
Best of both worlds - GitHub for version control, proper rendering with working navigation for users.
Same exact issue when I was sharing ML tutorials with students. GitHub’s notebook renderer strips out the HTML anchor elements that work fine in Jupyter locally. I fixed it by switching to standard markdown headers instead of custom HTML anchors. GitHub auto-generates linkable anchors for markdown headers, so you can reference them directly. Had to update my table of contents to match GitHub’s auto-generated anchor names, but then internal navigation worked perfectly. Just make sure your header text matches GitHub’s format - lowercase with hyphens for spaces. Bit of trial and error but way better than broken links.
totally agree, GitHub’s viewer is a pain for the anchors! nbviewer.org does do a much better job, just drop your link there and you’re good to go. makes navigating so much easier, really wish I knew this sooner!