# 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