{"id":29055706,"url":"https://github.com/ehamiter/bookerics","last_synced_at":"2026-03-13T18:37:30.768Z","repository":{"id":299117940,"uuid":"811033572","full_name":"ehamiter/bookerics","owner":"ehamiter","description":"bookmarks, but for Erics","archived":false,"fork":false,"pushed_at":"2025-06-22T17:24:05.000Z","size":3637,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-27T06:13:54.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://bookerics.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ehamiter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-05T20:14:33.000Z","updated_at":"2025-06-22T17:24:08.000Z","dependencies_parsed_at":"2025-06-14T19:58:26.291Z","dependency_job_id":"2d840569-3607-48ab-8e7f-010c53e52d86","html_url":"https://github.com/ehamiter/bookerics","commit_stats":null,"previous_names":["ehamiter/bookerics"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ehamiter/bookerics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehamiter%2Fbookerics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehamiter%2Fbookerics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehamiter%2Fbookerics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehamiter%2Fbookerics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehamiter","download_url":"https://codeload.github.com/ehamiter/bookerics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehamiter%2Fbookerics/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262366011,"owners_count":23299751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-27T04:09:43.756Z","updated_at":"2026-03-13T18:37:30.752Z","avatar_url":"https://github.com/ehamiter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `bookerics`\n\n\u003e bookmarks, but for Erics\n\n**`bookerics`** is a modern, self-hosted bookmark manager that combines simplicity with powerful features. Think of it as a personal alternative to [Pinboard](https://pinboard.in/) with intelligent tagging, automatic screenshots, RSS feeds, and cloud synchronization.\n\n![Screenshot](bookerics/static/images/screenshot.webp)\n\n## ✨ Features\n\n### 📚 Core Functionality\n- **Smart Bookmark Management** - Save, organize, and search your bookmarks with ease\n- **Automatic Screenshots** - Visual previews of your bookmarks using website thumbnails\n- **AI-Powered Tagging** - Intelligent tag suggestions\n- **Full-Text Search** - Search through titles, descriptions, and tags\n- **RSS Feed Generation** - Automated RSS feeds for all bookmarks or specific tags\n- **Archive.ph Integration** - Automatic archival of bookmarked URLs\n\n### 🎨 User Experience\n- **Keyboard Shortcuts** - Navigate and manage bookmarks without touching your mouse\n- **Dark/Light Theme Toggle** - Comfortable viewing in any lighting condition\n- **Infinite Scroll** - Seamless browsing through large bookmark collections\n- **Responsive Design** - Works beautifully on desktop and mobile devices\n- **Browser Extension** - One-click bookmark saving with pre-filled metadata\n\n### 🔧 Technical Features\n- **SFTP Integration** - Automatic screenshot storage and RSS feed distribution\n- **Multiple View Modes** - Newest, oldest, untagged, and tag-filtered views\n- **Customizable Branding** - Easily personalize for your name (booktoms, bookzendayas, etc.)\n\n## 🏗️ Architecture \u0026 Tech Stack\n\n### Backend\n- **[FastHTML](https://fastht.ml/)** - Modern Python web framework (previously Ludic)\n- **SQLite** - Lightweight, file-based database with thread-local connections\n- **OpenAI API** - AI-powered tag generation and content analysis\n- **shot-scraper** - Website screenshot generation using Playwright\n- **asyncssh** - Async SFTP integration\n\n### Frontend\n- **[HTMX](https://htmx.org/)** - Dynamic frontend interactions without JavaScript complexity\n- **Vanilla JavaScript** - Custom keyboard shortcuts and UI enhancements\n- **Modern CSS** - Responsive design with dark/light theme support\n\n### Infrastructure\n- Cloud storage for screenshots and RSS feeds via SFTP\n- Chrome/Firefox extensions for quick bookmark saving\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Python 3.12+\n- [uv](https://github.com/astral-sh/uv) package manager\n- Web hosting account (optional, for cloud storage of screenshots and RSS feeds)\n- OpenAI API key (optional, for AI tagging)\n\n### Installation\n\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/ehamiter/bookerics.git\ncd bookerics\n\n# Set up environment\ncp .env.example .env\n# Edit .env with your configuration\n\n# Install dependencies\nuv sync\n\n# Run the application\nuv run bookerics\n```\n\nThe application will be available at `http://localhost:50113`\n\n### Environment Configuration\n\nCreate a `.env` file with your settings:\n\n```env\n# Basic Configuration\nBOOKMARK_NAME=bookeric  # Customize your bookmark terminology\n\n# RSS Feed Configuration\nRSS_ID=\"https://bookyournames.com/\"\nRSS_TITLE=\"bookerics\"\nRSS_DESCRIPTION=\"bookmarks, but for Your Names\"\nRSS_AUTHOR_NAME=\"Your Name\"\nRSS_AUTHOR_EMAIL=\"yourname@bookyournames.com\"\nRSS_LINK=\"https://bookyournames.com\"\nRSS_LOGO=\"bookyournames.png\"\nRSS_LANGUAGE=\"en\"\n\n# Hosting (for screenshot and RSS feed storage)\nBOOKERICS_SERVER=your-server.somehosting.com\nBOOKERICS_USERNAME=your-username\nBOOKERICS_PASSWORD=your-password\n\n# AI tagging\nBOOKERICS_OPENROUTER_KEY=your-openrouter-api-key\n\n# Optional: Giphy (for placeholder images)\nGIPHY_API_KEY=your-giphy-api-key\n\n# Optional: Local backups\nLOCAL_BACKUP_PATH=/path/to/backup/directory\n```\n\n## 📱 Browser Extension\n\n`bookerics` includes browser extensions for Chrome and Firefox that enable one-click bookmark saving:\n\n### Chrome Extension\n```bash\ncd tools/bookerics_browser_extension\n# Load as unpacked extension in Chrome developer mode\n```\n\n### Firefox Extension\n```bash\ncd tools/bookerics_firefox_extension\n# Load as temporary add-on in Firefox\n```\n\n**Usage**: Click the extension icon or press `Cmd+D` to open a bookmark modal pre-filled with the current page's title and description.\n\n## ⌨️ Keyboard Shortcuts\n\n### Navigation\n- **J** - Navigate down to the next bookmark\n- **K** - Navigate up to the previous bookmark\n\n### Actions\n- **V** - Open the selected bookmark's URL in a new browser tab\n- **E** - Edit the selected bookmark (opens modal)\n- **X** - Delete the selected bookmark (requires confirmation)\n\n### Interface\n- **Cmd+K** (Mac) / **Ctrl+K** (Windows/Linux) - Focus the search bar\n- **Escape** - Unfocus search bar or close modals\n- **Cmd+Shift+D** - Toggle between dark and light themes\n- **?** - Show keyboard shortcuts help\n\n## 📡 RSS Feeds\n\n`bookerics` automatically generates RSS feeds for your bookmarks:\n\n- **Main Feed**: `/feeds/rss.xml` - All bookmarks\n- **Cloud Hosted**: Feeds are automatically uploaded to web hosting with SFTP for external access\n\nRSS feeds include:\n- Bookmark metadata (title, description, URL)\n- Screenshot thumbnails as enclosures\n- Tags as categories\n- Proper RSS 2.0 formatting with XSL styling\n\n## 🔄 Data Management\n\n### Import Existing Bookmarks\n\nUse the blazing fast 🔥 companion [bookerics-importer](https://github.com/ehamiter/bookerics-importer) tool to convert browser bookmarks:\n\n```bash\ngit clone https://github.com/ehamiter/bookerics-importer.git\ncd bookerics-importer\ncargo build --release\n\n# Convert bookmarks.html to bookerics.db\n./target/release/bookerics_importer /path/to/bookmarks.html bookerics.db\n```\n\n### Backup \u0026 Sync\n\n- **Automatic Sync**: Screenshots and RSS feeds automatically uploaded via SFTP\n- **Manual Backup**: Click the bookmark count to trigger immediate backup and feed update\n- **Local Backups**: Optional local backup path configuration (keeps 10 most recent backups)\n\n## 🚀 Deployment\n\n### Development\n```bash\nuv run bookerics\n```\n\n### Production (macOS with launchd)\n\nCreate `~/Library/LaunchAgents/com.bookerics.plist`:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n    \u003ckey\u003eLabel\u003c/key\u003e\n    \u003cstring\u003ecom.bookerics\u003c/string\u003e\n    \u003ckey\u003eProgramArguments\u003c/key\u003e\n    \u003carray\u003e\n        \u003cstring\u003e/Users/YOUR_USERNAME/.local/bin/uv\u003c/string\u003e\n        \u003cstring\u003erun\u003c/string\u003e\n        \u003cstring\u003ebookerics\u003c/string\u003e\n    \u003c/array\u003e\n    \u003ckey\u003eWorkingDirectory\u003c/key\u003e\n    \u003cstring\u003e/Users/YOUR_USERNAME/bookerics\u003c/string\u003e\n    \u003ckey\u003eStandardOutPath\u003c/key\u003e\n    \u003cstring\u003e/Users/YOUR_USERNAME/Library/Logs/bookerics.log\u003c/string\u003e\n    \u003ckey\u003eStandardErrorPath\u003c/key\u003e\n    \u003cstring\u003e/Users/YOUR_USERNAME/Library/Logs/bookerics.error.log\u003c/string\u003e\n    \u003ckey\u003eKeepAlive\u003c/key\u003e\n    \u003ctrue/\u003e\n    \u003ckey\u003eRunAtLoad\u003c/key\u003e\n    \u003ctrue/\u003e\n    \u003ckey\u003eEnvironmentVariables\u003c/key\u003e\n    \u003cdict\u003e\n        \u003ckey\u003ePATH\u003c/key\u003e\n        \u003cstring\u003e/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin\u003c/string\u003e\n    \u003c/dict\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\n**Service Management**:\n```bash\n# Load and start\nlaunchctl load ~/Library/LaunchAgents/com.bookerics.plist\n\n# Stop and unload  \nlaunchctl unload ~/Library/LaunchAgents/com.bookerics.plist\n\n# Check status\nlaunchctl list | grep bookerics\n\n# View logs\ntail -f ~/Library/Logs/bookerics.log\ntail -f ~/Library/Logs/bookerics.error.log\n```\n\n## 🤔 FAQ\n\n**Q. What?**  \nA: It's bookmarks, but for Erics. So, `bookerics`. Get it?\n\n**Q: That seems like it's marketed to a very niche group.**  \nA: That's not a question.\n\n**Q: Can I use this if my name isn't Eric?**  \nA: Sure. If you're not lucky enough to be named Eric, you can update the configuration to be booktoms, bookzendayas, bookvolodymyrs, \netc. I suppose \"bookmarks\" works as well.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehamiter%2Fbookerics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehamiter%2Fbookerics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehamiter%2Fbookerics/lists"}