QuickMark

QuickMark is a keyboard-first Chrome Extension for searching local bookmarks and browser history. Press Cmd/Ctrl + Shift + K on any page and jump to a bookmark or past visit in seconds — no typing full URLs, no hunting through folders.

中文文档 | 使用指南 (中文)

---

Features

• One keystroke away — Cmd/Ctrl + Shift + K opens a search palette over the current page
• Fuzzy search across title, URL and domain with Fuse.js
• Pinyin search for Chinese titles (e.g. zhihu finds 知乎)
• Flat results — bookmarks and browser history in one ranked list, without domain grouping or inserted homepage links
• Pinned websites — pin up to eight exact URLs; an icon-only strip inside the filter bar keeps frequently used sites one click away, and Cmd/Ctrl + 1–8 opens them
• Filters — source chips (all / bookmark / history), plus one dropdown that carries both the time range (all time / today / week / month) and the sort mode, labelled with the active non-default choices
• Remembered sort modes — smart, recent, frequent, title, created, relevance; smart balances recent visits and time-decayed frequency, not bookmark creation time
• Address-bar semantics — Enter on a complete URL or bare domain (e.g. github.com) navigates directly
• Keyboard-first — Enter opens in the current tab, Cmd/Ctrl + Enter in a new tab, Cmd/Ctrl + 1-9 jumps to the N-th result, Cmd/Ctrl + C copies the URL
• Search history — last 5 queries; press Space in the empty box to open a dropdown, pick with ↑↓ + Enter, and clear the whole list from its footer
• Web-search fallback — no local results? Press Enter to search Google
• Light / dark / system theme

Installation

QuickMark is not yet published to the Chrome Web Store. To install it from source:

1. Build the extension:

   git clone https://github.com/Amdeo/QuickMark.git
   cd QuickMark
   npm install
   npm run build

2. Load it into Chrome:

   • Open chrome://extensions
   • Enable Developer mode (top right)
   • Click Load unpacked
   • Select this project's dist directory

3. Verify the shortcut — open chrome://extensions/shortcuts and confirm QuickMark has Command/Ctrl + Shift + K assigned. Existing tabs receive the modal on demand, so no page reload is needed.

Usage

Keys	Action
Cmd/Ctrl + Shift + K	Open / close the search palette
↑ / ↓	Navigate results
Enter	Open the selected result in the current tab
Cmd/Ctrl + Enter	Open the selected result in a new tab
Cmd/Ctrl + 1–9	Open the N-th pinned icon, then the N-th result — pins take the first slots while the strip is visible; with a query typed, digits go straight to results
Cmd/Ctrl + C	Copy the selected result's URL
Alt + ← / →	Cycle source filter (all / bookmark / history); plain arrows edit the query
Space	Open the recent-searches dropdown while the query is empty (↑↓ to move, Enter to refill); with text present, space types normally
Esc	Clear the query first, then close the palette
Alt + P	Pin / unpin the selected result

Type a complete URL or bare domain (e.g. kimi.com, localhost:3000) and press Enter to navigate directly, address-bar style — even when no local results match.

Pins keep their exact URL and manual order, remain available if the original bookmark/history entry disappears, and never change with ranking. Click a result's pin button to add it; the icon row shows favicons with their Cmd/Ctrl+N badge, hover for the name and full URL, drag an icon onto another to reorder the row, and use the small remove button to unpin. Result badges always show each row's real key: with N pins the first result is Cmd/Ctrl + N+1. The strip sits in the filter bar, right after the source chips and before the filter dropdown, when the query is empty; with nothing pinned the bar keeps no placeholder. Pins and the selected sort mode are saved locally and restored when reopening the palette. With a query, match relevance takes priority and the selected mode breaks close ties; without a query, recent uses actual visit time and frequent uses visit count.

A full Chinese usage guide is available in USAGE.md.

Development

npm install      # install dependencies
npm test         # run the Vitest test suite
npm run build    # type-check, bundle and output to dist/
npm run dev      # start the Vite dev server

Project layout

• src/background — MV3 service worker: command routing, bookmark/history cache
• src/content — on-page modal overlay host (Shadow DOM); the heavy search bundle loads on demand, and a placeholder panel covers waits longer than 120ms
• src/domain — pure bookmark, search and ranking logic
• src/adapters — Chrome bookmarks / history / favicon API adapters
• src/search — React search UI and hooks
• public/manifest.json — extension manifest, copied into dist

Bookmark and history data is cached in chrome.storage.local under quickmark.bookmark-cache-v1 and refreshed in the background whenever bookmarks or history change. Cached data never leaves your browser.

Limitations

• The palette only appears on normal http:// / https:// pages. Chrome internal pages (chrome://extensions, Web Store, settings) do not allow extension overlays.

Contributing

Contributions are welcome! Please follow the existing conventions:

• Keep the codebase keyboard-first and dependency-light
• Comments and commit messages may be written in Chinese or English (see the repo history for style)
• Add or update tests in src/**/*.test.ts and run npm test before submitting
• Run npm run build to make sure the extension bundles cleanly

Report issues or feature ideas via GitHub Issues.

License

MIT © 2025 Amdeo