Bibliophage Documentation

Bibliophage is a Chrome extension that captures research sources as you browse, tracks your reading progress, lets you annotate with color-coded notes and highlights, generates citations in five formats, and organizes everything in a full-featured dashboard — all stored locally on your device.

What Bibliophage does

• Captures sources automatically on 20+ academic websites — arXiv, PubMed, JSTOR, Springer, and more.
• Tracks how far you've read and resumes exactly where you left off on the next visit.
• Lets you annotate any text selection with a color-coded note directly on the page.
• Generates citations in APA, MLA, Chicago, BibTeX, or your own custom format.
• Organizes your library with collections, tags, search, and a full dashboard.
• Exports your research to JSON, BibTeX, Markdown, CSV, or plain text at any time.

Installation

Bibliophage is available on the Chrome Web Store and works on any Chromium-based browser (Chrome, Edge, Brave, Arc).

From the Chrome Web Store

1. Click "Add to Chrome" on the Bibliophage store listing page.

2. Chrome will show a permissions dialog — click "Add extension" to confirm.

3. The Bibliophage icon appears in your toolbar. Pin it by clicking the puzzle-piece icon → pin icon next to Bibliophage.

4. The onboarding page opens automatically on first install. It walks you through choosing your default citation format and takes about 30 seconds.

Developer / Unpacked Install

1. Download or clone the source files to a permanent folder on your computer. Do not move or delete this folder after loading.

2. Open Chrome and navigate to chrome://extensions/

3. Enable Developer mode using the toggle in the top-right corner.

4. Click "Load unpacked" and select the bibliophage/ folder.

5. The extension loads immediately. Pin it in the toolbar for quick access.

Source Capture

Bibliophage can capture any web page as a research source — automatically on recognized academic sites, or manually on any page you choose.

Auto-Capture

When you visit a recognized academic domain, Bibliophage automatically extracts the source's metadata (title, authors, journal, publication date, DOI, abstract) and saves it to your library. A gold toggle button appears on the right edge of the page to confirm tracking is active.

Auto-capture respects your settings — you can disable it globally or remove specific domains in Settings.

Force-Capture Any Page

For any site that isn't auto-captured (news articles, Wikipedia, blog posts, institutional repositories), you have three ways to manually capture it:

• Press Alt+T
• Right-click the page → Track This Page (Bibliophage)
• Click the gold toggle button if it's already visible and the sidebar opens

Force-capture always saves the source regardless of domain, using the same metadata extraction pipeline as auto-capture.

What metadata is captured

Bibliophage reads metadata from multiple sources in this priority order:

1. citation_* meta tags (used by Google Scholar, arXiv, PubMed, Springer)
2. OpenGraph tags (og:title, og:description, og:site_name)
3. JSON-LD structured data (ScholarlyArticle, Article, NewsArticle, etc.)
4. DOI extracted directly from the URL path
5. Site-specific DOM parsers for arXiv, PubMed, ScienceDirect, JSTOR, and Springer
6. HTML fallbacks: <h1> text, <title>, and the page hostname

Duplicate Detection

Before saving, Bibliophage checks whether a source with the same URL or DOI already exists. If a duplicate is found, it updates the existing record rather than creating a second copy, so your library stays clean.

Search Page Detection

Google Scholar search results, PubMed search pages, and similar listing URLs are detected as search pages and are not saved as sources. Only individual article or resource pages are captured.

Reading Progress & Resume

Bibliophage tracks how far you've read each source and can reopen a tab exactly where you left off — even on React and Next.js single-page apps.

Progress Tracking

While you're on a tracked page, Bibliophage debounces your scroll position every 500 ms and saves both a percentage (0–100%) and a text anchor — a short snippet of the text closest to the center of your viewport.

Using text rather than pixel offsets means progress survives page reflows, font changes, and dynamically loaded content.

Resume Reading

When you reopen a tracked page, Bibliophage tries to scroll back to the text anchor using a TreeWalker to find the matching text node. If the exact text isn't found immediately (common on SPAs that hydrate asynchronously), it retries up to 6 times over ~10 seconds before falling back to the saved percentage offset.

You can also resume manually:

• Click the extension popup → click any source → the tab opens and scrolls to your last position
• Click the Resume button in the popup to jump to your most recent source

Session Logging

Every reading session is recorded with a timestamp, duration (in seconds), and the progress reached. Sessions shorter than 10 seconds are discarded to avoid noise. You can view session history per source in the Dashboard Analytics panel.

Research Sidebar

The sidebar is a slide-in panel that appears on the right side of any tracked page. It's your primary workspace for notes, highlights, tags, collections, and citations.

Opening the Sidebar

• Click the gold toggle button on the right edge of any tracked page
• Press Alt+B
• The sidebar opens automatically when you save a note via the selection tooltip or keyboard shortcut

