Page

· · to read

Self-host your bookmarks on WordPress.

A token-protected REST API, a one-click browser extension, and the admin tooling you already know.

What is LinkStash?

LinkStash turns any WordPress site into a personal bookmark archive — inspired by Linkding and Delicious, but built natively on the platform you already trust to host the rest of your content. Every URL you save is a real WordPress post, searchable, taggable, and reachable from anywhere a wp-json request can land.

No SaaS. No reading-list company quietly closing in three years. No “export your data before it’s gone” emails. The data lives on your server, alongside everything else you already self-host.

Why LinkStash

You already run WordPress. That’s the whole pitch. If you’ve got a working install, you’ve got the database, the auth system, the user roles, the admin UI, and the deploy story — LinkStash plugs straight into all of it. No second app to babysit, no second backup to configure.

Your bookmarks are first-class WordPress posts. Custom post type linkstash_bookmark, custom taxonomy linkstash_tag. That means every plugin you already use that operates on posts — backup, search, multilingual, audit logs — works on your bookmarks too, with no extra integration work.

The REST API was designed for extensions, not bolted on. Bearer tokens, an idempotent POST that dedupes by canonical URL, an X-LinkStash-Existing response header so the client knows whether it created or merged, CORS preconfigured for chrome-extension://*. The shape was figured out before any UI code was written, then the admin was layered on top.

Public when you want, private by default. Visibility uses WordPress’s native post_status — publish for shareable, private for the rest. Anonymous visitors only see public bookmarks; logged-in users see public plus their own private; admins see everything.

What’s in the box

In the WordPress admin

  • Quick-add form on the bookmark list screen. Paste a URL, optionally type tags (with autocomplete) and choose visibility, hit save. LinkStash fetches the page title and meta description for you and records whether the URL responded — useful three years later when half the web has rotted.
  • Dashboard widget. A QuickDraft-style “Add bookmark” tile sits on the WordPress dashboard so capture is one click from anywhere in the admin.
  • Lean edit screen. LinkStash uses a small classic-editor form: URL, optional title (falls back to a simplified URL when blank), notes, tags. That’s it.
  • List columns show URL, tags, visibility, and unread/archived badges so triaging a backlog is fast.
  • Settings page under Tools → LinkStash for managing API tokens. Tokens are SHA-256 hashed in storage; the plain value is shown once at creation time and never recoverable.

About the REST API

linkstash/v1 exposes:

  • GET /bookmarks — paged listing, filter by tag, unread, archived, or visibility.
  • POST /bookmarks — idempotent on canonical URL, returns X-LinkStash-Existing: 1 when re-saving an existing record.
  • GET /bookmarks/{id} / PATCH / DELETE — round out CRUD.
  • GET /tags?q= — tag listing with counts that respect visibility.
  • GET /check?url= — the “is this saved?” probe browser extensions use to badge the toolbar icon.

Authentication accepts both WordPress Application Passwords and plugin-issued Bearer tokens; both flow through determine_current_user so they compose with the rest of the WordPress auth stack.

From your browser

The companion Chrome MV3 extension turns any tab into a bookmark. Click the toolbar icon to save the current page, edit a saved entry, or delete it; right-click any link to save it without visiting; watch the badge for a green ✓ when the open tab is already saved. Settings live in the extension’s options page — point it at your LinkStash host, paste your token, done. The extension only requests permission for the host you supply.

→ https://github.com/apermo/linkstash-extension

Getting started

  1. Install the plugin. Currently by uploading the latest release zip from GitHub or from Packagist.
  2. Visit Tools → LinkStash and generate an API token. Copy it — it’s shown once.
  3. (Optional) Install the https://github.com/apermo/linkstash-extension, open its options page, paste your host URL and the token, and start saving.

That’s it. Bookmarks save immediately; everything else (public/private, tags, archived, notes) is incremental.

Privacy

LinkStash doesn’t talk to anything but your WordPress install. The plugin makes one outbound HTTP request per saved URL — to the URL you saved — to fetch the title and meta description. The browser extension only talks to the host you configure on its options page; no analytics, no telemetry, no third-party services. Both projects are GPL-2.0-or-later licensed.

Open source

Both halves live on GitHub:

Issues, pull requests, and discussion are all welcome. The plugin’s roadmap (public sharing pages, multi-user libraries, RSS feeds, import from Pinboard / Netscape HTML / linkding, snapshot via SingleFile, reader-mode extraction) is tracked in the GitHub milestones.