Jupyter Book V2: Disabling Edit_url Sitewide - A Quick Fix

Jan 16, 2026 by Editorial Team 59 views

Hey everyone! Having a bit of a headache trying to disable the edit_url sitewide in your Jupyter Book v2 project? You're not alone! It seems like there's a quirky issue with how the configuration is handled, and I'm here to break it down and hopefully offer some clarity. Let's dive in!

Understanding the Issue

So, you're rocking Jupyter Book v2 and want to get rid of that pesky edit_url link that appears on your pages. You've tried adding it directly under the site: section in your myst.yml file, but you're greeted with this error:

myst.yml extra site options should be nested under \"options\" key: edit_url
myst.yml 'options' options cannot include reserved key edit_url (at myst.yml#config.site)

Okay, makes sense, right? It's telling you to nest it under options:. But, plot twist! When you actually do nest it under options:, you're hit with another error:

myst.yml 'options' options cannot include reserved key edit_url (at myst.yml#config.site)
myst.yml 'options' options cannot include reserved key edit_url (at myst.yml#config.site)

Frustrating, isn't it? It feels like you're stuck in a loop. What's going on here? Well, it seems like edit_url is a reserved key that Jupyter Book v2 isn't quite handling as expected when you try to set it at the sitewide level.

Possible Workarounds and Solutions

Alright, so what can you do about it? While a proper bug fix might be needed in the long run, here are a few workarounds you can try:

1. Theme Configuration (Recommended)

One of the most effective ways to globally disable the edit_url is by tweaking your theme configuration. Jupyter Book often provides a way to customize the theme settings, and this is where you can usually find the switch to turn off the edit button. This involves modifying the _templates/sidebar-primary.html file in your theme.

Locate the Theme Directory: First, find where your theme files are located. This usually involves checking your _config.yml or similar configuration file to see which theme you're using. Common themes include sphinx-book-theme.
Override the Template: Create a _templates directory in your book's root if it doesn't exist.
Customize the Sidebar: Copy the sidebar-primary.html file from your theme's directory to your newly created _templates directory. Now, you can safely modify it without altering the original theme files.
Remove or Comment Out the Edit Link: Open the sidebar-primary.html file and look for the section that generates the "Edit this page" link. This usually involves some Jinja templating code. You can either completely remove this section or comment it out using {# ... #}. Here's an example of what you might be looking for:
```
{# Remove or comment out this section to hide the edit button #}
{%- if page_source_suffix %}
<a class="reference external" href="{{ edit_url }}{{ page_source_suffix }}">
    <i class="fas fa-pencil-alt"></i> Edit this page
</a>
{%- endif %}
```
Rebuild Your Book: After saving the changes, rebuild your Jupyter Book to see the effect. The "Edit this page" link should now be gone.

2. JavaScript Snippet (Less Recommended, but Possible)

If the theme configuration doesn't give you the option, you can inject a JavaScript snippet to hide the edit_url button. This is a bit of a hack, but it can work in a pinch.

Create a JavaScript File: Create a new .js file in your book's directory (e.g., _static/custom.js).
Add the JavaScript Code: Add the following JavaScript code to the file:
```
window.onload = function() {
  var editButton = document.querySelector('a[href*="edit"]');
  if (editButton) {
    editButton.style.display = 'none';
  }
};
```
This code waits for the page to load, then finds any link with "edit" in the href attribute and hides it.
Include the JavaScript in conf.py: In your conf.py file, add the following to the html_static_path list:
```
html_static_path = ['_static']

def setup(app):
    app.add_js_file('custom.js')
```
Rebuild Your Book: Rebuild your Jupyter Book. The edit button should now be hidden.

3. Post Processing Script (Advanced)

For those comfortable with scripting, you could create a post-processing script that runs after the book is built and removes the edit_url links from the generated HTML files. This approach offers a high degree of control but requires more technical expertise.

Create a Script: Write a script (e.g., in Python) that iterates through the generated HTML files in your book's _build directory.
Remove the Edit Links: Use a library like BeautifulSoup to parse the HTML and remove the edit_url links.
Run the Script: Configure your build process to run this script after the book is built.

4. Monkey-Patching (Potentially Risky)

As a last resort, you could try monkey-patching the Jupyter Book code to disable the edit_url generation. This is generally not recommended because it involves modifying the core library code, which can lead to unexpected behavior and make it harder to update Jupyter Book in the future. However, if you're desperate, you could try:

Locate the Relevant Code: Find the code in Jupyter Book that generates the edit_url links. This usually involves digging into the library's source code.
Modify the Code: Comment out or remove the code that generates the links.

Again, be very careful when doing this, and make sure you have a backup of your Jupyter Book installation.

Why This Happens

The reason you're seeing these errors is likely due to how Jupyter Book v2 handles configuration and reserved keys. It seems like the edit_url key is treated specially, and there might be a conflict in how it's processed when you try to set it globally. This could be a bug or an oversight in the configuration parsing logic.

Bug Fix Needed

It sounds like a proper bug fix is indeed needed to allow users to disable edit_url sitewide through the myst.yml file without these workarounds. Hopefully, the Jupyter Book team will address this in a future release.

Thanks to the Jupyter Book Team!

Even with this little hiccup, massive kudos to the Jupyter Book team for their amazing work on v2! It's a fantastic tool for creating beautiful and interactive documentation, and these small issues are just part of the process of improving it. So keep up the great work, guys!

In Summary

While disabling edit_url sitewide in Jupyter Book v2 can be a bit tricky right now, there are several workarounds you can use to achieve the desired result. Whether it's tweaking your theme configuration, injecting a JavaScript snippet, or using a post-processing script, there's a solution for every level of technical expertise. Hopefully, this guide has been helpful, and let's all look forward to a proper fix in a future release!