If the page isn't tracked yet, clicking the toggle button will force-capture it first, then open the sidebar.

Notes Tab

View and write notes for the current source. Each note displays:

• A color indicator dot (one of five colors)
• The quoted text (if the note was created from a selection)
• Your annotation text
• Timestamp and a jump-to-location link if an anchor was saved

To write a new note, use the compose area at the top of the tab. You can also copy all notes and quotes for the current source using the Copy All Notes button in the sidebar footer.

Highlights Tab

Lists every note that has an associated quote (i.e. notes created from a text selection). Each entry shows the quoted text and links back to its location on the page. Clicking the jump link scrolls the page to that passage.

Tags Tab

Add free-text tags to the current source. As you type, Bibliophage suggests tags from your existing vocabulary so your tagging stays consistent across your library. Remove tags by clicking the × on any tag chip.

Collections Tab

Add the current source to one or more named collections. Collections are created on the fly — type a name and press Enter. Sources can belong to multiple collections simultaneously.

Citations Tab

The full five-format citation editor. See Citation Formats for complete details. The tab includes the citation text area, format tabs, the Custom Builder button, and save/revert controls for edited citations.

Selection Tooltip

Select any text on any page and a small toolbar floats above your selection with three quick actions.

Inline Note Popup

A floating popup that lets you write and color-code an annotation directly on the page, without opening the sidebar.

Opening the popup

• Select text → click ✎ Note in the selection tooltip
• Press Alt+N with text selected (sidebar opens if it was closed)
• Click an existing highlight on the page to edit that note

Writing a note

The popup shows a condensed preview of the quoted text (first 5 words … last 4 words). Type your annotation in the text area. The popup positions itself above the selection when there's room, otherwise below.

Note Colors

Click any color dot to select it. The color is applied to the highlight on the page and shown as a dot in the sidebar note list.

Saving

Click Save Note or press Escape to cancel. Once saved:

• The quoted text is immediately highlighted on the page in the chosen color
• The sidebar opens (if it was closed) and scrolls to the new note
• The note is persisted to IndexedDB and will reappear on every future visit

Editing an existing note

Click any colored highlight on the page. The popup reopens with the existing content and color pre-filled. Change the text or color and click Update Note.

Persistent Highlights

Notes with a quoted selection are rendered as colored underline highlights directly on the page, every time you visit.

How highlighting works

When a note is saved with a quote, Bibliophage stores the quote text plus up to 60 characters of text before the selection (the "context"). On every page load, it walks all text nodes looking for the quote and uses the context characters to identify the correct occurrence when the same phrase appears multiple times.

If a quote spans across element boundaries (e.g. a link inside a paragraph), Bibliophage applies a partial highlight to the nodes it can wrap.

SPA support

For pages where content loads asynchronously (Medium, React SPAs, Next.js), highlights are re-applied a second time after 2.5 seconds to catch content that wasn't in the DOM on initial load.

Visual appearance

Highlights use a semi-transparent background (color + 2e alpha) and a solid 2px bottom border (color + 88 alpha) so they're visible without obscuring the text. On hover, brightness increases slightly for clarity.

Citation Formats

Bibliophage generates citations in four standard formats plus a fully custom template. The citation editor is available in both the sidebar and the dashboard source modal.

Switching formats

The citation editor shows five tabs: APA · MLA · Chicago · BibTeX · Custom. Click any tab to switch formats. Each format is generated independently from the source's stored metadata.

Copying a citation

Click the Copy button below the text area to copy the current citation to your clipboard. You can also press Alt+C on any tracked page to copy the citation in your default format without opening the sidebar.

Custom Citation Builder

Design your own citation format by dragging field chips into a template. The builder opens as a centered popup from the "Custom" tab in the citation editor.

Field palette

Eight field chips are available to add to your template:

Drag any chip from the palette into the drop zone below, or click a chip to append it at the end.

Reordering chips

Once chips are in the drop zone, drag them to reorder. Drop a chip onto another chip to insert it at that position, or drop it into empty space to move it to the end.

Chip configuration

Click any chip in the drop zone to expand its config panel:

