Quill

A minimal, self-hosted RSS/Atom/JSON feed reader for one person. Plain PHP (no framework), flat JSON file storage (no database), vanilla HTML/CSS/JS (no build step).

Features

• Add feeds by URL, or paste a site URL and pick one or more of its discovered feeds. Discovery covers <link rel="alternate"> tags, feed links on the page, the site's feed-directory page, conventional paths like /rss.xml, and per-section feeds of news sites.
• Folders (collapsible sidebar tree), Unread/Saved/Notes views, saved searches with live match counts in their own collapsible sidebar group
• Accent-insensitive search across every feed, including the full page text of articles you've opened, captured server-side the first time you open one
• Read/unread and starred tracking, personal notes and tags on items (tag autocomplete, browsable sidebar tag list, a "Notes" view for items with a note attached), per-feed content filters, per-feed enable/disable
• Text highlights: select a passage in an article and press Highlight (click it to remove), with highlighted articles in their own collapsible sidebar group and a choice of highlight color in Settings
• Manual refresh or scheduled refresh (cron/launchd/URL-based), with per-feed refresh intervals (auto-detected from feeds that declare their own, editable otherwise)
• Favicons and item thumbnails resolved automatically, no third-party services
• Visible items (and their images) are prefetched in the background, so opening one is instant
• OPML import/export and full backup/restore (zip/gzip/JSON)
• Update notice when a newer version is on GitHub, with a one-click download of an upload-ready package that leaves your config and data alone
• Multiple accounts, each with its own feeds, folders, saved items, tags, highlights and settings; the admin adds and removes them in Settings (bcrypt passwords, PHP session; no database, no third-party auth)

See the in-app Settings panel and feed row menus for the full interaction surface, or DOCUMENTATION.md for the complete reference.

Setup (local, macOS)

brew install php
cp src/config.sample.php src/config.php   # if not already done
php -S localhost:8000 -t public

Open http://localhost:8000/ and create your login on first visit; that first account is the admin, who can add more accounts under Settings → Users. Data lives under data/ as JSON files, one folder per account in data/users/<id>/. Lost your password? An admin can reset it in Settings → Users; for the only admin, run on the server:

php -r 'require "src/bootstrap.php"; Users::setPassword(Users::findByUsername("YOUR_NAME")["id"], "NEW_PASSWORD");'

Scheduled refresh

cron/refresh.php refreshes every feed past its interval and logs to data/cron.log. Pick one:

• No shell access: enable public/cron.php with a CRON_TOKEN in src/config.php, then hit its URL on a schedule (host cron panel, cron-job.org, GitHub Actions).
• Shell/cron: */15 * * * * php /path/to/rss/cron/refresh.php >> /path/to/rss/data/cron-stderr.log 2>&1
• launchd (macOS): a LaunchAgent plist calling the same script on an interval.

The manual "Refresh all" button always force-refreshes regardless of interval.

Deploying

1. Run bin/package-for-deploy.sh: it builds ./deploy/ from git archive (no local data, ever) and scaffolds src/config.php. Upload its contents; point the doc root at public/ if possible.
2. No custom doc root? .htaccess in data//src/ blocks direct access as a fallback.
3. Optional: HTTP Basic Auth via public/.htaccess as defense-in-depth on top of app login.
4. Set up scheduled refresh (above). Option A (URL cron) works on any host.

Updating

When a higher version number is on GitHub (from src/version.json), the footer shows "Version X available". Click it to open Settings, or use Check for updates there to ask GitHub right away instead of waiting for the hourly check. To release an update, bump that number and push.

From the app (easiest): in Settings → Version, press Download version X. The server builds quill-X.zip from the latest commit on main, using the same exclusions as bin/package-for-deploy.sh. It needs only curl, not the zip extension. The package is update-safe: it contains no src/config.php and nothing from data/ except the tracked templates. Upload the contents of its quill-X/ folder over your install. Safari unzips the download for you.

Manually:

[!WARNING] Pull/download the new version, re-run bin/package-for-deploy.sh, and upload it over the old install.

On your server you can replace public/, cron/, and all of src/ except src/config.php. That one file holds your login credentials and CRON_TOKEN, and overwriting it with the freshly generated one wipes them.

Leave data/ alone entirely.

Project layout

public/          document root: index.html, style.css, app.js, api/*.php, cron.php
src/             PHP classes: Storage, Auth, FeedFetcher, FaviconResolver, FeedDiscovery, RefreshService, OpmlImporter, YouTubeResolver, UpdatePackager
data/            users.json (accounts), users/<user_id>/{feeds.json, items/, items-index/, search-index/, search-counts/, pages/}, cron.log
cron/refresh.php CLI scheduled-refresh entry point (see also public/cron.php)

Every public/api/*.php endpoint requires login except auth.php (users.php and update-package.php require an admin); public/cron.php is unauthenticated but gated by CRON_TOKEN. See inline docblocks / src/ for endpoint details.