README.md
Rama main · réplica de lectura del repositorio original.
# Cloudmark
[](https://www.gnu.org/licenses/agpl-3.0.html)
[](https://cloudmark.site/)
[](https://deploy.workers.cloudflare.com/?url=https://github.com/wesleyel/cloudmark)
[中文文档](README.zh.md)
## Introduction
Cloudmark is a universal cloud bookmark management tool that allows you to easily save and access your bookmarks from anywhere. No login or registration required — create a collection ID (`mark`) plus a secret **write token**, install the bookmarklet, and start saving pages.
Try it online: [https://cloudmark.site/](https://cloudmark.site/)
## Key Features
- 🔑 **No Registration**: Access your collection with a unique `mark`; writes require a write token
- 🔖 **One-Click Save**: Bookmarklet embeds mark + write token
- 🧩 **Chrome Extension**: Save the active tab with an existing or new category
- 🏷️ **Category Management**: Custom categories for organization
- ⌨️ **Keyboard-first**: `/` search, `j/k` navigate, `n/e/d` CRUD, `?` help
- 📋 **High density**: Compact list with instant filter / sort
- 🎨 **Custom icons**: Emoji, letter marks, or upload SVG/ICO/PNG
- 🌐 **Cross-Device Access**: Read anywhere; copy the write token to another device to write
- 📝 **Detailed Descriptions**: Optional notes per bookmark
- 🌍 **Multi-Language Support**: English and Chinese
- 🗄️ **Cloudflare D1**: Relational storage on the edge
## Security Model
| Capability | Requirement |
|------------|-------------|
| View collection | Know the `mark` (URL) |
| Add / edit / delete | Valid **write token** for that mark |
| Bookmarklet save | `mark` + `token` query params |
- Write tokens are hashed (SHA-256) in D1; plaintext is only stored in the browser (`localStorage`) and in the bookmarklet.
- Rate limits and field length limits protect against abuse.
## Quick Start
1. Visit [https://cloudmark.site/doc](https://cloudmark.site/doc)
2. Generate a `mark` and write token (or customize the mark)
3. Drag the bookmarklet to your browser bookmarks bar
4. Click the bookmarklet while browsing to save pages
5. Open `https://cloudmark.site/your-mark` to manage bookmarks
## Chrome Extension
The Manifest V3 extension saves the active tab with an existing or new category and adds page/link actions to Chrome's context menu.
### Install from GitHub Releases
1. Download [`cloudmark-chrome.zip`](https://github.com/wesleyel/cloudmark/releases/latest/download/cloudmark-chrome.zip).
2. Unzip it to a permanent directory.
3. Open `chrome://extensions` and enable **Developer mode**.
4. Click **Load unpacked** and select the unzipped directory.
5. Configure the collection mark, write token, and Cloudmark server in the popup.
Chrome does not support one-click installation of store-external extensions for regular users. Keep the unzipped directory after loading the extension. New versions are published on the [GitHub Releases page](https://github.com/wesleyel/cloudmark/releases).
For local development, build and load `dist-extension/` instead:
```bash
pnpm install
pnpm build:extension
```
See [`extension/README.md`](extension/README.md) for permissions and development details.
## Local Development
### Prerequisites
- Node.js 20+ and pnpm
- Cloudflare account (for preview and deployment)
### Install Dependencies
```bash
pnpm install
```
### D1 setup
1. Create a D1 database:
```bash
pnpm exec wrangler d1 create cloudmark
```
2. Put the returned `database_id` into `wrangler.jsonc` → `d1_databases[0].database_id`.
3. Apply migrations:
```bash
# local (Miniflare)
pnpm db:migrate:local
# production
pnpm db:migrate:remote
```
### Development Mode
```bash
pnpm dev
```
Visit [http://localhost:3000](http://localhost:3000).
### Local Preview with Cloudflare
```bash
pnpm db:migrate:local
pnpm preview
```
### Build and Deploy
One-click deploy (creates a Cloudflare Worker from this repo):
[](https://deploy.workers.cloudflare.com/?url=https://github.com/wesleyel/cloudmark)
Or from your machine:
```bash
pnpm db:migrate:remote
pnpm run deploy
```
After the first deploy, set `d1_databases[0].database_id` in `wrangler.jsonc` (or via the dashboard) and run migrations.
## Cloudflare Configuration
### D1 Database
```jsonc
"d1_databases": [
{
"binding": "DB",
"database_name": "cloudmark",
"database_id": "your-d1-database-id",
"migrations_dir": "migrations"
}
]
```
### Environment Variables
- `BASE_URL` — public site URL in Worker vars (optional; client uses current origin)
## Technology Stack
- [TypeScript 7](https://www.typescriptlang.org/) — language
- [React](https://react.dev/) + [Vite](https://vite.dev/) — SPA frontend
- [Hono](https://hono.dev/) — Worker API
- [Cloudflare Workers](https://workers.cloudflare.com/) — hosting (`@cloudflare/vite-plugin`)
- [Cloudflare D1](https://developers.cloudflare.com/d1/) — primary data store
- [Tailwind CSS](https://tailwindcss.com/) + shadcn/ui — styling
## License
This project is open-sourced under the [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html) license.
## Contributing
Issues and Pull Requests are welcome!
1. Fork the project
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Contact
If you have any questions, please contact us through GitHub Issues.