How settings work in rustdoc

Rustdoc has a few well-hidden features in its settings page, plus the "paintbrush" thing on the top bar (which is going away). To make this work, rustdoc stores the settings in localStorage, which isn't actually browser cookies, but your browser probably treats them the same (usually, it's kept in a "Site Data" tool for tracking storage usage and clearing them.

The essential part of security in cookies and localStorage is the idea of an "origin", which is supposed to match roughly with what people intuitively think of as a website, so each "website" gets its own local storage:

• On the regular web, an origin is an effective Top-Level Domain, plus access protocol, based on the Public Suffix List. This means docs.rs and doc.rust-lang.org use separate rustdoc settings.
• On local machines, it's likely to treat every single file as its own origin, though technically it's browser-specific. This means that every single rustdoc page that you generate in cargo doc will get its own settings, which can be pretty annoying. If you wonder why your rustdoc theme randomly switches around with local docs, this is why.

Since this problem can't really be fixed in rustdoc (it's mostly the browser sandbox being a bit over-zealous), we need to work around it.

How rustdoc-settings-sync works

There's three different JavaScript files with distinct roles in here:

• content-script.js: This is the part that does "the important work." It loads your rustdoc settings from addon-side storage and injects them into the web page when it loads. It also hijacks rustdoc's updateLocalStorage function, so that when settings get changed, it sends a message to background.js, and it listens for messages coming from background.js, so that if settings are changed in another tab, this one will get updated.
• options.js and options.html: This runs if you open the add-on's own settings page. It has the same options list you see in rustdoc itself, and if you change settings, it sends out the "pushAllLocalStorage" to tell all the tabs to reload all their settings. This is be redundant, since rustdoc's own built-in settings page should work fine, but it's here just for discoverability purposes (you can click the settings button in your browser, instead of having to figure out where it is in rustdoc).
• background.js (and background.html, which is just a placeholder, and will probably go away in a future version of this extension): This is essentially just a router. To avoid creating infinite loops, it also checks if the settings don't match before forwarding things around, and sends a message to every single tab if they don't. The main reason why this exists is so that if you change your theme in one tab, the other tab will automatically update, and unfortunately there's no browser feature for sending messages directly between tabs: you have to go this way.

When does rustdoc-settings-sync not work?

This addon is set up to respond to docs.rs, doc.rust-lang.org, localhost, and file URLs. This should cover more than half of people's rustdoc usage, but it's not all of them, and there's no real plan to extend this list.

The reasoning behind limiting this list, even though this add-on already checks to make sure it's actually talking to a rustdoc page, is to prevent this add-on being used as a browser fingerprinting vector.

How to install

It's available for Firefox, Chrome, and Edge.