LLAR Configuration

fetch

Define a source, its source tags, UI options, and optional item processing hooks.

(fetch src-key src & body)

(fetch github-llar-releases
  (src/feed "https://github.com/irq0/llar/releases.atom")
  :tags #{:github :release})

fetch-reddit

Define a Reddit source with a generated source key and the source tag :reddit.

(fetch-reddit src & body)

(fetch-reddit (src/reddit "clojure" :top :week)
  :min-score 50
  :tags #{:programming})

sched-fetch

Schedule updates for all fetchable sources matching a predicate.

(sched-fetch SCHED-NAME CHIME-TIMES PREDICATE)

(sched-fetch my-feeds :now-and-hourly
  (some #{:my-feed-group} $TAGS))

autoread

Automatically remove :unread from old items fetched from matching sources.

(autoread SCHED-NAME PERIOD PREDICATE)

(autoread reddit-ages-fast (time/weeks 4)
  (some #{:reddit} $TAGS))

highlight

Add :highlight to items matching configured words or authors.

(highlight words|authors VALUE...)

(highlight words "llar" "rss")
(highlight authors "Douglas Engelbart")

sort-default

Set the default sort order for a Reader group item or the :all home view.

(sort-default TAG-KEY SORT-ORDER)

(sort-default :all :ranked)
(sort-default :blog :ranked)

rc

Read or set dynamic runtime behavior config. Reads resolve runtime overrides first, system config values that differ from shipped defaults second, and shipped defaults last.

(rc PATH VALUE)

(rc [:reader :ranking :highlight-boost-hours] 48)
(rc [:reader :default-list-view :storage] :headlines)

reader-favorites

Set the complete ordered reader favorite navigation list.

(reader-favorites FAVORITES)

(reader-favorites
 [[:all :default]
  [:saved :item-tags]
  [:highlight :item-tags]
  [:bookmark :type]])

reader-default-list-view

Set the default reader list style for one group item.

(reader-default-list-view KEY STYLE)

(reader-default-list-view :storage :headlines)
(reader-default-list-view :tweet :gallery)

reader-ranking

Set reader ranking tuning values.

(reader-ranking KEY VALUE ...)

(reader-ranking :highlight-boost-hours 48
                :rarity-boost-cap-hours 168)

reader-url-handler

Configure reader annotation export through an external URL handler.

(reader-url-handler CONFIG)

(reader-url-handler :name "Org-roam"
                    :icon "fas fa-brain"
                    :template "org-protocol://roam-ref?ref={url}&title={title}&body={body}")

podcast-retention

Override podcast retention for a source.

(podcast-retention SOURCE-KEY LIMIT)

(podcast-retention my-video-feed 10)

digest

Configure and enable digest delivery.

(digest KEY VALUE ...)

(digest :to "you_abc123@kindle.com"
        :from "llar@example.org"
        :limit 200
        :inline-images? true
        :keep-unread-issues 1)

podcast-download

Configure and enable podcast media downloads.

(podcast-download KEY VALUE ...)

(podcast-download :video-format "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]/bestvideo[height<=1080]+bestaudio/best[height<=1080][vcodec!=none]/bestvideo+bestaudio/best[vcodec!=none]"
                  :extra-args ["--embed-metadata" "--embed-chapters"]
                  :max-attempts 3
                  :retry-cooldown-minutes 30)

src/website

Generic website fetch.

(src/website url & {:as args})

(src/website "https://example.org/article.html")

src/custom

Custom function source returning LLAR item data.

(src/custom id fn)

(src/custom :my-source (fn [] []))

src/demo

Deterministic, network-free editorial content for demos and UI development.

(src/demo publication & {:as args})

{:count 8, :seed 4242}

(src/demo :signal-wire :count 8 :seed 4242)

src/website+paywall

Website fetch using a cookie store function.

(src/website+paywall url cookie-getter & {:as args})

(src/website+paywall "https://example.org" cookie-store)

src/feed

RSS, Atom, and similar feed formats.

(src/feed url & {:as args})

{:user-agent :default, :force-update? false}

(src/feed "https://github.com/irq0/llar/releases.atom")

src/selector-feed

Build a feed from an HTML page using Hickory selectors.

(src/selector-feed url selectors extractors args)

(src/selector-feed "https://example.org" {:urls (S/tag :a)} {} {})

src/wp-json

WordPress REST API posts.

(src/wp-json url & {:as args})

{:user-agent :default, :force-update? false}

(src/wp-json "https://example.org/wp-json/")

src/twitter-search

Twitter search source.

(src/twitter-search query oauth-creds)

(src/twitter-search "clojure" ($credentials :twitter-api))

src/twitter-timeline

Twitter home timeline source.

(src/twitter-timeline oauth-creds)

(src/twitter-timeline ($credentials :twitter-api))

src/readability

Single web page processed through article extraction.

(src/readability url & {:as args})

(src/readability "https://example.org/article.html")

src/reddit

Reddit listing source.

(src/reddit subreddit listing)
(src/reddit subreddit listing timeframe)

(src/reddit "clojure" :top :week)

src/imap

IMAP or IMAPS mailbox source using credentials from credentials.edn.

(src/imap url-str creds)

(src/imap "imaps://imap.example.org/INBOX" ($credentials :imap))

src/hn

Hacker News via Algolia.

(src/hn tag & {:as args})

{:count 1000}

(src/hn :front_page :query "clojure" :min-score 20)

src/streaming-channel

Streaming collection source such as supported video/audio channels or playlists.

(src/streaming-channel url & {:as args})

{:max-results 30}

(src/streaming-channel "https://www.youtube.com/@veritasium")

src/github-issues

Search GitHub issues/PRs. Query uses GitHub search syntax. Date tokens like {{last-week}} are expanded at fetch time.

(src/github-issues query & {:as args})

{:per-page 30, :order :desc}

(src/github-issues "repo:ceph/ceph is:pr created:>{{last-week}}")

src/github-repos

Search GitHub repositories. Query uses GitHub search syntax. Date tokens like {{last-week}} are expanded at fetch time.

(src/github-repos query & {:as args})

{:per-page 30, :order :desc}

(src/github-repos "language:clojure stars:>20" :sort :stars)

zotero-export-links

credentials.edn

{:zotero {:api-key "ZOTERO_API_KEY"
          :user-id "ZOTERO_USER_ID"}}

Dashboard

Config path: [:api :dashboard]

Administrative UI and Prometheus metrics endpoint. It starts when :port is present.

Example

:dashboard {:port 9999}

Reader

Config path: [:api :reader]

The browser-based reader. It starts when :port is present; :base-url is used when LLAR builds absolute reader links.

Example

:reader {:port 8023
         :base-url "https://reader.example.org"}

Bookmark capture

Config path: [:api :capture]

A reader-independent, durable save-for-later API for browser bookmarklets and iOS/macOS Shortcuts. It starts when :port is present.

• Expose the service through HTTPS and have the reverse proxy preserve the Authorization header. The write endpoint is POST <base-url>/api/v1/captures with a JSON body containing url and optional title. The feedback assets and API use relative URLs, so :base-url may include a reverse-proxy path; keep its trailing slash in the bookmarklet. The service intentionally has no CORS support, cookies, or token-management UI.
• Tokens. Generate a separate revocable token for each client with openssl rand -hex 32, store only the values in credentials.edn, restrict that file to the LLAR account (for example chmod 600 credentials.edn), and restart LLAR after changing them. Tokens must have at least 32 base64url-safe characters. A malformed or missing credential entry prevents the capture service from starting.
• Firefox/Chrome bookmarklet. Create a bookmark whose URL is the following one-line script, replacing the public base URL and the token belonging to that browser:

  javascript:location.href='https://save.example.org/#REPLACE_WITH_TOKEN:'+location.href

  The current tab navigates to LLAR's feedback page. LLAR removes the secret fragment before making the authenticated request and reports success only after the database commit; use Back to return to the page. Keeping the token out of query parameters prevents it from entering proxy access logs.
• Treat the bookmark itself as a credential: browser bookmark sync may copy its token to other signed-in devices. Use a token dedicated to that browser profile and revoke it from credentials.edn if the profile or synced account is compromised.
• iOS/macOS Shortcut. Create a Shortcut that accepts URLs from the Share Sheet, uses Get Contents of URL on https://save.example.org/api/v1/captures with method POST, JSON body {"url": <Shortcut Input>}, and header Authorization: Bearer <iphone token>. Finish with Show Result using the response's message. Treat a non-2xx response as not saved; HTTP 409 means the existing failed capture needs Retry or Dismiss in the dashboard.
• Queue operations. The dashboard's Bookmarks tab shows ready, processing, retry-wait, failed, and complete captures plus Retry/Dismiss recovery actions. The scheduler claims at most one leased capture per run. Set :schedule to a canned schedule keyword; it defaults to :now-and-every-minute. A duplicate pending capture returns already queued, a complete one returns already saved, and failed or dismissed captures are never implicitly recaptured.
• Minimal alerts. Alert on a capture delayed more than 15 minutes with llar_bookmark_queue_items{state="ready"} > 0 and on() (time() - llar_bookmark_queue_oldest_ready_unixtime > 900), and on manual intervention with llar_bookmark_queue_items{state="failed"} > 0. The first means the capture latency objective is breached (stalled worker or sustained backlog); inspect the Bookmarks tab, the generic schedule metrics, and source/item-pool saturation. The second is resolved by Retry after correcting the cause, or Dismiss when the URL should be abandoned.

Example

:capture {:port 8026
          :base-url "https://save.example.org"
          :credentials :bookmark-capture
          :schedule :now-and-every-minute}

;; credentials.edn
{:bookmark-capture
 {:tokens {:iphone "<64 hex characters>"
           :macbook "<64 hex characters>"
           :firefox "<64 hex characters>"}}}

Podcast

Config path: [:api :podcast]

HTTP service for downloaded podcast and video media. It starts when :port is present.

Example

:podcast {:host "127.0.0.1"
          :port 8024
          :base-url "https://media.example.org"
          :retention {:default-episode-limit 25}}

Fever-compatible sync

Config path: [:api :fever]

Mobile sync endpoint for Fever clients such as Fiery Feeds and ReadKit. It starts when :port is present.

• Only sources carrying :source-tag (default :mobile) are exposed.
• Clients authenticate with the Fever MD5 API key derived from username and the dedicated password.
• The working-set defaults are 30 initial days, 10 recent-read days, and 1048576 content bytes.
• :base-url is important. Set it to the externally reachable URL of this Fever endpoint, including any reverse-proxy path. Privacy-rewritten images and media are stored in the local blobstore and served by this endpoint at <base-url>/blob/<hash>. Content is rewritten to those absolute URLs so mobile clients can load them; without a correct :base-url the relative /blob/ URLs break on the phone. The endpoint must be exposed over HTTPS.

Example

:fever {:port 8025
        :base-url "https://reader.example.org/api/fever"
        :username "llar"
        :credentials :mobile-sync
        :source-tag :mobile}

;; credentials.edn
{:mobile-sync {:password "replace-me"}}

Digest delivery

Config path: [:api :digest]

Scheduled EPUB delivery to an e-reader address. This is not an HTTP API and requires top-level :mail configuration.

Example

:digest {:to "you_abc123@kindle.com"
         :from "llar@example.org"
         :schedule :sundays
         :keep-unread-issues 1
         :inline-images? true}