Shortcuts & Reference

This is the reference chapter: the complete menu bar, the keyboard shortcuts and mouse actions, the Preferences, an explanation of the on-disk file format and exactly how the app preserves and normalises it, a map of where every kind of data is stored, a reference for the BibTeX fields the app treats specially, notes on citations, the x-bibdesk:// automation URLs, an honest account of current limitations, a glossary, and general troubleshooting.

Use it as a lookup. The earlier chapters teach the workflows; this one nails down the details.

The menu bar#

Every command lives in the application menu bar — on macOS in the system menu bar at the top of the screen; on Windows and Linux attached to the window. The toolbar duplicates a few of the most common commands, but the menus are the full inventory. Items marked (needs an open library) are greyed out until a .bib file is open.

Bibliofile menu (macOS only)#

On Windows and Linux these items live elsewhere: Preferences… and Quit both move to the bottom of the File menu.

File menu#

Edit menu#

Undo (⌘Z / Ctrl+Z) and Redo (⇧⌘Z / Shift+Ctrl+Z) are document-level: they step a library edit (a field change, a delete, a batch operation, …) back and forth, and the menu labels name the action (e.g. Undo Delete). Cut, Copy, Paste, Paste and Match Style, Delete, and Select All are the standard platform editing roles with their usual system shortcuts and apply to text fields. The app-specific commands are:

Publication menu#

Every item needs an open library.

View menu#

Tools menu#

Window and Help menus#

The Window menu holds Minimize and Zoom, then Bring All to Front on macOS (Close on Windows and Linux), and finally a checkmarked list of every open library — pick one to bring its window forward. The Help menu's Bibliofile Help item (F1 on Windows/Linux) opens this manual in its own window.

Keyboard shortcuts (quick list)#

The app-specific accelerators, gathered in one place (macOS first; on Windows and Linux ⌘ is Ctrl, ⌥ is Alt):

Keys in the publications table#

These act on the table itself, so they need the table to have keyboard focus (click a row once):

The list always scrolls to keep the moved-to row in view.

Mouse and click actions#

Plenty of behaviour is driven by the pointer rather than the keyboard. The useful ones:

Cross-references for these: sorting, filtering, and columns are covered in Browsing & Searching; field editing and the copy commands in Editing Entries; importing and exporting in Importing & Exporting; links and [[citeKey]] notes in Notes & Abstracts and Preview & Citations.

File format & fidelity#

Your library is a standard .bib (BibTeX) text file, and it is the single source of truth. There is no sidecar metadata folder and no second copy of your data — every fact about your library (entries, groups, macros, notes, attachment links) is read from, and written back to, that one plain-text file. You can open it in any text editor, version-control it with Git, and use it directly with LaTeX.

The one thing the app keeps outside the file is a derived cache: the text it extracts from your attached PDFs, so that full-text search doesn't have to re-read every PDF on every launch. That lives in the app's own per-user folder, never beside your .bib, and it is disposable — delete it and it rebuilds. See Where data is stored.

Preserved BibDesk extensions#

BibDesk stores a handful of things inside the .bib file using BibTeX comment and string mechanisms, so that the file remains valid BibTeX while carrying extra structure. The app reads, preserves, and rewrites all of them, so a library round-trips faithfully — you can move it between this app and the original macOS BibDesk without anything being mangled:

• @string macros — reusable abbreviations (for instance a short token that expands to a full journal name). Editable via the @string… toolbar button or Publication → Macros (@string)….
• @preamble — a LaTeX preamble block, preserved verbatim.
• Group blocks — saved Static, Smart, URL, and Script groups, stored as specially structured @comment blocks. (Static and Smart groups filter the table in this app; URL and Script groups are preserved on disk but are not evaluated here — see Limitations.)
• @bibdesk_info — BibDesk's document-info block (window/display state and similar), preserved verbatim.
• Bdsk-File-N attachments — file attachments encoded as numbered, base64 binary-plist blobs holding a relative path plus, on macOS, an Apple bookmark blob. Existing bookmarks are preserved untouched; on macOS this app now also writes one for every attachment it stores, so a library it created has the same moved-file recovery in macOS BibDesk that BibDesk's own files do. Off macOS the blob is relative-path-only, which BibDesk still reads. See Attachments.

