feat: the app

README.md

@@ -0,0 +1,144 @@
+# LinkDing
+
+LinkDing is a modern bookmarking application where you can paste links and get a list of links with title, description, and image. After a link is pasted, the page is scraped for metadata including the main product image that is then displayed in the link list. It is primarily used to make a list of links to products that you may want to buy.
+
+## Features
+
+- ✅ Paste links and get a list of links with title, description, and image
+- ✅ Automatic metadata extraction (title, description, product images)
+- ✅ Search functionality by title, description, and URL
+- ✅ Modern, responsive web interface
+- ✅ Smart image extraction from product containers
+- ✅ Support for JavaScript-heavy sites using Puppeteer
+- ✅ Automatic fallback from HTTP scraping to browser rendering
+
+## Tech Stack
+
+- **Backend**: Express.js (Node.js)
+- **Frontend**: Vanilla JavaScript, HTML5, CSS3
+- **Web Scraping**: Cheerio + Puppeteer (for JavaScript-heavy sites)
+- **Data Storage**: JSON file
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+ (or Docker)
+- Chromium/Chrome (for Puppeteer support, optional)
+
+### Local Installation
+
+1. Clone the repository or navigate to the project directory:
+   ```bash
+   cd linkding
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Start the server:
+   ```bash
+   npm start
+   ```
+
+4. Open your browser to `http://localhost:3000`
+
+### Docker Installation
+
+1. Build the Docker image:
+   ```bash
+   docker build -t linkding .
+   ```
+
+2. Run the container:
+   ```bash
+   docker run -d \
+     --name linkding \
+     -p 3000:3000 \
+     -v $(pwd)/data:/app/data \
+     linkding
+   ```
+
+   Or use Docker Compose:
+   ```bash
+   docker-compose up -d
+   ```
+
+3. Access the application at `http://localhost:3000`
+
+## Usage
+
+1. **Add a Link**: Paste a URL into the input field and click "Add Link"
+2. **Search**: Use the search bar to filter links by title, description, or URL
+3. **View Links**: Browse your saved links with images, titles, and descriptions
+4. **Delete Links**: Click the "Delete" button on any link card to remove it
+
+## API Endpoints
+
+- `GET /api/links` - Get all saved links
+- `GET /api/links/search?q=query` - Search links
+- `POST /api/links` - Add a new link (body: `{ "url": "https://example.com" }`)
+- `DELETE /api/links/:id` - Delete a link by ID
+
+## Metadata Extraction
+
+The application automatically extracts:
+
+- **Title**: From Open Graph tags, JSON-LD structured data, or HTML `<h1>`/`<title>` tags
+- **Description**: From meta tags, structured data, or page content
+- **Images**: Prioritizes product container images, then meta tags, with smart fallbacks
+
+### Image Extraction Priority
+
+1. Product container images (`.product-container img`, etc.)
+2. Product-specific image containers
+3. Open Graph / Twitter Card meta tags
+4. JSON-LD structured data
+5. Generic product selectors
+6. Fallback to meaningful images
+
+## Environment Variables
+
+- `PORT` - Server port (default: 3000)
+- `CHROME_EXECUTABLE_PATH` - Path to Chrome/Chromium executable (for Puppeteer)
+- `NODE_ENV` - Environment mode (production/development)
+
+## Data Storage
+
+Links are stored in `data/links.json`. Make sure this directory exists and is writable. When using Docker, mount the `data` directory as a volume for persistence.
+
+## Troubleshooting
+
+### Puppeteer Issues
+
+If you encounter issues with Puppeteer:
+
+1. **NixOS**: The app uses `puppeteer-core` and automatically detects system Chromium
+2. **Docker**: Chromium is included in the Docker image
+3. **Manual Setup**: Set `CHROME_EXECUTABLE_PATH` environment variable to your Chromium path
+
+### 403 Errors
+
+Some sites block automated requests. The app automatically:
+- First tries HTTP requests with realistic headers
+- Falls back to Puppeteer for JavaScript rendering if blocked
+- Uses system Chromium for browser automation
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode with auto-reload
+npm run dev
+
+# Start production server
+npm start
+```
+
+## License
+
+ISC