RSS-Bridge · Bockiii · Mar 22, 2022 · Mar 12, 2022 · Mar 12, 2022 · Mar 12, 2022
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,27 @@
+name: Documentation
+
+on:
+  push:
+    paths:
+    - 'docs/**'
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        persist-credentials: false
+    - name: Setup PHP
+      uses: shivammathur/setup-php@2.17.1
+      with:
+        php-version: 8.0
+    - name: Install dependencies
+      run: composer global require daux/daux.io
+    - name: Generate documentation
+      run: daux generate
+    - name: Deploy same repository 🚀
+      uses: JamesIves/github-pages-deploy-action@v4.2.5
+      with:
+        folder: "static"
+        branch: gh-pages
diff --git a/docs/01_General/01_Project-goals.md b/docs/01_General/01_Project-goals.md
@@ -0,0 +1,8 @@
+**RSS-Bridge** aims at sites that:
+
+  - don't provide public accessible Atom or RSS feeds
+  - force their users to subscribe to e-mail notifications
+  - force their users to use their own proprietary APIs
+  - require their users to come back on a regular basis in order to check for new content
+
+**RSS-Bridge** will generate feeds based on "bridges" that are developed for any site. Those bridges will collect data and extract all necessary information which is then converted into various feed formats like Atom or RSS.
diff --git a/docs/01_General/02_Contribute.md b/docs/01_General/02_Contribute.md
@@ -0,0 +1,9 @@
+There are many things you can do to contribute to **RSS-Bridge** as developer or as user without any knowledge in PHP or (web) development. Here are a few things:
+
+- Share **RSS-Bridge** with your friends (Twitter, Facebook, ..._you name it_...)
+- Report broken bridges or bugs [here](https://github.com/RSS-Bridge/rss-bridge/issues)
+- Request new features or propose ideas (via [Issues](https://github.com/RSS-Bridge/rss-bridge/issues))
+- Discuss bugs, features, ideas or [issues](https://github.com/RSS-Bridge/rss-bridge/issues)
+- Add new bridges or improve the API
+- Improve this documentation
+- Host **RSS-Bridge**
diff --git a/docs/01_General/03_Requirements.md b/docs/01_General/03_Requirements.md
@@ -0,0 +1,23 @@
+**RSS-Bridge** requires either of the following:
+
+## A Web server* with:
+
+  - PHP 7.1 (or higher)
+  - [`openssl`](https://secure.php.net/manual/en/book.openssl.php) extension
+  - [`libxml`](https://secure.php.net/manual/en/book.libxml.php) extension (enabled by default, see [PHP Manual](http://php.net/manual/en/libxml.installation.php))
+  - [`mbstring`](https://secure.php.net/manual/en/book.mbstring.php) extension
+  - [`simplexml`](https://secure.php.net/manual/en/book.simplexml.php) extension
+  - [`curl`](https://secure.php.net/manual/en/book.curl.php) extension
+  - [`json`](https://secure.php.net/manual/en/book.json.php) extension
+  - [`filter`](https://secure.php.net/manual/en/book.filter.php) extension
+  - [`sqlite3`](http://php.net/manual/en/book.sqlite3.php) extension (only when using SQLiteCache)
+
+Enable extensions by un-commenting the corresponding line in your PHP configuration (`php.ini`).
+
+
+## A Linux server with:
+
+ - Docker server configured (Any recent version should do)
+ - 100MB of disk space
+
+To setup RSS Bridge using Docker, see the [Docker Guide](../03_For_Hosts/03_Docker_Installation.md) on installing RSS Bridge.
diff --git a/docs/01_General/04_Screenshots.md b/docs/01_General/04_Screenshots.md
@@ -0,0 +1,7 @@
+## Welcome screen:
+![welcome screen](../images/screenshot_rss-bridge_welcome.png)
+
+## rss-bridge hashtag (#rss-bridge) search on Twitter:
+_in Atom format (as displayed by Firefox)_
+
+![twitter bridge](../images/screenshot_twitterbridge_atom.png)
diff --git a/docs/01_General/05_FAQ.md b/docs/01_General/05_FAQ.md
@@ -0,0 +1,30 @@
+This page provides a collection of frequently asked questions and their answers. Please check this page before opening a new Issue :revolving_hearts:
+
+* [Why doesn't my bridge show new contents?](#why-doesnt-my-bridge-show-new-contents)
+* [How can I make a bridge update more frequently?](#how-can-i-make-a-bridge-update-more-frequently)
+* [Firefox doesn't show feeds anymore, what can I do?](#firefox-doesnt-show-feeds-anymore-what-can-i-do)
+
+## Why doesn't my bridge show new contents?
+
+RSS-Bridge creates a cached version of your feed in order to reduce traffic and respond faster. The cached version is created on the first request and served for all subsequent requests. On every request RSS-Bridge checks if the cache timeout has elapsed. If the timeout has elapsed, it loads new contents and updates the cached version.
+
+_Notice_: RSS-Bridge only updates feeds if you actively request it, for example by pressing F5 in your browser or using a feed reader.
+
+The cache duration is bridge specific and can last anywhere between five minutes and 24 hours. You can specify a custom cache timeout for each bridge if [this option](#how-can-i-make-a-bridge-update-more-frequently) has been enabled on the server.
+
+## How can I make a bridge update more frequently?
+
+You can only do that if you are hosting the RSS-Bridge instance:
+- Enable [`custom_timeout`](../03_For_Hosts/08_Custom_Configuration.md#customtimeout)
+- Alternatively, change the default timeout for your bridge by modifying the `CACHE_TIMEOUT` constant in the relevant bridge file (e.g [here](https://github.com/RSS-Bridge/rss-bridge/blob/master/bridges/FilterBridge.php#L7) for the Filter Bridge).
+
+## Firefox doesn't show feeds anymore, what can I do?
+
+As of version 64, Firefox removed support for viewing Atom and RSS feeds in the browser. This results in the browser downloading the pages instead of showing contents.
+
+Further reading:
+- https://support.mozilla.org/en-US/kb/feed-reader-replacements-firefox
+- https://bugzilla.mozilla.org/show_bug.cgi?id=1477667
+
+To restore the original behavior in Firefox 64 or higher you can use following Add-on which attempts to recreate the original behavior (with some sugar on top):
+- https://addons.mozilla.org/en-US/firefox/addon/rsspreview/
diff --git a/docs/01_General/06_Public_Hosts.md b/docs/01_General/06_Public_Hosts.md
@@ -0,0 +1,20 @@
+| Flag | Host | Status |  Contact | Comment |
+|:-----------------------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|--------------------------------------------------|----------------------------------------------------------------------------|
+|  ![🇮🇳](https://iplookup.flagfox.net/images/h16/IN.png) | ![](https://www.google.com/s2/favicons?sz=16&domain_url=https://rss-bridge.bb8.fun) [rss-bridge.bb8.fun](https://rss-bridge.bb8.fun) | ![Status](https://img.shields.io/website/https/rss-bridge.bb8.fun.svg) | [@captn3m0](https://github.com/captn3m0) | Hosted in Bengaluru, India |
+|  ![🇳🇱](https://iplookup.flagfox.net/images/h16/NL.png) | ![](https://www.google.com/s2/favicons?domain=feed.eugenemolotov.ru) [feed.eugenemolotov.ru](https://feed.eugenemolotov.ru) | ![Status](https://img.shields.io/website/https/feed.eugenemolotov.ru.svg) | [@em92](https://github.com/em92) | Hosted in Amsterdam, Netherlands |
+|  ![🇫🇷](https://iplookup.flagfox.net/images/h16/FR.png) | ![](https://www.google.com/s2/favicons?domain=bridge.suumitsu.eu) [bridge.suumitsu.eu](https://bridge.suumitsu.eu/) | ![Status](https://img.shields.io/website/https/bridge.suumitsu.eu.svg) | [@mitsukarenai](https://github.com/mitsukarenai) | Hosted in Paris, France |
+|  ![🇫🇷](https://iplookup.flagfox.net/images/h16/FR.png) | ![](https://www.google.com/s2/favicons?sz=16&domain_url=https://sebsauvage.net/rss-bridge/) [sebsauvage.net/rss-bridge](https://sebsauvage.net/rss-bridge/) | ![Status](https://img.shields.io/website/https/sebsauvage.net/rss-bridge.svg) | [@sebsauvage](https://github.com/sebsauvage/) | Hosted in France |
+|  ![🇫🇮](https://iplookup.flagfox.net/images/h16/FI.png) | ![](https://www.google.com/s2/favicons?domain=rss-bridge.snopyta.org) [rss-bridge.snopyta.org](https://rss-bridge.snopyta.org) | ![Status](https://img.shields.io/website/https/rss-bridge.snopyta.org.svg) | [@Perflyst](https://github.com/Perflyst) | Hosted in Helsinki, Finland |
+|  ![🇩🇪](https://iplookup.flagfox.net/images/h16/DE.png) | ![](https://www.google.com/s2/favicons?domain=rss.nixnet.xyz) [rss.nixnet.xyz](https://rss.nixnet.xyz/) | ![Status](https://img.shields.io/website/https/rss.nixnet.xyz.svg) | [@amolith](https://nixnet.xyz/contact) | Hosted in Wunstorf, Germany |
+|  ![🇫🇷](https://iplookup.flagfox.net/images/h16/FR.png) | ![](https://www.google.com/s2/favicons?sz=16&domain_url=https://myrss4fun.xyz/) [myrss4fun.xyz](https://myrss4fun.xyz) | ![Status](https://img.shields.io/website/https/rss-bridge.bb8.fun.svg)| [@mrcoding](https://github.com/mrcoding/) | Latest GitHub Release |
+|  ![🇫🇷](https://iplookup.flagfox.net/images/h16/FR.png) | ![](https://www.google.com/s2/favicons?domain=bridge.easter.fr) [bridge.easter.fr](https://bridge.easter.fr/) | ![Status](https://img.shields.io/website/https/bridge.easter.fr.svg) | [@chatainsim](https://github.com/chatainsim) | Hosted in Roubaix, France |
+|  ![🇫🇷](https://iplookup.flagfox.net/images/h16/FR.png) | ![](https://www.google.com/s2/favicons?sz=16&domain_url=https://wtf.roflcopter.fr/rss-bridge) [wtf.roflcopter.fr/rss-bridge](https://wtf.roflcopter.fr/rss-bridge/) | ![Status](https://img.shields.io/website/https/wtf.roflcopter.fr/rss-bridge.svg) | [roflcopter.fr](https://wtf.roflcopter.fr/) | Hosted in France |
+| ![LT](https://iplookup.flagfox.net/images/h16/LT.png) | ![](https://www.google.com/s2/favicons?domain=rssbridge.fossdaily.xyz) [rssbridge.fossdaily.xyz](https://rssbridge.fossdaily.xyz) | ![Status](https://img.shields.io/website/https/rssbridge.fossdaily.xyz.svg) |  | Hosted in Vilnius, Lithuania |
+|  ![AT](https://iplookup.flagfox.net/images/h16/AT.png) | https://rss-bridge.ggc-project.de | ![Status](https://img.shields.io/website/https/rss-bridge.ggc-project.de) | [@ggc-project.de](https://social.dev-wiki.de/@ggc_project) | Hosted in Steyr, Austria |
+|  ![US](https://iplookup.flagfox.net/images/h16/US.png) | https://bridge.noisebridge.info | ![Status](https://img.shields.io/website/https/bridge.noisebridge.info) | [Discuss Forum](https://discuss.noisebridge.info) | Hosted in United States |
+|  ![🇳🇱](https://iplookup.flagfox.net/images/h16/NL.png) | ![](https://www.google.com/s2/favicons?sz=16&domain_url=https://feeds.proxeuse.com) [feeds.proxeuse.com](https://feeds.proxeuse.com/) | ![Status](https://img.shields.io/website/https/feeds.proxeuse.com) | [Proxeuse](https://www.proxeuse.com/en/contact-us) | Hosted in Germany |
+|  ![🇷🇺](https://iplookup.flagfox.net/images/h16/RU.png) | ![](https://www.google.com/s2/favicons?domain_url=ololbu.ru/rss-bridge) [ololbu.ru/rss-bridge/](https://ololbu.ru/rss-bridge) | ![Status](https://img.shields.io/website/https/ololbu.ru) | [@Ololbu](https://github.com/Ololbu) | Hosted in Moscow, Russia |
+|  ![🇩🇪](https://iplookup.flagfox.net/images/h16/DE.png) | ![](https://www.google.com/s2/favicons?domain=tools.bheil.net/rss-bridge/) [tools.bheil.net/rss-bridge/](https://tools.bheil.net/rss-bridge/) | ![Status](https://img.shields.io/website/https/tools.bheil.net.svg) | [@bheil](https://www.bheil.net) | Hosted in Germany |
+|  ![🇩🇪](https://iplookup.flagfox.net/images/h16/DE.png) | ![](https://www.google.com/s2/favicons?domain=rss-bridge.mediani.de) [rss-bridge.mediani.de](https://rss-bridge.mediani.de/) | ![Status](https://img.shields.io/website/https/rss-bridge.mediani.de.svg) | [@sokai](https://github.com/sokai) | Hosted with Netcup, Germany |
+|  ![🇫🇷](https://iplookup.flagfox.net/images/h16/FR.png) | ![](https://www.google.com/s2/favicons?domain=rssbridge) [rssbridge.boldair.dev](https://rssbridge.boldair.dev/) | ![Status](https://img.shields.io/website?down_color=red&down_message=down&up_color=lime&up_message=up&url=https%3A%2F%2Frssbridge.boldair.dev) | [@Boldairdev](https://github.com/Boldairdev) | Latest Github release, Hosted on PHP 8.0 in Roubaix, France |
+|  ![🇨🇦](https://iplookup.flagfox.net/images/h16/CA.png) | ![](https://www.google.com/s2/favicons?sz=16&domain_url=https://rss-bridge.esmailelbob.xyz/) [rss-bridge.esmailelbob.xyz](https://rss-bridge.esmailelbob.xyz/) | ![Status](https://img.shields.io/website/https/rss-bridge.esmailelbob.xyz.svg)| [@esmaiellbobdev2](https://github.com/esmailelbobve2/) | Latest GitHub Release |
diff --git a/docs/02_CLI/index.md b/docs/02_CLI/index.md
@@ -0,0 +1,36 @@
+RSS-Bridge supports calls via CLI. You can use the same parameters as you would normally use via the URI. Example:
+
+`php index.php action=display bridge=DansTonChat format=Json`
+
+## Required parameters
+
+RSS-Bridge requires a few parameters that must be specified on every call. Omitting these parameters will result in error messages:
+
+### action
+
+Defines how RSS-Bridge responds to the request.
+
+Value | Description
+----- | -----------
+`action=list` | Returns a JSON formatted list of bridges. Other parameters are ignored.
+`action=display` | Returns (displays) a feed.
+
+### bridge
+
+This parameter specifies the name of the bridge RSS-Bridge should return feeds from. The name of the bridge equals the class name of the bridges in the ./bridges/ folder without the 'Bridge' prefix. For example: DansTonChatBridge => DansTonChat.
+
+### format
+
+This parameter specifies the format in which RSS-Bridge returns the contents. RSS-Bridge currently supports five formats: `Atom`, `Html`, `Json`, `Mrss`and `Plaintext`.
+
+## Optional parameters
+
+RSS-Bridge supports optional parameters. These parameters are only valid if the options have been enabled in the index.php script.
+
+### _noproxy
+
+This parameter is only available if a proxy server has been specified via `PROXY_URL` and 'PROXY_BYBRIDGE' has been enabled. This is a Boolean parameter that can be set to '1' (true) or '0' (false).
+
+## Bridge parameters
+
+Each bridge can specify its own set of parameters. As in the example above, some bridges don't specify any parameters or only optional parameters that can be neglected. For more details read the `PARAMETERS` definition for your bridge.
diff --git a/docs/03_For_Hosts/01_Installation.md b/docs/03_For_Hosts/01_Installation.md
@@ -0,0 +1,12 @@
+In order to install RSS-Bridge on your own web server* do as follows:
+
+* Make sure your web server meets all [requirements](../01_General/03_Requirements.md)
+* Download the ZIP file of the [last stable release](https://github.com/RSS-Bridge/rss-bridge/releases)
+* Place all files on your web server
+
+For linux hosts:
+* Grant read-write-access for `www-data` to the `./cache` directory (`chown -R www-data ./cache`)
+
+You have successfully installed RSS-Bridge.
+
+Instructions for Docker setups are at [Docker Installation](../03_For_Hosts/03_Docker_Installation.md)
diff --git a/docs/03_For_Hosts/02_Updating.md b/docs/03_For_Hosts/02_Updating.md
@@ -0,0 +1,42 @@
+Updating an existing installation is very simple, depending on your type of installation.
+
+## Release Build
+
+* Download latest version
+* Extract all files
+* Replace existing files
+
+This will update all core files to the latest version. Your custom configuration and bridges are left untouched. Keep in mind that changes to any core file of RSS-Bridge will be replaced.
+
+## Docker
+
+Simply get the latest Docker build via `:latest` or specific builds via `:<tag-name>`.
+
+## Heroku
+
+### If you didn't fork the repo before
+
+Fork the repo by clicking the `Fork` button at the top right of this page (must be on desktop site). Then on your Heroku account, go to the application. Click on the `Deploy` tab and connect the repo named `yourusername/rss-bridge`. Do a manual deploy of the `master` branch.
+
+### If you forked the repo before
+
+[Click here to create a new pull request to your fork](https://github.com/RSS-Bridge/rss-bridge/pull/new/master). Select `compare across forks`, make the base repository `yourusername/rss-bridge` and ensure the branch is set to master. Put any title you want and create the pull request. On the page that comes after this, merge the pull request.
+
+You then want to go to your application in Heroku, connect your fork via the `Deploy` tab and deploy the `master` branch.
+
+You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future. 
+
+## Git
+
+To get the latest changes from the master branch
+
+```
+git pull
+```
+
+To use a specific tag
+
+```
+git fetch --all
+git checkout tags/<tag-name>
+```
diff --git a/docs/03_For_Hosts/03_Docker_Installation.md b/docs/03_For_Hosts/03_Docker_Installation.md
@@ -0,0 +1,58 @@
+This guide is for people who want to run RSS Bridge using Docker. If you want to run it a simple PHP Webhost environment, see [Installation](../03_For_Hosts/01_Installation.md) instead.
+
+## Setup
+
+### Create the container
+
+```bash
+docker create \
+--name=rss-bridge \
+--volume </local/custom/path>:/config \
+--publish 3000:80 \
+rssbridge/rss-bridge:latest
+```
+### Run it
+```bash
+docker start rss-bridge
+```
+
+And access it using `http://IP_Address:3000`. If you'd like to run a specific version, you can run it by:
+
+```bash
+docker create \
+--name=rss-bridge \
+--volume </local/custom/path>:/config \
+--publish 3000:80 \
+rssbridge/rss-bridge:$version
+```
+
+Where you can get the versions published to Docker Hub at https://hub.docker.com/r/rssbridge/rss-bridge/tags/. The server runs on port 80 internally, and you can publish it on a different port (change 3000 to your choice).
+
+You can run it using a `docker-compose.yml` as well:
+
+```yml
+version: '2'
+services:
+  rss-bridge:
+    image: rssbridge/rss-bridge:latest
+    volumes:
+      - </local/custom/path>:/config
+    ports:
+      - 3000:80
+    restart: unless-stopped
+```
+
+# Container access and information
+
+|Function|Command|
+|----|----|
+|Shell access (live container)|`docker exec -it rss-bridge /bin/sh`|
+|Realtime container logs|`docker logs -f rss-bridge`|
+
+# Adding custom bridges and configurations
+If you want to add a bridge that is not part of [`/bridges`](https://github.com/RSS-Bridge/rss-bridge/tree/master/bridges), you can specify an additional folder to copy necessary files to the `rss-bridge` container.
+
+_Here **root** is folder where `docker-compose.yml` resides._
+1. Create `custom` folder in root. 
+2. Copy your [bridges files](../05_Bridge_API/01_How_to_create_a_new_bridge.md) to the `custom` folder. You can also add your custom [whitelist.txt](../03_For_Hosts/05_Whitelisting.md) file and your custom [config.ini.php](../03_For_Hosts/08_Custom_Configuration.md) to this folder.
+3. Run `docker-compose up` to recreate service.
diff --git a/docs/03_For_Hosts/04_Heroku_Installation.md b/docs/03_For_Hosts/04_Heroku_Installation.md
@@ -0,0 +1,25 @@
+This guide is for people who want to run RSS Bridge on [Heroku](https://heroku.com).
+
+You can run it on Heroku for free, however make sure your RSS reader interval is not set to a fast rate, otherwise your Heroku hours will use up quicker. Heroku puts the app to sleep after 30 mins of no activity. When the app is asleep no Heroku hours are used. So choose an interval that won't make the app exceed the limit!
+
+You can increase your Heroku hours to 1000 a month from 550 a month by simply verifying your account with a credit card.
+
+## Deploy button
+You can simply press the button below to easily deploy RSS Bridge on Heroku and use the default bridges. Or you can follow the manual instructions given below.
+
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/RSS-Bridge/rss-bridge)
+
+## Manual deploy
+1. Fork this repo by clicking the Fork button at the top right of this page (only on desktop site)
+
+![image](../images/fork_button.png)
+
+2. To customise what bridges can be used if need, create a `whitelist.txt` file in your fork and follow the instructions given [here](../03_For_Hosts/05_Whitelisting.md). You don’t need to do this if you’re fine with the default bridges.
+
+3. [Log in to Heroku](https://dashboard.heroku.com) and create a new app. The app name will be the URL of the RSS Bridge (appname.herokuapp.com)
+
+4. Go to Deploy, select the GitHub option and connect your GitHub account. Search for the repo named `yourusername/rss-bridge`
+
+![image](../images/heroku_deploy.png)
+
+5. Deploy the master branch.