Normalisations applied on save#

The serializer reproduces BibDesk's own on-disk formatting rules, which means a freshly saved file is tidied into a canonical shape rather than written back byte-for-byte as you typed it. Expect these normalisations every time you save:

• Field names are lower-cased (Author → author, Doi → doi). This is cosmetic — BibTeX field names are case-insensitive.
• Fields are sorted within each entry, case-insensitively and numeric-aware, with the linked-file/URL fields (bdsk-file-N, bdsk-url-N) forced to the end.
• Values are {…}-wrapped (brace-delimited) consistently. The exception is a value built from @string macros or bare numbers, which stays unbraced so the macro reference survives.
• Empty fields are dropped — a field whose value you clear is removed entirely.
• Unmatched braces in a value are escaped — a stray { or } is written as {\textbraceleft} / {\textbraceright} and shown back to you as { / } (see What survives a round trip).
• Entry-type and keyword tokens are lower-cased (@Article → @article).
• TeXify-on-save — text fields are converted to TeX where appropriate (accented and special characters become their TeX forms), so the file is portable through the LaTeX toolchain. URL, file, and note fields are not TeXified, so links survive intact.

Saving and backups#

Saving is explicit by default (there is no autosave unless you enable Preferences → General → Saving → Autosave). Whether you save manually or autosave does it for you, the write is the same. When you save:

1. The app checks whether the file changed on disk since it last read or wrote it — an edit in another program, a Git checkout, a cloud-sync client. If it did, the save stops and asks rather than silently overwriting the other version. See Getting Started.
2. The in-memory library is serialised to BibTeX text.
3. If the target file already exists, it is copied to <your-file>.bib.bak (a single rolling backup of the previous version).
4. The new text is written to a temporary file in the same folder, which is then renamed over the target. This rename is atomic on a normal filesystem, so the file is never left half-written even if the machine loses power mid-save.

The • beside the library name in the window header is your unsaved-changes indicator; it reads (saving…) during the write and disappears once the file is on disk. See Getting Started → The header.

Where data is stored#

Use this table to reason about portability, backups, and what travels with the file.

Field reference#

The app stores fields as raw BibTeX text and shows nearly all of them generically in the editor. A few fields, however, get special treatment in display, search, or citation. Knowing which is which helps you predict how an entry will appear.

Everything else (Publisher, Address, Edition, Series, ISBN, Note, custom fields, …) is stored and shown verbatim with no special handling.

Citations#

The detail pane renders a live, formatted citation for the selected entry using CSL (the Citation Style Language) via the citeproc-js engine, entirely offline — no network call is made to format a citation.

• Pick a style from the dropdown: APA, Vancouver, or Harvard, plus any .csl style you have installed yourself. Set the one you start in under Preferences → Citations → Default style.
• The citation updates as you edit the entry's fields, so it always reflects the current data.
• It's meant for copying a properly formatted reference into an email, a document, or a reading list — use Edit → Copy Citation to put it on the clipboard as plain text, Edit → Copy Citation as RTF (⌥⌘R) to keep the italics, or Edit → Copy as BibTeX for the raw source.

Behind the scenes the app maps each entry to CSL-JSON (entry type → CSL type; parsed authors/editors → CSL name objects; Pages en-dashes normalised; Doi, Url, Abstract, and the venue carried across). Only the three styles above are bundled. See Preview & Citations.

Preferences#

Open Preferences with ⌘, / Ctrl+, (the item is in the Bibliofile menu on macOS, the File menu on Windows/Linux). All settings are saved in a settings.json file in the per-user application-data folder, so they apply to every library and persist across sessions — none of them is written into your .bib. Changes take effect immediately; there is no OK/Apply button.

The pane has a left rail of nine sections. Below, Section is the rail entry and Group the heading you will find it under.

Automation: the x-bibdesk:// URL scheme#

Besides the Script Console, the app registers a URL scheme so other programs can drive it: AppleScript (open location "x-bibdesk://…"), a shell script (open on macOS, xdg-open on Linux), a Shortcut, a text editor's "run command" hook. It covers fire-and-forget commands only — a URL cannot ask the app a question and get an answer back.

