From 618ce380e7f6a10b481b9cf32f861d1e01689505 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Tue, 14 Nov 2023 23:28:01 +0100 Subject: More WebSub doc (#5862) * More WebSub doc * UI for WebSub + more documentation And spellcheck Frech * Links to WebSub doc from readme * Add link to WebSub doc in admin interface * Fix checkbox * Plural --- docs/en/users/WebSub.md | 54 +++++++++++++++++++++++++++++++++---- docs/fr/users/08_PubSubHubbub.md | 57 +++++++++++++++++++++++++++++++--------- 2 files changed, 94 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/en/users/WebSub.md b/docs/en/users/WebSub.md index e8499b8e5..86abcde20 100644 --- a/docs/en/users/WebSub.md +++ b/docs/en/users/WebSub.md @@ -7,20 +7,64 @@ for instance when a new article is available via RSS / ATOM. FreshRSS supports WebSub natively. Just like for the FreshRSS API to work from a mobile phone, supporting WebSub requires that your FreshRSS instance is routable (that is to say, with a public IP, that can be accessed from third-party servers). -## Examples of feeds +## WebSub terminology -Many individual feeds and platforms already offer instant notifications through WebSub, such as: -[Friendica instances](https://friendi.ca), WordPress (from WordPress.com or with [an extension](https://wordpress.org/plugins/pubsubhubbub/)), Blogger sites, Medium sites, etc. +There are tree main concepts: + +* **publisher**: Web site publishing content such as RSS / ATOM feeds; +* **subscriber**: Feed aggregator such as FreshRSS; +* **hub**: Intermediate technical component in charge of notifying all subscribers instantly when a publisher has some new content. +The same hub can serve several publishers and their subscribers. +Some publishers have a built-in hub. + +## Enabling WebSub in FreshRSS + +FreshRSS supports WebSub natively, but requires a public address (read from the `base_url` configuration), +and requires the `./FreshRSS/p/api/` folder to be publicly accessible (just like for other FreshRSS APIs). + +During the initial Web-based setup, support for WebSub is enabled if the server hosting FreshRSS appears to have a public address. +In any case, check your `./data/config.php` for: -## Test WebSub +```php +'base_url' => 'https://freshrss.example.net/', +'pubsubhubbub_enabled' => true, +``` + +Additional logs about WebSub are available in `./FreshRSS/data/users/_/log_pshb.txt` + +## Test WebSub compatibility of your FreshRSS instance You can test that WebSub works properly in your FreshRSS instance with a service such as: * +When you create a new article, it should instantly be available in your FreshRSS instance. + +## Examples of feeds using WebSub + +Many individual feeds and platforms already offer instant notifications through WebSub, such as: +[Friendica instances](https://friendi.ca), WordPress (from WordPress.com or with [an extension](https://wordpress.org/plugins/pubsubhubbub/)), Blogger sites, Medium sites, etc. + +## Test WebSub compatibility of an RSS / ATOM feed + +* (for any feed) +* (for feeds you control) + ## Add WebSub to your RSS / ATOM feeds -Your CMS (e.g. WordPress) might already offer WebSub as an option. Otherwise, you can make a solution that notifies a hub such as: +Your CMS (e.g. WordPress) might already offer WebSub as an option, such as: + +* + +Otherwise, you can make a solution that notifies a hub, such as: * * + +Or even deploy your own hub, such as: + +* + +## Test WebSub compatibility of a hub + +* diff --git a/docs/fr/users/08_PubSubHubbub.md b/docs/fr/users/08_PubSubHubbub.md index ee46916b4..b1b78330d 100644 --- a/docs/fr/users/08_PubSubHubbub.md +++ b/docs/fr/users/08_PubSubHubbub.md @@ -1,13 +1,13 @@ -# Qu’est-ce que [WebSub](https://www.w3.org/TR/websub/) ? +# Qu’est-ce que WebSub ? -Derrière ce nom (anciennement [PubSubHubbub](https://github.com/pubsubhubbub/PubSubHubbub)) se cache un protocole qui vient compléter Atom et RSS. +Derrière le nom de [WebSub](https://www.w3.org/TR/websub/) (anciennement [PubSubHubbub](https://github.com/pubsubhubbub/PubSubHubbub)) se cache un protocole qui vient compléter Atom et RSS. En effet, le fonctionnement de base de ces deux derniers implique de vérifier à intervalles réguliers s’il existe de nouveaux articles sur les sites suivis. Cela même si le site concerné n’a rien publié depuis la dernière synchronisation. Le [protocole WebSub](https://www.w3.org/TR/websub/) permet d’éviter des synchronisations inutiles en notifiant en temps réel l’agrégateur de la présence de nouveaux articles. ## Fonctionnement de WebSub -On va retrouver trois notions dans WebSub : les éditeurs (les sites qui publient du contenu), les abonnés (les agrégateurs de flux RSS) et les hubs. +On va retrouver trois notions dans WebSub : **les éditeurs** (les sites qui publient du contenu comme des flux ATOM / RSS), **les abonnés** (les agrégateurs de flux RSS comme FreshRSS), et **les hubs**. Lorsqu’un agrégateur s’abonne à un site et récupère son flux RSS, il peut y trouver l’adresse d’un hub. Si c’est le cas — car un site peut ne pas en préciser —, l’agrégateur va s’abonner au hub et non pas à l’éditeur directement. @@ -15,21 +15,54 @@ Ainsi, lorsqu’un éditeur va publier du contenu, il va notifier le hub qui va Pour pouvoir être notifié, les abonnés doivent fournir une adresse accessible publiquement sur Internet. -## WebSub et FreshRSS +## Activer WebSub dans FreshRSS -Depuis la version 1.1.2-beta, FreshRSS supporte officiellement WebSub. -Vous pouvez donc recevoir en temps réel les articles des sites qui affichent dans leur flux RSS un « hub », -tels [Friendica](https://friendi.ca), WordPress (WordPress.com ou avec [une extension](https://wordpress.org/plugins/pubsubhubbub/)), Blogger, Medium, etc. +FreshRSS supporte nativement WebSub, mais requiert une addresse publique (lu depuis la configuration `base_url`), +et requiert aussi aussi que le répertoire `./FreshRSS/p/api/` soit accessible publiquement (comme pour les autres APIs de FreshRSS). + +Durant l’installation Web initiale, le support de WebSub est activé si le serveur semble avoir une adresse publique. +Dans tous les cas, vérifiez votre `./data/config.php` pour : + +```php +'base_url' => 'https://freshrss.example.net/', +'pubsubhubbub_enabled' => true, +``` + +Des logs supplémentaires relatifs à WebSub sont consultables dans `./FreshRSS/data/users/_/log_pshb.txt` + +## Tester la compatibilité WebSub de votre instance FreshRSS + +Vous pouvez tester que le support WebSub de votre instance FreshRSS est correct avec un service comme : + +* + +Quand vous y créez un nouvel article, celui-ci devrait être immédiatement disponible dans votre FreshRSS. -## Tester WebSub +## Tester la compatibilité WebSub d’un flux RSS / ATOM -Vous pouver tester que le support WebSub de votre instance FreshRSS est correct avec un service comme : +* (pour n’importe quel flux) +* (pour les flux que vous contrôlez) -* +## Exemples de flux utilisant WebSub + +Vous pouvez recevoir en temps réel les articles des sites qui affichent dans leur flux RSS un « hub », +tels [Friendica](https://friendi.ca), WordPress (WordPress.com ou avec [une extension](https://wordpress.org/plugins/pubsubhubbub/)), Blogger, Medium, etc. ## Ajouter WebSub à votre flux RSS / ATOM -Votre CMS (par exemple WordPress) supporte peut-être déjà WebSub en option. Sinon, vous pouvez faire une solution qui notifie un hub tel : +Votre CMS (par exemple WordPress) supporte peut-être déjà WebSub en option, comme : + +* + +Sinon, vous pouvez faire une solution qui notifie un hub, comme : -* +* * + +Ou encore déployer votre propre hub, comme : + +* + +## Tester la compatibilité WebSub d’un hub + +* -- cgit v1.2.3