Frequently Asked Questions

Why doesn't it work? It used to work, but recently it stopped working.

In early May of 2023 a new version (2023.04.8) was released, which is a major rewrite to comply with modern, cross browser web standards. The main difference from a user perspective is that, unlike before, your explicit permission is required to modify a page (which is how highlights are actually added to the page). With the old version, permission was implicitly granted for all sites just by installing it.

This permission is per site, meaning once permission is granted for any one page of a site, every page on that site (ie: each page that starts with the same site name) is allowed.

The extension is only allowed to ask for that permission in response to an explicit action you undertake, which in our case is one of the following:

• Clicking the pen icon in the toolbar (it may be hidden inside your browser’s extensions icon), and then, if present, clicking the Request Permission button.
• Making a new highlight on the page.

Until you do one of those, the extension appears to not be working because it hasn’t the permission to do anything.

If you’ve been automatically upgraded from the old version, you still need to give your permission for the extension to do what it used to do automatically.

There may still be other teething problems. Please be patient. I’m always investigating but I’m finding it hard to reproduce some problems.

There are other issues that I’m working through (see the next question), but unfortunately they tend to come to light only after a large amount of people use it.

Why is/was it slow (for some people)?

The transition to the new generation of web extension standards has both made some things impossible, and exposed some design decisions that were more easily masked before. The short answer is:

• The fast path for accessing the highlights database was forbidden (in the name of security), and it turns out that the slow path becomes really slow above a certain threshold.
• Every text snippet was displayed in its entirety for every page, increasing the likelihood of exponential memory usage.
• A single, massive highlight of the entire page (probably made by accident) wasn’t handled optimally, causing all page interaction to slow.

These choices became bottlenecks in all other areas, such as loading a page or making a backup (because the database is queried), or even just moving the pointer over a highlight.

With any luck these have been fixed in version 2023.05.14. Additionally, text snippets (the copy of the text taken from the highlight, and listed in the popup window, summary, options page etc) now only display the first 5000 characters by default, and require your explicit action to display the remainder. The range of the actual highlight is unaffected.

So in summary, while not highlighting the entire contents of War and Peace (accidentally or on purpose), for example, will give you a smoother experience, as of now that choice is still yours.

How can I use the old version?

I wrote the new version because support for the technology used to write the old version is in the process of being removed by Google. When that transition is complete, some time in 2023, the extension (and all other extensions which use that technology) will stop working, although that seems to be up for debate.

As the link also states, I can’t (re)publish an extension with the old technology, or update anything based on it.

If you’re desperate, and you understand how Chrome’s Extension Developer Mode works, I have uploaded the old version as a .ZIP file. But bear in mind:

• You’re now responsible for any further security issues.
• As Chrome will warn you when you install it, it’s going to stop working some time in 2023 anyway.

If you still want to do it, here’s how (Google Chrome or Microsoft Edge only):