Two rules keep this from being a hole in your library, because anything can emit one of these URLs — including a web page you merely visited:

• Every one of these asks first. A dialog names what is about to happen ("Add entries to library.bib from an external link?") and says the request came from outside the app. Cancel is the default, so pressing Return or Escape declines. Nothing happens until you click Allow.
• open?file= accepts .bib paths only. Any other path is refused outright, before the prompt — an unrestricted "open this file" would let a web page use the app to find out which files exist on your disk.

import and new act on the front library, so they do nothing if no library is open. Unknown commands are ignored.

Limitations / not-yet#

In the interest of honesty, here is what is incomplete, deferred, or platform-specific in the current build. None of these affect the integrity of your .bib file; they're missing conveniences, not data hazards.

• Undo is per-document. Library edits apply immediately to the in-memory model but are undoable: Edit → Undo / Redo (⌘Z / ⇧⌘Z) step them back and forth (a batch edit or a multi-row delete is one step; see Undo and redo). Beyond that, your safety net is explicit save plus the .bib.bak backup and File → Revert to Saved, which reloads the last saved version from disk.
• Autosave is opt-in. Saving is explicit by default (⌘S / Ctrl+S); unsaved imports and edits are lost if you quit without saving (the app does prompt). You can turn on Preferences → General → Saving → Autosave to have the app save for you after each edit.
• Text fields are edited as raw text. Keywords, rating, boolean and tri-state fields have purpose-built widgets, but every other field is edited as its literal BibTeX string (with autocomplete from existing values) — there are still no dedicated person or date field editors, so authors are typed as Family, Given and Family, Given. The Read and Rating icon columns show their fields but aren't click-to-toggle; use the editor's checkbox and stars instead. Macros are edited in the @string… modal; the field editor stores literal strings, not macro/complex values.
• Some commands still act on one entry only. The whole selection is used by Delete, Generate Cite Key, AutoFile Linked Files, Find Open-Access PDFs…, OCR Scanned PDFs…, Color Label, Export → Selected Entries, Copy As → RIS / Minimal BibTeX / LaTeX \bibitem, and a drag-out (which produces \cite{key1,key2}). But Copy Cite Key, Copy \cite{…}, Copy Citation, Copy Citation as RTF, Copy as BibTeX and Duplicate still take the single focused entry even when several rows are highlighted.
• Moved-attachment recovery is one-way. macOS BibDesk stores an Apple "bookmark" beside each attachment that can re-find a file after it's moved or renamed. On macOS this app now writes those bookmarks too (and Consolidate Linked Files… backfills them into older libraries), so a library edited here keeps that recovery ability in BibDesk. It does not yet use them itself: this app resolves attachments only by their stored relative path, so a file that has been moved may not open here until you fix the path, AutoFile it, or re-add it. Off macOS, bookmarks are neither written nor read (existing ones are preserved untouched). See Attachments.
• URL and Script groups are not evaluated. Static and Smart groups (and nestable folders) are fully editable in the app — create, rename, delete, and build Smart-group conditions in the sidebar. URL and Script groups, however, are only preserved on disk: they appear in the sidebar but have no live membership (URL groups don't fetch; Script groups don't execute). (These BibDesk Script group definitions are unrelated to Scripting with JavaScript, which is fully supported.)
• Citation styles are added by file. Three styles ship built in (APA, Vancouver, Harvard); you can install any other by adding its CSL (.csl) file in Preferences → Citations, but there is no in-app browser of the CSL style repository — you download the file yourself. See Preview & Citations.
• Full-text search needs the native component. Search uses SQLite FTS5 — field text in memory, PDF text on disk. Both rely on a native module that must be built for the app's runtime; if a build doesn't include it, search silently falls back to a substring filter over the visible columns. Developers enable it with pnpm --filter @bibdesk/app rebuild:electron.
• Find Duplicates merges into the primary entry. It groups likely duplicates and can merge a group into its first entry — that entry keeps its own values, gains any field it was missing, unions the keywords, adopts the other entries' attachments, and the rest are deleted. You cannot nominate a different entry as the keeper, and it does not auto-resolve every group: you confirm each merge.

