Skip to content

About

A web-based chronological visualization of Pinboard bookmarks

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

PinboardViz

A web-based chronological visualization of Pinboard bookmarks.

What It Does

  • Loads bookmarks from a Pinboard JSON export and renders them as a horizontal timeline of colored dots — like a filmstrip or photo gallery.
  • Hover any dot to see a tooltip with the page title, URL, date, tags, and a live screenshot of the website (captured on first hover, cached to disk for instant repeat views).
  • Click any dot to open the original URL in a new tab.
  • Date range filter (top bar) to narrow the timeline to any period. Defaults to the last 30 days.
  • Search box to filter by description, tags, URL, or notes.
  • Drag or scroll wheel to pan horizontally through the timeline.
  • Axis labels show months or years depending on the visible time span.

Screenshot

┌──────────────────────────────────────────────────────────────────┐
│ Pinboard Timeline   From [2026-04-17] to [2026-05-17]  [Search]  285 bookmarks │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│    ○ ○ ● ○ ○ ○ ● ● ○ ○ ● ○ ○ ○ ● ● ○ ○ ● ○ ○ ● ● ○ ○ ● ○     │
│  ──●──────────────────────────────────────────────────●──       │
│         │  │     │  │  │     │     │  │  │     │  │  │         │
│        Apr              May                                    │
├──────────────────────────────────────────────────────────────────┤
│  2026-04-17 → 2026-05-17                                        │
└──────────────────────────────────────────────────────────────────┘

Hover tooltip:

┌──────────────────────────────┐
│  ┌────────────────────────┐  │
│  │   (screenshot image)   │  │
│  └────────────────────────┘  │
│  Alan Kay at UCLA CS 201     │
│  youtube.com                 │
│  5/17/2026, 12:00:37 AM      │
│  [alankay]                   │
└──────────────────────────────┘

Project Structure

PinboardViz/
  server.py        # Flask backend — data API + screenshot capture
  index.html       # Frontend — single-file, no build step
  screenshots/     # Cached website thumbnails (auto-created, gitignored)
  README.md        # This file
  .gitignore       # Excludes screenshots/, Python artifacts, OS files

Prerequisites

  • Python 3.9+
  • Flask 3.x
  • Playwright (with Chromium)

Quick Start

# Clone the repository
git clone https://github.com/<your-username>/PinboardViz.git
cd PinboardViz

# Install dependencies
pip install flask playwright

# Install Playwright's Chromium browser
python -m playwright install chromium

# Configure your data path (see below), then run:
python server.py

# Open in browser: http://localhost:5150/

Configuration

Edit the constants at the top of server.py:

Variable Default Description
DATA_PATH (required) Absolute path to your Pinboard JSON export file
SCREENSHOT_DIR ./screenshots/ Where cached thumbnails are stored
VIEWPORT_W 1280 Screenshot width in pixels
VIEWPORT_H 720 Screenshot height in pixels
SCREENSHOT_TIMEOUT 15000 Max milliseconds to wait for a page to load

The server runs on port 5150 by default. Change the port in the app.run() call at the bottom of server.py.

Getting Your Pinboard Data

Export your bookmarks from Pinboard as JSON, then set DATA_PATH in server.py to the downloaded file's location.

How Screenshots Work

  1. When you hover a dot, the frontend checks if a screenshot is already cached in the browser's memory for this session.
  2. If not, it sends a POST /api/capture request to the backend.
  3. The backend uses Playwright (headless Chromium) to navigate to the URL, wait for the page to load, and capture a viewport-sized screenshot.
  4. The PNG is saved to the screenshots/ directory.
  5. Subsequent hovers serve the cached file directly — no re-capture needed.

Screenshots that fail (timeout, unreachable host, bot protection, etc.) show a fallback message in the tooltip. Navigate away and hover again to retry.

The screenshots/ directory is excluded from version control via .gitignore. It is safe to delete at any time — screenshots will be re-captured on next hover.

API Reference

GET /

Serves the frontend (index.html).

GET /api/stats

Returns dataset statistics.

Response:

{
  "count": 76778,
  "dated_count": 76776,
  "undated_count": 2,
  "min": "2006-02-15T10:29:21Z",
  "max": "2026-05-17T00:32:11Z"
}

GET /api/bookmarks

Returns bookmark data, filterable by date range and search query.

Query parameters:

Parameter Type Default Description
start date — Inclusive start date (ISO format, e.g. 2025-01-01)
end date — Inclusive end date
search string — Full-text search across description, tags, URL, notes
limit int 5000 Max results (capped at 10000)
offset int 0 Pagination offset

Response:

{
  "total": 143,
  "offset": 0,
  "limit": 5000,
  "bookmarks": [
    {
      "href": "https://example.com/article",
      "description": "Article Title",
      "extended": "User notes…",
      "tags": "tag1 tag2",
      "time": "2025-01-15T12:00:00Z",
      "shared": "yes",
      "toread": "no",
      "hash": "a1b2c3d4e5f6g7h8"
    }
  ]
}

POST /api/capture

Triggers a screenshot capture for a given URL. Called by the frontend on first hover.

Request body:

{
  "url": "https://example.com",
  "hash": "a1b2c3d4e5f6g7h8"
}

Response (success):

{ "ok": true, "hash": "a1b2c3d4e5f6g7h8" }

GET /screenshot/<hash>

Returns a cached PNG screenshot. Returns 404 if not yet captured.

Data Format

The input file is a Pinboard JSON export — a JSON array of objects:

Field Description
href URL of the bookmarked page
description Page title or user-provided title
extended User notes (may contain HTML)
tags Space-separated tag string
time ISO 8601 timestamp (UTC)
shared "yes" or "no"
toread "yes" or "no"
meta Internal Pinboard metadata hash
hash Internal Pinboard URL hash

Entries with a timestamp of 1970-01-01T00:00:00Z (Unix epoch) are treated as undated and excluded from the timeline by default. This is Pinboard's sentinel value for bookmarks with no saved date.

Browser Compatibility

The frontend uses vanilla ES6+ JavaScript with no build step and no dependencies. It works in any modern browser (Chrome, Firefox, Safari, Edge).

Performance Notes

  • The full dataset is loaded into memory at server startup. RAM usage scales with bookmark count (roughly 3-5 KB per bookmark).
  • The frontend fetches up to 10,000 bookmarks per request. For very wide date ranges, dots may overlap visually — this is intentional (density = activity).
  • Screenshots are captured one at a time. Hovering many dots quickly will queue captures. Each takes 2-15 seconds depending on the target site.
  • The screenshots/ directory grows over time as you explore. Safe to delete to free disk space.

Troubleshooting

Problem Solution
Server won't start — port in use Change the port in server.py: app.run(..., port=5150)
Screenshots always fail Ensure Playwright Chromium is installed: python -m playwright install chromium
Date filter returns no results Check that your date range overlaps the data range shown in /api/stats
Page loads but no dots appear Open browser console (F12) for JS errors; verify server is running on the expected port
Out of memory Use a narrower date range or reduce the limit parameter

License

MIT

About

A web-based chronological visualization of Pinboard bookmarks

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages