Merge branch 'main' into feat/docker-tips

Author: supahgreg

.github/workflows/lint.yml

@@ -9,27 +9,29 @@ on:
   # Allow other workflows (e.g. Pages) to invoke this one.
   workflow_call:
 
-permissions:
-  contents: read
-  statuses: write
+permissions: {}
 
 jobs:
   super-linter:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      statuses: write
     steps:
       - name: Checkout
         uses: actions/checkout@v5
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Run Super-Linter
         uses: super-linter/super-linter/slim@v8
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEFAULT_BRANCH: main
-          # Validate all files on push/workflow_dispatch, only changed files on
-          # PRs
+          # Validate all files on push/workflow_dispatch, only changed files on PRs
           VALIDATE_ALL_CODEBASE: >-
             ${{ github.event_name != 'pull_request' }}
+          # VALIDATE_GITHUB_ACTIONS_ZIZMOR: true
           VALIDATE_MARKDOWN: true
+          # VALIDATE_NATURAL_LANGUAGE: true
           VALIDATE_YAML: true

.github/workflows/pages.yml

@@ -4,6 +4,12 @@ name: Build and deploy Pages
 on:
   push:
     branches: [main]
+    paths-ignore:
+    - '.github/**'
+    - '.*'
+    - CONTRIBUTING.md
+    - LICENSE
+    - README.md
   # Allow manual triggering
   workflow_dispatch:
 

docs/API-Reference.md

@@ -1,15 +1,13 @@
 ---
 layout: default
 title: API Reference
-nav_order: 3
+nav_order: 60
 ---
 
-{: .no_toc }
-
 ## Table of contents
 {: .no_toc .text-delta }
 
-1. TOC
+- TOC
 {:toc}
 
 ---
@@ -80,7 +78,7 @@ are not supported.
 
 ## Methods
 
-### getApiLevel (since version:1.5.8, api level-1)
+### getApiLevel (since version:1.5.8, api level 1)
 
 Return an abstracted integer API version level, increased with each API
 functionality change. This is the proper way to detect host API
@@ -128,11 +126,11 @@ password parameters.
 
 - On version:1.6.0 and above login also returns current API level as an
   <code>api\_level</code> integer, you can use that instead of calling `getApiLevel` after login.
-- Since API 17, also returns configuration object (see `getConfig`-below).
+- Since API 17, also returns configuration object (see [`getConfig`](#getconfig) below).
 
 ### logout
 
-Closes your login session. Returns either status-message <code>{"status":"OK"}</code> or an error (e.g.-<code>{"error":"NOT_LOGGED_IN"}</code>)
+Closes your login session. Returns either status message <code>{"status":"OK"}</code> or an error (e.g. <code>{"error":"NOT_LOGGED_IN"}</code>)
 
 ### isLoggedIn
 
@@ -162,8 +160,7 @@ Parameters:
 - ``unread_only`` (bool) - only return feeds which have unread articles
 - ``limit`` (integer) - limit amount of feeds returned to this value
 - ``offset`` (integer) - skip this amount of feeds first
-- ``include_nested`` (bool) - include child categories (as Feed-objects
-    ``with is_cat set)`` **requires version:1.6.0**
+- ``include_nested`` (bool) - include child categories (as Feed objects with `is_cat` set) **requires version:1.6.0**
 
 Pagination:
 
@@ -174,12 +171,12 @@ instead.
 Special category IDs are as follows:
 
 * 0 Uncategorized
-* -1 Special (e.g. Starred, Published, Archived,-etc.)
+* -1 Special (e.g. Starred, Published, Archived, etc.)
 * -2 Labels
 
 Added in version:1.5.0:
 
-- -3 All feeds, excluding virtual feeds (e.g. Labels and-such)
+- -3 All feeds, excluding virtual feeds (e.g. Labels and such)
 - -4 All feeds, including virtual feeds
 
 Known bug: Prior to version:1.5.0 passing null or 0 cat\_id to this
@@ -201,7 +198,7 @@ categories is returned and unread counters include counters for child
 categories.
 
 This should be used as a starting point, to display a root list of all
-(for backwards-compatibility) or topmost categories, use getFeeds to
+(for backwards compatibility) or topmost categories, use [`getFeeds`](#getfeeds) to
 traverse deeper.
 
 ### getHeadlines
@@ -210,14 +207,14 @@ Returns JSON-encoded list of headlines.
 
 Parameters:
 
-- ``feed_id`` (integer|string) - only output articles for this feed (supports string values to retrieve tag virtual feeds since API level 18, otherwise-integer)
-- ``limit`` (integer) - limits the amount of returned articles (see-below)
+- ``feed_id`` (integer|string) - only output articles for this feed (supports string values to retrieve tag virtual feeds since API level 18, otherwise integer)
+- ``limit`` (integer) - limits the amount of returned articles (see below)
 - ``skip`` (integer) - skip this amount of feeds first
 - ``filter`` (string) - currently unused (?)
-- ``is_cat`` (bool) - requested feed\_id is a category
+- ``is_cat`` (bool) - requested `feed_id` is a category
 - ``show_excerpt`` (bool) - include article excerpt in the output
 - ``show_content`` (bool) - include full article text in the output
-- ``view_mode`` (string = all\_articles, unread, adaptive,-marked,
+- ``view_mode`` (string = all\_articles, unread, adaptive, marked,
     updated)
 - ``include_attachments`` (bool) - include article attachments (e.g.
     enclosures) **requires version:1.5.3**
@@ -230,24 +227,22 @@ Parameters:
 - ``sanitize`` (bool) - sanitize content or not **requires version:1.8**
     (default:-true)
 - ``force_update`` (bool) - try to update feed before showing headlines
-    **requires version:1.14 (api-9)** (default: false)
+    **requires version:1.14 (api 9)** (default: false)
 - ``has_sandbox`` (bool) - indicate support for sandboxing of iframe
     elements **<span class="10 api"></span>** (default: false)
 - ``include_header`` (bool) - adds status information when returning
     headlines, instead of array(articles) return value changes to
-    array(header,-array(articles)) (api-12)
+    array(header, array(articles)) (api 12)
 
 Limit:
 
 Before **API level 6** maximum amount of returned headlines is capped at
 60, API 6 and above sets it to 200.
 
-This parameters might change in the future (supported since **API-level
-2**):
+These parameters might change in the future (supported since **API level 2**):
 
-- ``search`` (string) - search query (e.g. a list of-keywords)
-- ``search_mode`` (string) - all\_feeds, this\_feed (default), this\_cat
-    (category containing requested-feed)
+- ``search`` (string) - search query (e.g. a list of keywords)
+- ``search_mode`` (string) - `all_feeds`, `this_feed` (default), `this_cat` (category containing requested feed)
 - ``match_on`` (string) - ignored
 
 Special feed IDs are as follows:
@@ -271,13 +266,13 @@ Update information on specified articles.
 
 Parameters:
 
-- ``article_ids`` (comma-separated list of-integers) - article IDs to
+- ``article_ids`` (comma-separated list of integers) - article IDs to
     operate on
 - ``mode`` (integer) - type of operation to perform (0 - set to false, 1--
     set to true, 2 - toggle)
-- ``field`` (integer) - field to operate on (0 - starred, 1 - published, 2 - unread, 3 - article note **since api level-1**)
+- ``field`` (integer) - field to operate on (0 - starred, 1 - published, 2 - unread, 3 - article note **since api level 1**)
 - ``data`` (string) - optional data parameter when setting note field
-    (since **api level-1**)
+    (since **api level 1**)
 
 E.g. to set unread status of articles X and Y to false use the
 following:
@@ -312,9 +307,9 @@ Returns tt-rss configuration parameters:
 - ``icons_dir`` - path to icons on the server filesystem
 - ``icons_url`` - path to icons when requesting them over http
 - ``daemon_is_running`` - whether update daemon is running
-- ``num_feeds`` - amount of subscribed feeds (this can be used to-refresh
+- ``num_feeds`` - amount of subscribed feeds (this can be used to refresh
     feedlist when this amount changes)
-- ``custom_sort_types`` - map of plugin-provided article sort types (API-17+)
+- ``custom_sort_types`` - map of plugin-provided article sort types (API 17+)
 
 ### updateFeed
 
@@ -324,7 +319,7 @@ aborted by the HTTP server.
 
 - ``feed_id`` (integer) - ID of feed to update
 
-Returns status-message if the operation has been completed.
+Returns status message if the operation has been completed.
 
 ```json
 {"status":"OK"}
@@ -344,15 +339,15 @@ Returns preference value of specified key.
 
 Required version: version:1.4.3
 
-Tries to catchup (e.g. mark as-read) specified feed.
+Tries to catchup (e.g. mark as read) specified feed.
 
 Parameters:
 
 - ``feed_id`` (integer) - ID of feed to update
 - ``is_cat`` (boolean) - true if the specified feed\_id is a category
 - ``mode`` (string) - optional: one of `all`, `1day`, `1week`, `2week`. defaults to `all`. **since api level 15**.
 
-Returns status-message if the operation has been completed.
+Returns status message if the operation has been completed.
 
 ```json
 {"status":"OK"}
@@ -379,7 +374,7 @@ to “flc”):
 Several global counters are returned as well, those can’t be disabled
 with output\_mode.
 
-### getLabels (since API level-1)
+### getLabels (since API level 1)
 
 Returns list of configured labels, as an array of label objects:
 
@@ -402,7 +397,7 @@ Parameters:
 
 * ``article_id`` (int) - set “checked” to true if specified article id has returned label.
 
-### setArticleLabel (since API level-1)
+### setArticleLabel (since API level 1)
 
 Assigns article\_ids to specified label.
 
@@ -413,9 +408,9 @@ Parameters:
 * ``assign`` (boolean) - assign or remove label
 
 Note: Up until version:1.15 setArticleLabel() clears the label cache for
-the specified articles. Make sure to regenerate it (e.g. by calling-API
+the specified articles. Make sure to regenerate it (e.g. by calling API
 method getLabels() for the respecting articles) when you’re using
-methods which don’t do that by themselves (e.g.-getHeadlines())
+methods which don’t do that by themselves (e.g. getHeadlines())
 otherwise getHeadlines() will not return labels for modified articles.
 
 ### shareToPublished (since API level 4 --version:1.6.0)
@@ -437,7 +432,7 @@ subscribe\_to\_feed() in functions.php for details.
 Parameters:
 
 * ``feed_url`` - Feed URL (string)
-* ``category_id`` - Category id to place feed into (defaults to 0,-Uncategorized) (int)
+* ``category_id`` - Category id to place feed into (defaults to 0, Uncategorized) (int)
 * ``login``, ``password`` - Self explanatory (string)
 
 ### unsubscribeFeed (API level 5 --version:1.7.6)

docs/Android-Client.md

@@ -1,30 +1,30 @@
 ---
 layout: default
 title: Android Client
-nav_order: 40
+parent: Legacy
 ---
 
 ## **IMPORTANT**
 
 * The original tt-rss-android project, hosted at <https://tt-rss.org/> and its various subdomains,
-  [will be gone after 2025-11-01](https://community.tt-rss.org/t/the-end-of-tt-rss-org/7164).
+  went away on 2025-11-01.
 * There are currently no plans to continue maintaining the app.
 * The app's source code may be found at <https://github.com/tt-rss/tt-rss-android>.
-* **APK downloads from <https://gitlab.tt-rss.org/tt-rss/tt-rss-android/-/releases> are no longer working.  This is likely permanent.**
+* APKs that were available at <https://gitlab.tt-rss.org/tt-rss/tt-rss-android/-/releases> are gone.
 * This page's content should only be treated as a historical reference.
-* Refer to <https://github.com/tt-rss/tt-rss/discussions/29> for more information.
+* Refer to <https://github.com/tt-rss/tt-rss-android/discussions/8> for more information.
 
 ## Screenshots
 
-[<img src="images/tt-rss-android/Screenshot_20250509_135136.webp" width="120" align="left" alt="Android app main feed view">](images/tt-rss-android/Screenshot_20250509_135136.webp)
+[<img src="../images/tt-rss-android/Screenshot_20250509_135136.webp" width="120" align="left" alt="Android app main feed view">](../images/tt-rss-android/Screenshot_20250509_135136.webp)
 
-[<img src="images/tt-rss-android/Screenshot_20250509_135154.webp" width="120" align="left" alt="Android app article list">](images/tt-rss-android/Screenshot_20250509_135154.webp)
+[<img src="../images/tt-rss-android/Screenshot_20250509_135154.webp" width="120" align="left" alt="Android app article list">](../images/tt-rss-android/Screenshot_20250509_135154.webp)
 
-[<img src="images/tt-rss-android/Screenshot_20250509_135217.webp" width="120" align="left" alt="Android app article view">](images/tt-rss-android/Screenshot_20250509_135217.webp)
+[<img src="../images/tt-rss-android/Screenshot_20250509_135217.webp" width="120" align="left" alt="Android app article view">](../images/tt-rss-android/Screenshot_20250509_135217.webp)
 
-[<img src="images/tt-rss-android/Screenshot_20250509_135426.webp" width="120" align="left" alt="Android app settings">](images/tt-rss-android/Screenshot_20250509_135426.webp)
+[<img src="../images/tt-rss-android/Screenshot_20250509_135426.webp" width="120" align="left" alt="Android app settings">](../images/tt-rss-android/Screenshot_20250509_135426.webp)
 
-[<img src="images/tt-rss-android/Screenshot_20250509_135438.webp" width="120" alt="Android app preferences">](images/tt-rss-android/Screenshot_20250509_135438.webp)
+[<img src="../images/tt-rss-android/Screenshot_20250509_135438.webp" width="120" alt="Android app preferences">](../images/tt-rss-android/Screenshot_20250509_135438.webp)
 
 ## Download
 

docs/Archived-Feed.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Archived Feed
-nav_order: 41
+parent: Features
 ---
 
 Archived is the place for articles for which originating feed no longer exists.

docs/Content-Filters.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Content Filters
-nav_order: 20
+parent: Features
 ---
 
 Filters are a very powerful and flexible tool which may significantly ease the
@@ -37,8 +37,9 @@ final matching.
 all rules match.
 - Regular expressions may be matched against several article fields, such
 as, title, content, author, etc.
-- Do not include delimiters (e.g.-<code>/</code>) when writing regular
-expressions.
+
+{: .warning }
+> Do not include delimiters (e.g. <code>/</code>) when writing regular expressions.
 
 ### Matching articles and applying actions
 

docs/Email-Digests.md

@@ -1,18 +1,18 @@
 ---
 layout: default
 title: Email Digests
-nav_order: 42
+parent: Features
 ---
 
-Users may opt into receiving daily (sent once every 24-hours) digests of unread headlines via email.
+Users may opt into receiving daily (sent once every 24 hours) digests of unread headlines via email.
 
-Digests are sent out by the update daemon or if running <code>update.php —feeds</code>
+Digests are sent out by the update daemon or if running <code>update.php --feeds</code>
 manually. At most 15 messages are sent in one batch.
 
 {: .note }
 > [PHPMailer plugin](https://github.com/tt-rss/tt-rss-plugin-mailer-smtp) is required to send mail under Docker.
 
 
-* Digests may be customized by editing ``templates/digest_template*.txt``.
+* Digests may be customized by copying `digest_template.txt` and `digest_template_html.txt` from `templates/` to `templates.local/`
+  and modifying the new files' contents as desired.
 * You can preview your digest contents in preferences.
-

docs/Encryption.md

@@ -1,12 +1,14 @@
 ---
 layout: default
 title: Encryption
-nav_order: 43
+parent: Security
 ---
 
-Transparent at rest encryption is optionally supported for sensitive data stored in the database, currently limited to stored session data and passwords for feeds with authentication enabled.
+Transparent at-rest encryption is optionally supported for sensitive data stored in the database,
+currently limited to stored session data and passwords for feeds with authentication enabled.
 
-To enable, [global configuration](Global-Config) option `TTRSS_ENCRYPTION_KEY` should be set to a 32-byte hex string of random bytes, which may be generated using CLI like this:
+To enable, [global configuration](Global-Config) option `TTRSS_ENCRYPTION_KEY` should be set to a 32-byte hex string of random bytes,
+which may be generated using CLI like this:
 
 ```sh
 php ./update.php --gen-encryption-key
@@ -15,4 +17,6 @@ php ./update.php --gen-encryption-key
 If enabled, existing plaintext login sessions are automatically encrypted when used, plaintext feed passwords are encrypted on feed update.
 
 {: .warning }
-> Automatic encryption of plaintext data is a one-way process. If you decide to disable `TTRSS_ENCRYPTION_KEY` afterwards, all encrypted sessions would become invalid and you will get logged out. Feed passwords would become unreadable until you either enable encryption back using same key or edit feeds manually.
+> Automatic encryption of plaintext data is a one-way process. If you decide to disable `TTRSS_ENCRYPTION_KEY` afterwards, all encrypted sessions would
+> become invalid and you will get logged out. Feed passwords would become unreadable until you either enable encryption back using same key or edit feeds
+> manually.