NewsBlur Documentation

NewsBlur utilizes a multi-database strategy to handle different data types efficiently:

• PostgreSQL: Stores relational data requiring ACID guarantees, such as user accounts, feed metadata, subscriptions, recommendations, OAuth tokens, and payment records.
• MongoDB: Handles high-volume document storage with flexible schemas, including stories (MStory), starred stories, read states, classifiers, social data, AI responses, and briefings.
• Redis: Acts as an in-memory cache, message broker, and session store. It manages user data cache, analytics, statistics, Celery brokers, Django cache, and session state.
• Elasticsearch: Powers full-text search and vector-based discovery for feeds (SearchFeed) and stories (SearchStory, DiscoverStory).

The frontend is a Backbone.js single-page application.

Key Directory Structure (media/js/newsblur/):

• reader/: Main reader UI (includes reader.js as the central controller).
• models/: Backbone models (e.g., stories.js, feeds.js).
• views/: Backbone views.
• common/: Shared utilities.

Conventions:

• JavaScript uses snake_case to match the Python codebase.
• The global namespace is NEWSBLUR.reader (for the controller) and NEWSBLUR.assets (for data).

Install the NewsBlur CLI using uv pip and authenticate via OAuth. Note that using the CLI requires a Premium Archive or Premium Pro subscription. On first use, a browser window will open for authorization.

uv pip install newsblur-cli
newsblur auth login

You can change the layout of the story title pane to suit your preference. The available positioning options are:

• Left positioning: Places the story title pane on the left side of the reader.
• Top positioning: Places the story title pane at the top of the reader.
• Bottom positioning: The default setting, placing the story title pane at the bottom of the reader.

To change these settings, navigate to Manage > Preferences within the NewsBlur interface.

Settings for auto-marking stories as read cascade from folders down to individual feeds. This allows you to organize feeds by consumption style (e.g., a 'News' folder with a 2-day limit and a 'Must Read' folder set to 'Never').

Inheritance Rules:

• Default: The feed or folder inherits the setting from its parent folder or the site-wide setting.
• Days: Sets a specific duration for that folder or feed.
• Never: Disables auto-marking for that specific folder or feed.

Status text below the slider in the settings UI will indicate whether the current setting is inherited from a parent/site-wide preference or is an explicit override.

To use the extension during development:

1. Build and run the app from Xcode.
2. Open Safari and navigate to Settings → Extensions.
3. Enable NewsBlur Archive.
4. Grant the Allow on All Websites permission.

To install the extension manually in developer mode:

1. Open chrome://extensions (or edge://extensions).
2. Enable Developer mode.
3. Click Load unpacked.
4. Select the clients/browser-extension directory.

To upgrade to Django 1.10 or 1.11, install the required dependencies and run migrations.

pip install -r requirements.txt
./manage.py migrate

Your existing NewsBlur intelligence (classifiers) automatically applies to stories in the Widely Read Stories and Long Reads feeds. This means:

• Tags, Authors, and Title/Text classifiers will score these stories.
• Stories will display the same green and red intelligence scoring based on your training (e.g., if you have marked an author as disliked or a tag as interesting).

You can automate data movement between NewsBlur and other web services using IFTTT (if this then that). This allows you to automatically copy saved stories to services like Evernote, Twitter, or Pinboard, or move data from services like Tumblr or 500px into NewsBlur.

Customizable Triggers

When creating IFTTT recipes, you can customize the triggers to filter which stories are processed based on:

• Specific tags
• Specific blurblogs
• Specific folders
• Specific feeds
• Unread focus (trained) stories: You can choose to only trigger recipes for stories that have been filtered/highlighted using the NewsBlur Intelligence Trainer.