README.md

news2reader

Server that offers webpages from popular news aggregators as EPUB files via ODPS, for consumption via e-reader software (such as KOReader).

What it does

Many e-readers and other e-book reading software support browsing and downloading e-books from sources called OPDS Catalogs. (Wikipedia) (Supported software)

news2reader acts as an OPDS Catalog, but instead of listing books it lists current articles from sources like Hacker News, Tildes.net, and Pocket. When you select an article for download, the article is automatically converted into a readable EPUB file and downloaded to your device.

Screenshots

How it works

news2reader is powered mainly by:

• OPDS (the protocol)
• Node.js (the JavaScript runtime)
• TypeScript (the programming language)
• Express (the web framework)
• Readability (for making readable versions of web pages)
• epub-gen (for turning readable web pages into EPUB files)

How to run it

Run via Docker

Docker images are available for amd64, arm/v7, and arm64/v8 architectures.

docker run --expose 8080 bhspitmonkey/news2reader:main

Or, to add to a Docker Compose stack:

version: "3.9"
services:
  server:
    image: bhspitmonkey/news2reader:main
    container_name: news2reader
    restart: unless-stopped
    volumes:
      - ./config/:/root/.config/news2reader/
    ports:
      - 8080:8080

You will need to mount a config directory at /root/.config/news2reader/ in the container (as shown above).

Run via Node.js

(Tested using Node 22.x)

yarn install
yarn start

How to use it

Start by opening the homepage in a web browser to make sure the application is running as expected. This might be at the URL http://localhost:8080, but this could vary based on how you've configured things so be sure to replace localhost:8080 in these examples with the appropriate host and port in your situation.

You should see a simple status page including instructions for (optionally) setting up a Pocket account.

Next, you'll need to add a new ODPS catalog into whichever e-reader software you are using. If using KOReader, you navigate from the main screen to 🔎 » ODPS catalog, then tap the "+" icon in the corner to begin adding a new catalog. The catalog URL is just the URL you're running the server at, plus /odps at the end (for example: http://localhost:8080).

How to build it

Run the development server (which will hot-reload and recompile on the fly):

yarn install
yarn run dev

License

MIT (see LICENSE.md for the full terms)