Glossary#

.bib / BibTeX file The plain-text database format the app reads and writes. The single source of truth for your library.

Cite key The short, unique identifier for an entry (e.g. einstein1935) — what you cite in a document and what [[…]] note links and Crossref point at. The app can Generate one from author + year and guarantees uniqueness.

Complex string / macro A field value built (in whole or part) from @string abbreviations, optionally concatenated with #. Macros are reusable tokens — define a short name once and reference it from many entries. Edited in the @string… modal.

Crossref (inheritance) A BibTeX mechanism where one entry names another by cite key in its Crossref field and inherits the parent's fields. Useful when several chapters share one book's publisher and year. Inherited fields show an (inherited) badge; editing one creates a local override on the child.

FTS (full-text search) Indexed search over the full text of records and the text of attached PDFs, as opposed to a simple substring scan. The app uses SQLite's FTS5 engine over two rebuildable indexes: your field text in memory, rebuilt each time a library opens, and the text extracted from your PDFs persisted on disk (pdf-index.db) and keyed by file path, so a big library is scanned once rather than on every launch. A substring filter is the fallback when the native component isn't active.

CSL (Citation Style Language) The XML standard that describes how to format a citation in a given style. The app uses the citeproc-js engine with bundled APA/Vancouver/Harvard styles — plus any .csl file you install yourself — to render the formatted citation in the detail pane.

Bdsk-File A BibDesk file attachment, stored in the .bib as a Bdsk-File-N field holding a base64 binary-plist with the file's relative path and, on macOS, an Apple bookmark blob. This app writes the bookmark on macOS and preserves any it finds elsewhere; it resolves attachments by the relative path.

Troubleshooting#

A change didn't stick. Editing is explicit-save by default. If a • follows the library name in the window header, your edits are still only in memory — press ⌘S / Ctrl+S to write them. (Turn on Preferences → General → Saving → Autosave to have this done for you.)

Saving stopped to warn me the file changed on disk. Something outside the app wrote to your .bib since it was opened — another editor, a Git checkout, a sync client. Choose Overwrite to keep what is in the window, Reload from Disk to throw away your in-app edits and re-read the file, or Cancel to think about it. Cancel is the default. See Getting Started.

An attachment won't open. The file has probably been moved, renamed, or deleted, or it's referenced by a relative path that no longer resolves from the library's folder. This app finds attachments by that stored relative path only — it does not (yet) follow the macOS bookmark that would survive a rename. Put the file back where the relative path expects it, use Find Broken Links… to point it at the new location, or re-add the attachment. See Attachments.

An x-bibdesk:// link did nothing. Either you declined the confirmation dialog (Cancel is its default, so Return or Escape declines), or the request was refused: open?file= only accepts .bib paths, and import/new need a library already open. See Automation.

My file looks heavily reformatted after the first save. That's the canonical normalisation pass (lower-cased field names, sorted fields, {…}-wrapping, TeXify). No content was lost; subsequent saves are stable. See Normalisations applied on save.

Online search fails. Almost always a connectivity issue — check your internet connection (and any proxy/VPN/firewall) and retry. See Online Search → Troubleshooting.

The theme (or another preference) reset on another machine. Preferences — including the light/dark theme — are stored per installation in a settings.json file, not in the .bib file, so they don't travel with your library. Set them again on the new machine. (If your theme is set to System, it follows that machine's OS appearance.)

A DOI or URL chip didn't open. Only http, https, and mailto links are honoured (a bare DOI is rewritten to https://doi.org/…). A Url value with an unsupported scheme won't open; fix the value in the editor.

See also#

• Getting Started — the window at a glance.
• Editing Entries — fields, cite keys, types, macros, Find & Replace, the copy commands, and saving.
• Attachments — Bdsk-File storage, opening in default apps, and AutoFile.
• Importing & Exporting — paste, drag-and-drop, import, and export.
• Online Search — importing new entries.
• Preview & Citations — the CSL citation block.
• Scripting with JavaScript — the other automation surface, for anything the x-bibdesk:// commands above can't express.