• Prefix — text to insert before the field value (e.g. ", ()
• Suffix — text to insert after the value (e.g. "., ))
• Wrap in italics — wraps the value in italics (useful for journal names)
• Wrap in quotes — wraps the value in quotation marks

Separator inputs

Between each chip in the drop zone is a small separator input field. Type any text (spaces, commas, periods) to control what appears between fields.

Live preview

The preview box at the bottom of the builder updates in real time as you add, remove, reorder, or configure chips. It renders using the actual metadata of the current source so you can see exactly what the output will look like.

Saving the template

Click Save Template. The template is saved globally and applied to every source in your library. The preview in the Custom tab of the citation editor updates immediately across all views.

Removing chips

Click the × on any chip in the drop zone to remove it from your template.

Editable Citations & Stale Detection

Every citation text area is fully editable. Your modifications are saved per format, per source, and persist across sessions.

Editing a citation

Click inside any citation text area in the sidebar or dashboard and type. The text area becomes active and a Save and Revert button appear below it.

• Save — stores your edited text for this format. The auto-generated citation is replaced by your version and displayed every time you view this source in this format.
• Revert — discards your edits and restores the auto-generated citation.

Stale detection

When you save an edited citation, Bibliophage records a snapshot of the source's key metadata fields (authors, title, date, DOI, journal/site). If you later update those fields in the dashboard, Bibliophage compares the current metadata against the saved snapshot.

If they no longer match, a stale warning banner appears above the text area:

You can dismiss the warning by re-saving the edited text (accepting it as current) or by clicking Revert.

Per-format independence

Each of the five citation formats stores its edited version independently. Editing the APA citation doesn't affect the BibTeX or Custom citation for the same source.

Works Cited — Bulk Copy

Copy your entire bibliography to the clipboard in one click, formatted and sorted alphabetically, ready to paste into any document.

How to use it

From any view in the dashboard — All Sources, Articles, a specific Collection, or a Tag — click the Copy Works Cited button in the section heading. A format picker appears with five options.

Sorting

Sources are sorted alphabetically by the first author's last name. The sort handles both formats:

• "Last, First" — uses the text before the comma
• "First Last" — uses the last word in the name

For sources with no authors, the title is used instead, with leading articles (A, An, The) stripped for correct alphabetization.

Output format

Each citation appears on its own paragraph with a blank line between entries, matching the standard Works Cited / References page layout expected by word processors.

Supported formats

Selecting Custom uses your saved custom template. If no custom template has been saved yet, a toast notification will prompt you to build one first.

Dashboard Overview

The dashboard is a full-page research management interface. Open it from the extension popup, with Alt+D, or via right-click → Open Bibliophage Dashboard.

Views

Search

The search bar filters sources across title, authors, DOI, and abstract text simultaneously. Results update as you type (debounced). Clear the search to return to the full list.

Sort options

Source cards

Each card shows the source title, authors, site/journal, reading progress bar, status badge (Reading / Done / Paused), and a count of attached notes. Click any card to open its detail modal.

Source detail modal

The modal shows the full source record with editable metadata fields, all notes in a scrollable list, the complete 5-format citation editor (identical to the sidebar), and a reading sessions analytics table. Changes to metadata fields are saved to the database immediately.

Collections & Tags

Two independent ways to organize your library — collections for broad project groupings, tags for cross-cutting themes.

Collections

Collections are named groups (e.g. "Thesis Chapter 2", "Machine Learning Papers"). A source can belong to multiple collections at once. Create and manage collections from:

• The Collections tab in the sidebar while reading a source
• The source detail modal in the dashboard
• The Collections view in the dashboard to see all collections and their source counts

Tags

Tags are free-text labels for fine-grained categorization (e.g. "transformer", "attention", "to-read"). Add tags in the sidebar's Tags tab or in the source detail modal. The tag input offers auto-suggestions based on your existing tags to keep naming consistent.

Click any tag in the dashboard's Tags view to filter to all sources carrying that tag.

Analytics

Bibliophage logs every reading session so you can see how much time you've invested in each source.

Per-source sessions

Open any source in the dashboard modal and scroll to the Reading Sessions section. Each row shows:

• Date and time the session ended
• Duration in minutes and seconds
• Progress percentage reached during that session

The header row shows total time spent on the source across all sessions.

Session recording rules

• A session starts when the page is loaded and Bibliophage detects tracking is active.
• A session ends when the tab is closed or navigates away.
• Sessions shorter than 10 seconds are discarded automatically (e.g. accidental opens).

Export & Import

Your library is fully portable. Export in multiple formats anytime, or import from another reference manager.

Export formats

Import (BibTeX / RIS)

Go to Settings → Import, upload a .bib or .ris file, and Bibliophage will parse and add all entries to your library. Duplicates (matched by DOI or URL) are skipped. Import is useful for migrating an existing Zotero, Mendeley, or EndNote library.

Keyboard Shortcuts

All core actions are accessible without touching the mouse. Shortcuts are suppressed when your cursor is in an input, textarea, or contenteditable element.

Right-Click Context Menu

Four Bibliophage actions are available in the right-click context menu on any page.

Cite While You Write

On Google Docs and Overleaf, Bibliophage adds a floating button that lets you search your library and copy a citation without leaving your document.

Where it appears

A small gold circular button appears in the bottom-right corner of any docs.google.com or overleaf.com page.

Using the citation picker

1. Click the gold button to open the citation search overlay.

2. Type to filter your library by title, author, or journal. Results appear as you type.

3. Click any result to copy its citation to your clipboard. The overlay closes automatically after 0.8 s.

4. Paste (Ctrl+V) into your document at the cursor position.

Closing the picker

Click the gold button again, click anywhere outside the overlay, or click the × inside the overlay header.

DOI Quick-Add

Paste any DOI into the extension popup and Bibliophage fetches full metadata from the public Crossref API — without you visiting the paper's page.

Accepted formats

All of these are valid inputs — Bibliophage normalizes them automatically:

• 10.48550/arXiv.1706.03762
• https://doi.org/10.48550/arXiv.1706.03762
• doi:10.48550/arXiv.1706.03762

What gets imported

Title, authors (in "Last, First" format), journal/conference name, publication year, DOI, abstract, and source type (article, book, etc.).

Duplicates

If a source with the same DOI already exists in your library, a warning is shown and no duplicate is created.

Settings

Open Settings from the extension popup → Settings, or right-click any page → Bibliophage Settings.

Auto-Capture

Toggle automatic source capture on recognized academic domains on or off. When disabled, no page is captured automatically — you must use Alt+T or the right-click menu to track pages manually.

Default Citation Format

Choose which format tab is pre-selected when you open the citation editor and which format is used by Alt+C and the Cite While You Write picker.

Tracked Domains

View the full list of domains currently set for auto-capture. Click the × next to any domain to remove it. Add custom domains by typing a hostname (e.g. example.edu) and pressing Enter.

Export Data

Download your library in any of the five supported formats. See Export & Import for format details.

Import BibTeX / RIS

Upload a .bib or .ris file to bulk-import sources from Zotero, Mendeley, EndNote, or any other reference manager.

Clear All Data

Permanently deletes every source, note, collection, tag, session, and setting from the local database. A double-confirmation prompt prevents accidental deletion — you must confirm twice before data is erased.

Supported Sites

These domains are recognized for auto-capture. Bibliophage also has specialized DOM parsers for five platforms that improve metadata quality beyond what standard meta tags provide.

Auto-Capture Domains (Default)

Enhanced Site Parsers

To add any domain not on this list, go to Settings → Tracked Domains → Add Domain.

Privacy & Data

Bibliophage is built on a local-first principle: your research data stays on your device.

What is stored and where

All data is stored exclusively in IndexedDB inside your browser profile. This includes sources, notes, sessions, collections, tags, settings, and edited citations. Nothing is uploaded to any server.

Network requests

The only outbound request Bibliophage makes is to the Crossref API (api.crossref.org) when you manually paste a DOI into the popup's DOI quick-add field. Only the DOI string is sent. This request never happens automatically.

Permissions explained

Read the full Privacy Policy.

Troubleshooting

Common issues and how to resolve them.

Extension not loading

• Go to chrome://extensions/ and check for red error badges on the Bibliophage card.
• Click Details → Inspect views: service worker to open the background console and read any error messages.
• Ensure all extension files are present in the folder (for unpacked installs).

Sidebar not appearing

• The page must be auto-tracked or manually captured with Alt+T before the sidebar can open with Alt+B.
• Some pages with a strict Content-Security-Policy block <iframe> elements from extension URLs. The gold toggle button will still appear, but the sidebar won't load. This is a browser security restriction, not a Bibliophage bug.
• Check the page console (F12) for [Bibliophage] prefixed errors.

Sources not being captured

• Open DevTools on the page → Console, look for errors starting with [Bibliophage].
• Open chrome://extensions/ → Bibliophage → Inspect views: service worker and check the console for database errors.
• If auto-capture is off in Settings, use Alt+T or right-click → Track This Page.

Service worker / DB errors

Manifest V3 service workers are ephemeral — Chrome can suspend them after a period of inactivity. If you see "DB not initialized" errors, click the circular reload icon next to Bibliophage in chrome://extensions/. The next page visit will reinitialize everything normally.

Highlights not appearing after a page reload

• For SPAs (Medium, Next.js apps), Bibliophage retries highlighting after 2.5 seconds. Wait a moment.
• If highlights still don't appear, close the tab and reopen it — this forces a fresh content script injection.
• If the quote text was edited on the page (e.g. a typo was fixed), the stored snippet may no longer match. The highlight will be lost for that note.

Progress not updating

• Progress saves are debounced 500 ms — scroll a bit and wait.
• Check that the background service worker is active (reload the extension if not).
• Pages under 400px of scrollable height don't record progress (nothing meaningful to track).

DOI lookup returns an error

• Confirm the DOI is valid — paste it into https://doi.org/<your-doi> first.
• Not all DOIs are in Crossref's database (e.g. some book chapters or theses). Try searching the publisher's site directly and using force-capture instead.
• If Crossref returns HTTP 429, you've hit a rate limit. Wait a minute and try again.

Still stuck?

Open a support request via the Buy Me a Coffee page, or report the issue with your Chrome version and a screenshot of the error.