1. Open your browser’s extensions page (or go to chrome://extensions in Chrome, or edge://extensions in Edge).
2. Enable Developer Mode
3. Download the old extension and unzip the file.
4. Click Load Unpacked, and select the folder containing the unzipped files.
5. Good luck, you’re on your own now.

Why do highlights sometimes go missing?

This is explained in more detail in the main help page, but basically the extension relies on the highlighted text being in the exact same location each time the page loads. More accurately this is the internal structural location, rather than the visible location. However there are many things that alter that structure of a web page, sometimes differently every time the page loads.

Mostly this is due to adverts being inserted, adverts being blocked (ad-blockers), or other extensions. For example, if an ad-blocker receives a configuration update, it may start blocking adverts that it didn’t before. Depending on where that advert was, it can alter the structural (though not visible) location of the highlight. So when the time comes to add the highlight back on the page, things aren’t where the extension expects it to be.

When this happens, the icon shows a red line across the icon. The text of the original highlight is still displayed in the popup window (albeit with a red dashed outline), but the reference to the place on the page is now broken (though you can still see the highlight in the Summary and Options pages).

How can I make highlights within highlights (aka Nested Highlights)?

This option was removed in the latest version because it obscured the more often requested desire to change an entire highlight’s style directly from the context menu. However, due to user demand it will be reintroduced in the forthcoming version 2023.05.10, but it will be disabled by default (UPDATE: as of version 2023.05.14 is it enabled by default). It can be enabled on the extension’s options page.

In the meantime there is a workaround:

• Assign a keyboard shortcut to a style.
• Select the text you wish to highlight.
• Invoke the keyboard shortcut.

How can I assign a keyboard shortcut to apply a highlight?

After selecting text, many prefer to make a highlight using a keyboard shortcut instead of using the menu. This can be done by using the browser’s built-in Keyboard shortcuts feature.

Chrome, Edge, Brave

• Go to the browser’s main extensions page (where all the installed extensions are listed). You can also manually navigate to chrome://extensions or edge://extensions.
• Click the menu button in the top-left corner, and select Keyboard shortcuts.

Firefox

• Go to Firefox’s settings page, then click Extensions & Themes, in the lower corner. You can also manually navigate to about:addons.
• Select Extensions in the list on the left side of the page, then click the cog icon alongside Manage Your Extensions.
• Choose Manage Extension Shortcuts.

You can assign shortcuts for any of the first 10 styles, and also for your default style, which applies to whatever you have currently assigned as the default highlight style.

Additionally, when a highlight has focus on the page (ie: it has an outline around it after being clicked on or selected with the TAB key), it can be deleted with the BACKSPACE key.

Why does the extension now require my permission?

As part of the new cross-browser web extension framework’s increased emphasis on security you must opt in at least once (per site) to every change the extension can make, meaning that for each unique site your explicit permission will be requested. This differs from the previous version, whereby simply installing the extension gave your implicit permission.

The extension requires a set of permissions to operate correctly.

• Read your browsing history.

  Technically speaking, this is composed of two specific permissions. The scripting permission is required to run the code that actually applies the highlights to the web page. The webNavigation permission is required so that after each new web page is navigated to, the extension can check whether its address is one for which it has highlights, so it can then try to apply them again to the page.

At no time does the extension use these events or information for any other purpose. No external services are used. Everything happens on your computer.

I give my permission but it doesn't work, and it asks again every time.

There are many possible reasons why permission isn’t granted even though you explicitly allow it, but my current theory is related to centralized browser management.

Chrome (and its derivatives, such as Microsoft Edge) can be configured as managed, meaning policies are put in place restricting what they the browser can do. As related to extensions, a policy could restrict the web stores they can be installed from, or only allow a subset of pre-approved extensions to be installed.

If you’ve seen the phrase “Managed by your organization” in your browser, it was probably enabled. This tends to happen within large companies, but it can also be enabled on a personal device. Apparently, Malware can also enable it.

One such policy limits the capabilities of installed extensions, such that even if you accept a permission request, it won’t be allowed. This extension requires the scripting permission, to make highlights on the page. If the permission can’t be granted, highlights can’t be made. Unfortunately, that permission is also required to show the alert to tell you that permission was denied. Therefore it appears to fail silently.

So, in short, my theory is something has put a policy in place to always deny an important permission request. As for how to turn off that policy, or management entirely, I’m afraid I have no idea.

You can check whether your device is managed at chrome://management, and if so the policies in place at chrome://policy (replace chrome with edge for Microsoft Edge).

How do I highlight a PDF file?

A PDF file is unrelated to a web page, even though it can be embedded within one. There are many PDF-specific highlighters available.

How can I synchronize my highlights between my browsers?

As of the time of writing, you can’t. Synchronization requires a server, which requires infrastructure, which requires time & money, of which I have neither. The closest current workaround is using the backup and restore function, but as stated in their descriptions above, these are currently in an experimental state. Caveat emptor.

Where are the highlights stored?

Highlights are stored in a database that remains private to the extension. It stays on your computer, and does not get uploaded or download to any server.

How can I save a web page with the highlights "baked" into it?

The browser’s normal Save functionality should include the highlights, but only the following formats are supported:

• Web page, Single File (Chrome, Edge, Brave only)
• Web page, Complete

Is it available for other browsers?

Almost! The benefit of new web technologies is that porting becomes much easier. Once it settles down on Chrome and Edge I’ll release it for Firefox, and Opera (maybe). It should also work in by default in Brave via the Chrome Web Store.

Safari is a work in progress, but it’s far more complicated.

How can I create a diagnostics file?

A diagnostic file is a file containing information about the extension, and a copy of your highlights database. However, this database has been scrubbed of all personally identifiable information (page titles, web site addresses, snippet contents), and so should be safe to help me track down bugs. You can (and probably should) view the file yourself to double check I haven’t missed anything.

You can find the “Save Anonymous Diagnostics” button in the “About” section of the Options page.

I have a backup of my system files (Windows Backup, Time Machine for macOS etc). Can I use that backup to "restore" my highlights?

You can, but bear in mind you’re fiddling with things that weren’t designed to fiddled with, so this isn’t guaranteed to work. This is moderate to advanced level stuff, so take a backup beforehand. Much of this is take from Chromium’s User Data Directory documentation, and is correct as of Chrome 113. Also, make sure Chrome is fully closed beforehand.

Chrome stores its data in a profile specific folder. Visit chrome://version, and copy the Profile Path text. This is the folder containing your settings, cache etc, and is where the following folders are located.

The extension uses Chrome to store its information in two areas:

Local Storage

This is where the style of each highlight is stored, alongside various other settings. This corresponds to the Local Extension Settings subfolder, which will contain a folder named hhlhjgianpocpoppaiihmlpgcoehlhio (this is the extension’s ID).

IndexedDB

This is where the database that associates the web site url with the location of highlights on its page (and various other metadata) is located. It corresponds to the IndexedDB subfolder, and should containing at least one of these folders.

• chrome-extension_hhlhjgianpocpoppaiihmlpgcoehlhio_0.indexeddb.leveldb
• chrome-extension_hhlhjgianpocpoppaiihmlpgcoehlhio_0.indexeddb.blob (this might not be present)

As far as I can tell you can replace the entire contents of both of these folders, as a form of “backup”. Obviously, how you access your original files from your backup is something you’ll have to figure out yourself.

What does it mean to "trim" a highlight?

When you make a highlight, various bits of information are stored about it, including the address of the page on which it is located, its start and end position, and its style. Also included is the textual content of the highlight, aka its “snippet”. This is because, should the highlight not be locatable on the page in the future, you at least will still know what it contained.

Text snippets were intended to be small in length, as most highlights tend to be. However, there is no practical limit to their length. It’s possible to accidentally make a huge highlight, and thus a huge snippet. This can slow things down because, although it will never be needed, it still needs to be processed, stored, and included in backups.

With this in mind, from version 2023.05.16 it is possible to trim a highlight. If the highlight’s snippet is over 5,000 characters long, and you choose to “trim” it, the following will happen:

• All but the first 5,000 characters of the snippet are removed.
• A scissors icon is shown after the text to indicate it is trimmed.
• A reference to the original source of the text is added.
• When the full text of the snippet is needed (for example, when clicking the “more” button), the original page is loaded, and if the highlight can be found on the page, its full text is used as the snippet.

There are advantages and disadvantages to this. It can significantly reduce the size of storage & backup files, and make things run smoother. However, it now requires that the original page be open and the highlight be locatable. If that isn’t possible, you’re left with just the first 5,000 characters of your snippet. Note that if the original page isn’t open (usually when interacting with Options page), it will be opened first, then you must manually try again (this is a browser limitation).

Whilst you should consider trimming a highlight, you’re not required to. The functionality should be the same either way.

Can I rely on this extension?

No. This was written a long time ago, only to suit my specific needs at the time. There are many ways for things to go wrong, some of which I’m discovering for the first time after over a decade. Whilst I make my best effort to keep it working, mistakes will be made. In short, if you rely on your highlights, use a service that guarantees their integrity. I’m sure they’ll be glad to take your money.

How many highlights can I make?

The number of highlights you can make is only limited by the space the browser allows the extension to store the details of those highlights, which is practically extremely large.

The real question is not whether you can but whether you should. There are instances of databases with multiple hundreds of thousands of highlights, and whilst it will work, albeit slowly, when I designed it many many years ago I never envisaged that amount. Every time you visit any web page, the database is consulted for potential highlights, and the larger the database the slower that process is. Also, the ‘Pages’ section of the ‘Options’ page must enumerate every site for every highlight. Hopefully these processes aren’t slow, but they’re not nothing either. Large databases also increase the probability of the browser removing the database when it has more urgent storage requirements.

I’m reluctant to add an “automatic pruning” feature, because it’s not for me to say what highlight is important to you, but I strongly recommend that, instead of using the extension as an archive of every highlight you ever make, you make a regular habit of removing the individual highlights (or entire pages) for things you no longer need. This will lead to smoother running, a lower memory and storage footprint, and a better overall experience with the extension. This can either be done from the popup window (for a specific page), or the Options page (for multiple items).