Refactor News documentation with mkdocs and mkdocs-material
- move all pages to new structure - use gh-pages to host html version - use github actions for automatic build Co-authored-by: anoy <anoymouserver+github@mailbox.org> Signed-off-by: Benjamin Brahmer <info@b-brahmer.de>
This commit is contained in:
Benjamin Brahmer
parent
271b6ee3c9
commit
79e469fd33
|
|
@ -0,0 +1,23 @@
|
|||
name: Publish docs via GitHub Pages
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
|
||||
jobs:
|
||||
build:
|
||||
name: Deploy docs
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout master
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Deploy docs
|
||||
uses: mhausenblas/mkdocs-deploy-gh-pages@master
|
||||
# Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
#CUSTOM_DOMAIN: optionaldomain.com
|
||||
#CONFIG_FILE: folder/mkdocs.yml
|
||||
#EXTRA_PACKAGES: build-base
|
||||
# GITHUB_DOMAIN: github.myenterprise.com
|
||||
|
|
@ -10,6 +10,7 @@ js/*.xml
|
|||
.rvm
|
||||
*.clover
|
||||
.phpunit.result.cache
|
||||
site/
|
||||
|
||||
# python
|
||||
PKG-INFO
|
||||
|
|
|
|||
39
README.md
39
README.md
|
|
@ -6,45 +6,12 @@
|
|||
|
||||
The News app is an RSS/Atom feed aggregator. It offers a [RESTful API](https://github.com/nextcloud/news/tree/master/docs/externalapi/Legacy.md) for app developers. The source code is [available on GitHub](https://github.com/nextcloud/news)
|
||||
|
||||
## Install
|
||||
See the [install document](https://github.com/nextcloud/news/blob/master/docs/install.md)
|
||||
|
||||
## FAQ
|
||||
* [My browser shows a mixed content warning](https://github.com/nextcloud/news/blob/master/docs/faq/README.md#my-browser-shows-a-mixed-content-warning-connection-is-not-secure)
|
||||
* [I am getting: Exception: Some\\Class does not exist erros in my nextcloud.log](https://github.com/nextcloud/news/blob/master/docs/faq/README.md#i-am-getting-exception-someclass-does-not-exist-erros-in-my-nextcloudlog)
|
||||
* [Feeds are not updated](https://github.com/nextcloud/news/blob/master/docs/faq/README.md#feeds-not-updated)
|
||||
* [Adding feeds that use self-signed certificates](https://github.com/nextcloud/news/blob/master/docs/faq/README.md#adding-feeds-that-use-self-signed-certificates)
|
||||
* [Is There An Subscription URL To Easily Subscribe To Feeds](https://github.com/nextcloud/news/blob/master/docs/faq/README.md#is-there-an-subscription-url-to-easily-subscribe-to-feeds)
|
||||
* [Database table grows too big](https://github.com/nextcloud/news/blob/master/docs/faq/README.md#database-table-grows-too-big)
|
||||
|
||||
## Supported Browsers
|
||||
* Newest Firefox (Desktop, Android, Firefox OS)
|
||||
* Newest Chrome/Chromium (Desktop, Android)
|
||||
## Documentation
|
||||
The documentation can be found [here](https://nextcloud.github.io/news/), the source of the documentation is on [GitHub](https://github.com/nextcloud/news/blob/master/docs)
|
||||
|
||||
## Bugs
|
||||
Please read the [appropriate section in the contributing notices](https://github.com/nextcloud/news/blob/master/CONTRIBUTING.md#issues)
|
||||
|
||||
## Sync Clients
|
||||
Nextcloud News can be synced with the following apps:
|
||||
* [RSS Guard (Windows, Linux, OS/2, Mac OS)](https://github.com/martinrotter/rssguard), [open source](https://github.com/martinrotter/rssguard)
|
||||
* [Nextcloud News Reader (Android)](https://play.google.com/store/apps/details?id=de.luhmer.owncloudnewsreader), [open source](https://github.com/nextcloud/news-android-app)
|
||||
* [OCReader (Android)](https://f-droid.org/repository/browse/?fdid=email.schaal.ocreader), [open source](https://github.com/schaal/ocreader)
|
||||
* [Newsout (Android)](https://play.google.com/store/apps/details?id=com.inspiredandroid.newsout), [open source](https://github.com/SimonSchubert/NewsOut)
|
||||
* [Readrops (Android)](https://f-droid.org/en/packages/com.readrops.app/), [open source](https://github.com/readrops/Readrops)
|
||||
* [CloudNews (iOS)](https://apps.apple.com/app/cloudnews-owncloud-news-reader/id683859706), [open source](https://github.com/owncloud/news-ios-app)
|
||||
* [Fiery Feeds (iOS)](https://apps.apple.com/us/app/fiery-feeds-rss-reader/id1158763303), closed source
|
||||
* [News Checker (Chrome extension)](https://chrome.google.com/webstore/detail/owncloud-news-checker/hnmagnmdnfdhabdlicankfbfhcdgbfhe)
|
||||
* [own News (BlackBerry)](http://appworld.blackberry.com/webstore/content/32767887/)
|
||||
* [FeedSpider (Firefox OS, WebOS, LuneOS)](http://www.feedspider.net/), [open source](https://github.com/OthelloVentures/feedspider)
|
||||
* [fastReader (Windows Phone)](http://www.windowsphone.com/en-us/store/app/fastreader/e55e696d-aa45-4a49-bb1c-a1fc7fdabec1), closed source
|
||||
* [py3status](https://github.com/ultrabug/py3status/) for [i3 (UNIX-like)](http://i3wm.org/), [open source](https://github.com/i3/i3)
|
||||
* [newsboat](http://newsboat.org/) for Unix terminal, [open source](https://github.com/newsboat/newsboat)
|
||||
* [Newsie (Ubuntu Touch)](https://open-store.io/app/newsie.martinferretti), [open source](https://gitlab.com/ferrettim/newsie)
|
||||
|
||||
## Custom Themes
|
||||
Nextcloud News can look different with the following themes:
|
||||
* [Nextcloud News Themes](https://github.com/cwmke/nextcloud-news-themes)
|
||||
|
||||
## Updating Notices
|
||||
To receive notifications when a new News app version was released, simply add the following Atom feed in your currently installed News app:
|
||||
|
||||
|
|
@ -59,4 +26,4 @@ To receive notifications when a new News app version was released, simply add th
|
|||
* [Sean Molenaar](https://github.com/SMillerDev)
|
||||
|
||||
### Special thanks to the Feed-IO library
|
||||
Please consider donating to the developer of the RSS parser that powers nextcloud/news: [https://github.com/sponsors/alexdebril](https://github.com/sponsors/alexdebril)
|
||||
Please consider donating to the developer of the RSS parser that powers the Nextcloud News App: [https://github.com/sponsors/alexdebril](https://github.com/sponsors/alexdebril)
|
||||
|
|
|
|||
|
|
@ -3,11 +3,20 @@
|
|||
<id>news</id>
|
||||
<name>News</name>
|
||||
<summary>An RSS/Atom feed reader</summary>
|
||||
<description><
|
||||
<description>< to avoid surprises.
|
||||
- 📲 Synchronize your feeds with multiple mobile or desktop [clients](https://nextcloud.github.io/news/clients/)
|
||||
- 🔄 Automatic updates of your news feeds
|
||||
- 🆓 Free and open source under AGPLv3, no ads or premium functions
|
||||
|
||||
**Important**: To enable feed updates you will need to enable either [Nextcloud system cron](https://docs.nextcloud.org/server/latest/admin_manual/configuration_server/background_jobs_configuration.html#cron) or use [an updater](https://github.com/nextcloud/news-updater) which uses the built in update API and disable cron updates. More information can be found [in the README](https://github.com/nextcloud/news).]]></description>
|
||||
**System Cron is currently required for this app to work**
|
||||
Requirements can be found [here](https://nextcloud.github.io/news/install/#dependencies)
|
||||
The Changelog is available [here](https://github.com/nextcloud/news/blob/master/CHANGELOG.md)
|
||||
|
||||
Create a [bug report](https://github.com/nextcloud/news/issues/new/choose)
|
||||
Create a [feature request](https://github.com/nextcloud/news/discussions/new)
|
||||
Report a [feed issue](https://github.com/nextcloud/news/discussions/new)
|
||||
]]></description>
|
||||
<version>16.0.0</version>
|
||||
<licence>agpl</licence>
|
||||
<author>Benjamin Brahmer</author>
|
||||
|
|
@ -17,8 +26,9 @@ Before you update to a new version, [check the changelog](https://github.com/nex
|
|||
<author>Jan-Christoph Borchardt (former)</author>
|
||||
<namespace>News</namespace>
|
||||
<documentation>
|
||||
<admin>https://github.com/nextcloud/news#readme</admin>
|
||||
<developer>https://github.com/nextcloud/news/tree/master/docs</developer>
|
||||
<user>https://nextcloud.github.io/news/</user>
|
||||
<admin>https://nextcloud.github.io/news/admin/</admin>
|
||||
<developer>https://nextcloud.github.io/news/</developer>
|
||||
</documentation>
|
||||
<category>multimedia</category>
|
||||
<website>https://github.com/nextcloud/news</website>
|
||||
|
|
|
|||
|
|
@ -1,13 +1,9 @@
|
|||
# Documentation
|
||||
# News Documentation
|
||||
|
||||
The News documentation of News uses mkdocs and is hosted [here](https://nextcloud.github.io/news/).
|
||||
As extension of mkdocs, mkdocs-material is used.
|
||||
|
||||
As a developer you can interact with the News app in the following ways:
|
||||
|
||||
* [Use the API for syncing and updating feeds](externalapi/)
|
||||
* [Write plugins](plugins/)
|
||||
* [Add custom CSS for feeds](feedcss/)
|
||||
* [Customize the explore section](explore/)
|
||||
|
||||
|
||||
The News app uses [FeedIO](https://github.com/alexdebril/feed-io) for parsing feeds and full text feeds. FeedIO is a fantastic library so if you contribute or fix bugs, please consider **contributing your changes** back to the library to help others :)
|
||||
Check the resources below for how to install both of them locally.
|
||||
|
||||
* [mkdocs](https://www.mkdocs.org/)
|
||||
* [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,33 @@
|
|||
# Admin
|
||||
Welcome to the Admin documentation this page explains some of the configuration options for news.
|
||||
## System Cron
|
||||
Nextcloud uses Cron to run regular jobs, News relies on the Job system to execute the feed updates.
|
||||
Alternatively you may use an [external updater](https://nextcloud.github.io/news/clients/#update-clients), in this case you need to disable the system cron in the settings.
|
||||
|
||||
## Auto purge count
|
||||
This value represents the maximum amount of read items per feed, which won't be deleted by the cleanup job.
|
||||
For example if the value is 200 there can be maximum 200 read items per feed, unread items are unaffected.
|
||||
If old articles reappear after being read, try to increase this value.
|
||||
To disable this feature use -1.
|
||||
|
||||
## Explore Service
|
||||
If you are using the News app in your company/community it might be interesting to offer your users a bunch of easily to discover default feeds. You could also create a website where people can add and up-vote news feeds like bigger cloud feed readers like Feedly do it or even convert their APIs into a service for the News app (if someone wants to provide one for the News app, feel free to contact us by creating an issue in the bug tracker).
|
||||
|
||||
The URL should be a path to a directory which contains a JSON file in the format of **feeds.LANG_CODE.json** where LANG_CODE is a two character language code (e.g. **en** or **de**).
|
||||
|
||||
For example, entering the URL **https://domain.com/directory** as explore URL will produce the following request for German users:
|
||||
|
||||
GET https://domain.com/directory/feeds.de.json
|
||||
|
||||
**Do not forget to implement [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) in your API, otherwise the request will fail!**
|
||||
|
||||
## Update Interval
|
||||
The update interval is used to determine when the next update of all feeds should be done.
|
||||
You can configure this interval as an administrator.
|
||||
|
||||
### What is a good update interval?
|
||||
That depends on your individual needs.
|
||||
Please keep in mind that the lower you set your update interval, the more traffic is generated.
|
||||
|
||||
### Can I set individual update intervals per feed/user?
|
||||
No, the job framework of Nextcloud is pretty simple.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# External API v1-2 (Legacy)
|
||||
# External API v1-2
|
||||
|
||||
The **News app 1.2** offers a RESTful API
|
||||
|
||||
|
|
@ -629,6 +629,7 @@ This is used to stay up to date.
|
|||
To enable people to write their own update scripts instead of relying on the sequential built in web and system cron, API routes and console commands have been created.
|
||||
|
||||
Updating should be done in the following fashion:
|
||||
|
||||
* Run the cleanup before the update
|
||||
* Get all feeds and user ids
|
||||
* For each feed and user id, run the update command
|
||||
|
|
@ -1,8 +1,10 @@
|
|||
# External API v2 (Draft)
|
||||
|
||||
**Disclaimer:** this API has not been fully implemented yet.
|
||||
|
||||
The **News app** offers a RESTful API which can be used to sync folders, feeds and items. The API also supports [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) which means that you can access the API from your browser using JavaScript.
|
||||
|
||||
In addition, an updater API is exposed which enables API users to run feed updates in parallel using a REST API or ownCloud console API.
|
||||
In addition, an updater API is exposed which enables API users to run feed updates in parallel using a REST API or Nextcloud console API.
|
||||
|
||||
## Conventions
|
||||
This document uses the following conventions:
|
||||
|
|
@ -15,6 +17,7 @@ This document uses the following conventions:
|
|||
In order to only specify the JSON objects once, comments are used to alias them.
|
||||
|
||||
There are two types of aliases:
|
||||
|
||||
* Objects
|
||||
* Object arrays
|
||||
|
||||
|
|
@ -77,19 +80,22 @@ You have to design your app with these things in mind!:
|
|||
## Request Format
|
||||
The base URL for all calls is:
|
||||
|
||||
https://yourowncloud.com/index.php/apps/news/api/v2
|
||||
https://yournextcloud.com/index.php/apps/news/api/v2
|
||||
|
||||
Unless an absolute Url is specified, the relative Urls in the Specification are appended to this url. To access the route **/sync** for instance you'd use the following url:
|
||||
|
||||
https://yourowncloud.com/index.php/apps/news/api/v2/sync
|
||||
https://yournextcloud.com/index.php/apps/news/api/v2/sync
|
||||
|
||||
The required request headers are:
|
||||
|
||||
* **Accept**: application/json
|
||||
|
||||
Any request method except GET:
|
||||
|
||||
* **Content-Type**: application/json; charset=utf-8
|
||||
|
||||
Any route that allows caching:
|
||||
|
||||
* **If-None-Match**: an Etag, e.g. 6d82cbb050ddc7fa9cbb659014546e59. If no previous Etag is known, this header should be omitted
|
||||
|
||||
The request body is either passed in the URL in case of a **GET** request (e.g.: **?foo=bar&index=0**) or as JSON, e.g.:
|
||||
|
|
@ -107,7 +113,7 @@ The request body is either passed in the URL in case of a **GET** request (e.g.:
|
|||
Check the [API level route](#api-level)
|
||||
|
||||
### Authentication
|
||||
Because REST is stateless you have to re-send user and password each time you access the API. Therefore running ownCloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**.
|
||||
Because REST is stateless you have to re-send user and password each time you access the API. Therefore running Nextcloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**.
|
||||
|
||||
Credentials are passed as an HTTP header using [HTTP basic auth](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side):
|
||||
|
||||
|
|
@ -122,21 +128,24 @@ This authentication/authorization method will be the recommended default until c
|
|||
**Note**: Even if login cookies are sent back to your client, they will not be considered for authentication.
|
||||
|
||||
## Response Format
|
||||
The status codes are not always provided by the News app itself, but might also be returned because of ownCloud internal errors.
|
||||
The status codes are not always provided by the News app itself, but might also be returned because of Nextcloud internal errors.
|
||||
|
||||
The following status codes can always be returned by ownCloud:
|
||||
* **401**: The provided credentials to log into ownCloud are invalid.
|
||||
The following status codes can always be returned by Nextcloud:
|
||||
|
||||
* **401**: The provided credentials to log into Nextcloud are invalid.
|
||||
* **403**: The user is not allowed to access the route. This can happen if for instance of only users in the admin group can access the route and the user is not in it.
|
||||
* **404**: The route can not be found or the resource does not exist. Can also happen if for instance you are trying to delete a folder which does not exist.
|
||||
* **5xx**: An internal server error occurred. This can happen if the server is in maintenance mode or because of other reasons.
|
||||
|
||||
The following status codes are returned by News:
|
||||
|
||||
* **200**: Everything went fine
|
||||
* **304**: In case the resource was not modified, contains no response body. This means that you can ignore the request since everything is up to date.
|
||||
* **400**: There was an app related error, check the **error** object if specified
|
||||
* **409**: Conflict error which means that the resource exists already. Can be returned when updating (**PATCH**) or creating (**POST**) a resource, e.g. a folder
|
||||
|
||||
The response headers are:
|
||||
|
||||
* **Content-Type**: application/json; charset=utf-8
|
||||
* **Etag**: A string containing a cache header of maximum length 64, e.g. 6d82cbb050ddc7fa9cbb659014546e59. The etag value will be assembled using the number of feeds, folders and the highest last modified timestamp in milliseconds, e.g. 2-3-123131923912392391239. However consider that a detail and dont rely on it.
|
||||
|
||||
|
|
@ -159,6 +168,7 @@ In case of an **4xx** or **5xx** error the request was not successful and has to
|
|||
|
||||
## Security Guidelines
|
||||
Read the following notes carefully to prevent being subject to security exploits:
|
||||
|
||||
* You should always enforce SSL certificate verification and never offer a way to turn it off. Certificate verification is important to prevent MITM attacks which is especially important in the mobile world where users are almost always connected to untrusted networks. In case a user runs a self-signed certificate on his server ask him to either install his certificate on his device or direct him to one of the many ways to sign his certificate for free (most notably letsencrypt.com)
|
||||
* All string fields in a JSON response **expect an item's body** are **not sanitized**. This means that if you do not escape it properly before rendering you will be vulnerable to [XSS](https://www.owasp.org/index.php/Cross-site_Scripting_%28XSS%29) attacks
|
||||
* Basic Auth headers can easily be decrypted by anyone since base64 is an encoding, not an encryption. Therefore only send them if you are accessing an HTTPS website or display an easy to understand warning if the user chooses HTTP
|
||||
|
|
@ -166,14 +176,15 @@ Read the following notes carefully to prevent being subject to security exploits
|
|||
* If you are building a client in JavaScript or are using a link with **target="blank"**, remember to set the **window.opener** property to **null** and/or add a **rel="noreferrer"** to your link to prevent your app from being [target by an XSS attack](https://medium.com/@jitbit/target-blank-the-most-underestimated-vulnerability-ever-96e328301f4c#.wf2ddytbh)
|
||||
|
||||
## Syncing
|
||||
All routes are given relative to the base API url, e.g.: **/sync** becomes **https://yourowncloud.com/index.php/apps/news/api/v2/sync**
|
||||
All routes are given relative to the base API url, e.g.: **/sync** becomes **https://yourNextcloud.com/index.php/apps/news/api/v2/sync**
|
||||
|
||||
There are two usecases for syncing:
|
||||
|
||||
* **Initial sync**: the user does not have any data at all
|
||||
* **Syncing local and remote changes**: the user has synced at least once and wants to submit and receive changes
|
||||
|
||||
### Initial Sync
|
||||
The intial sync happens when a user adds an ownCloud account in your app. In that case you want to download all folders, feeds and unread/starred items. To do this, make the following request:
|
||||
The intial sync happens when a user adds an Nextcloud account in your app. In that case you want to download all folders, feeds and unread/starred items. To do this, make the following request:
|
||||
|
||||
* **Method**: GET
|
||||
* **Route**: /sync
|
||||
|
|
@ -182,9 +193,11 @@ The intial sync happens when a user adds an ownCloud account in your app. In tha
|
|||
* **Accept: "application/json"**
|
||||
|
||||
This will return the following status codes:
|
||||
|
||||
* **200**: Success
|
||||
|
||||
and the following HTTP headers:
|
||||
|
||||
* **Content-Type**: application/json; charset=utf-8
|
||||
* **Etag**: A string containing a cache header, maximum size 64 ASCII characters, e.g. 6d82cbb050ddc7fa9cbb659014546e59
|
||||
|
||||
|
|
@ -198,6 +211,7 @@ and the following request body:
|
|||
```
|
||||
|
||||
**Note**: Each object is explained in more detail in a separate section:
|
||||
|
||||
* [Folders](#folders)
|
||||
* [Feeds](#feeds)
|
||||
* [Items](#items)
|
||||
|
|
@ -247,6 +261,7 @@ If no items have been read or starred, simply leave the **items** array empty, e
|
|||
```
|
||||
|
||||
The response matches the **GET** call, except there can be two different types of item objects:
|
||||
|
||||
* **[Full](#full)**: Contains all attributes
|
||||
* **[Reduced](#reduced)**: Contains only **id**, **isUnread** and **isStarred**
|
||||
|
||||
|
|
@ -308,11 +323,13 @@ Folders are represented using the following data structure:
|
|||
```
|
||||
|
||||
The attributes mean the following:
|
||||
|
||||
* **id**: 64bit Integer, id
|
||||
* **name**: Abitrary long text, folder's name
|
||||
|
||||
### Deleting A Folder
|
||||
To delete a folder, use the following request:
|
||||
|
||||
* **Method**: DELETE
|
||||
* **Route**: /folders/{id}
|
||||
* **Route Parameters**:
|
||||
|
|
@ -322,6 +339,7 @@ To delete a folder, use the following request:
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Folder was deleted successfully
|
||||
* **404**: Folder does not exist
|
||||
|
||||
|
|
@ -339,6 +357,7 @@ In case of an HTTP 200, the deleted folder is returned in full in the response,
|
|||
|
||||
### Creating A Folder
|
||||
To create a folder, use the following request:
|
||||
|
||||
* **Method**: POST
|
||||
* **Route**: /folders
|
||||
* **Authentication**: [required](#authentication)
|
||||
|
|
@ -353,6 +372,7 @@ with the following request body:
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Folder was created successfully
|
||||
* **400**: Folder creation error, check the error object:
|
||||
* **code**: 1: folder name is empty
|
||||
|
|
@ -367,9 +387,11 @@ In case of an HTTP 200, the created or already existing folder is returned in fu
|
|||
|
||||
### Changing A Folder
|
||||
The following attributes can be changed on the folder:
|
||||
|
||||
* **name**
|
||||
|
||||
To change any number of attributes on a folder, use the following request and provide as much attributes that can be changed as you want:
|
||||
|
||||
* **Method**: PATCH
|
||||
* **Route**: /folders/{id}
|
||||
* **Route Parameters**:
|
||||
|
|
@ -388,10 +410,11 @@ with the following request body:
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Folder was updated successfully
|
||||
* **400**: Folder update error, check the error object:
|
||||
* **code**: 1: folder name is empty
|
||||
* Other ownCloud errors, see [Response Format](#response-format)
|
||||
* Other Nextcloud errors, see [Response Format](#response-format)
|
||||
|
||||
In case of an HTTP 200, the changed or already existing folder is returned in full in the response, e.g.:
|
||||
|
||||
|
|
@ -423,6 +446,7 @@ Feeds are represented using the following data structure:
|
|||
```
|
||||
|
||||
The attributes mean the following:
|
||||
|
||||
* **id**: 64bit Integer, id
|
||||
* **name**: Abitrary long text, feed's name
|
||||
* **faviconLink**: Abitrary long text, feed's favicon location, **null** if not found
|
||||
|
|
@ -443,6 +467,7 @@ The attributes mean the following:
|
|||
|
||||
### Deleting A Feed
|
||||
To delete a feed, use the following request:
|
||||
|
||||
* **Method**: DELETE
|
||||
* **Route**: /feeds/{id}
|
||||
* **Route Parameters**:
|
||||
|
|
@ -453,9 +478,10 @@ To delete a feed, use the following request:
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Feed was deleted successfully
|
||||
* **404**: Feed with given id was not found, no error object
|
||||
* Other ownCloud errors, see [Response Format](#response-format)
|
||||
* Other Nextcloud errors, see [Response Format](#response-format)
|
||||
|
||||
|
||||
In case of an HTTP 200, the deleted feed is returned in full in the response, e.g.:
|
||||
|
|
@ -472,6 +498,7 @@ In case of an HTTP 200, the deleted feed is returned in full in the response, e.
|
|||
|
||||
### Creating A feed
|
||||
To create a feed, use the following request:
|
||||
|
||||
* **Method**: POST
|
||||
* **Route**: /feeds
|
||||
* **Authentication**: [required](#authentication)
|
||||
|
|
@ -490,6 +517,7 @@ with the following request body:
|
|||
"basicAuthPassword": "password"
|
||||
}
|
||||
```
|
||||
|
||||
* **url**: Abitrary long text, the url needs to have the full schema e.g. https://the-url.com. In case the user omits the schema, prepending **https** is recommended
|
||||
* **folderId**: 64bit Integer, the feed's folder or **0** in case no folder is specified
|
||||
* **name (optional)**: Abitrary long text, the feeds name or if not given taken from the RSS/Atom feed
|
||||
|
|
@ -503,6 +531,7 @@ with the following request body:
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Feed was created successfully
|
||||
* **400**: Feed creation error, check the **error** object:
|
||||
* **code**: 1: url is empty
|
||||
|
|
@ -529,6 +558,7 @@ In case of an HTTP 200, the created feed is returned in full in the response, e.
|
|||
|
||||
### Changing A Feed
|
||||
To change a feed, use the following request:
|
||||
|
||||
* **Method**: PATCH
|
||||
* **Route**: /feeds/{id}
|
||||
* **Route Parameters**:
|
||||
|
|
@ -564,6 +594,7 @@ All parameters are optional
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Feed was changed successfully
|
||||
* **400**: Feed creation error, check the error object:
|
||||
* **code**: 1: url is empty
|
||||
|
|
@ -577,7 +608,7 @@ Status codes:
|
|||
* **code**: 9: request timed out
|
||||
* **code**: 10: invalid or missing http basic auth headers
|
||||
* **code**: 11: not allowed to access the feed (difference here is that the user can be authenticated but not allowed to access the feed)
|
||||
* Other ownCloud errors, see [Response Format](#response-format)
|
||||
* Other Nextcloud errors, see [Response Format](#response-format)
|
||||
|
||||
In case of an HTTP 200, the changed feed is returned in full in the response, e.g.:
|
||||
|
||||
|
|
@ -597,6 +628,7 @@ Items can occur in two different formats:
|
|||
* Reduced
|
||||
|
||||
The attributes mean the following:
|
||||
|
||||
* **id**: 64bit Integer, id
|
||||
* **url**: Abitrary long text, location of the online resource
|
||||
* **title**: Abitrary long text, item's title
|
||||
|
|
@ -649,7 +681,7 @@ A reduced item only contains the item status:
|
|||
```
|
||||
|
||||
## Updater
|
||||
Instead of using the built in, slow cron updater you can use the parallel update API to update feeds. The API can be accessed through REST or ownCloud console API.
|
||||
Instead of using the built in, slow cron updater you can use the parallel update API to update feeds. The API can be accessed through REST or Nextcloud console API.
|
||||
|
||||
The API should be used in the following way:
|
||||
|
||||
|
|
@ -658,17 +690,17 @@ The API should be used in the following way:
|
|||
* For each feed and user id, run the update
|
||||
* Clean up after the update
|
||||
|
||||
The reference [implementation in Python](https://github.com/owncloud/news-updater) should give you a good idea how to design your own updater.
|
||||
The reference [implementation in Python](https://github.com/nextcloud/news-updater) should give you a good idea how to design your own updater.
|
||||
|
||||
If the REST API is used, Authorization is required via Basic Auth and the user needs to be in the admin group.
|
||||
If the ownCloud console API is used, no authorization is required.
|
||||
If the Nextcloud console API is used, no authorization is required.
|
||||
|
||||
### Clean Up Before Update
|
||||
This is used to clean up the database. It deletes folders and feeds that are marked for deletion.
|
||||
|
||||
**Console API**:
|
||||
|
||||
php -f /path/to/owncloud/occ news:updater:before-update
|
||||
php -f /path/to/nextcloud/occ news:updater:before-update
|
||||
|
||||
**REST API**:
|
||||
|
||||
|
|
@ -681,7 +713,7 @@ This call returns pairs of feed ids and user ids.
|
|||
|
||||
**Console API**:
|
||||
|
||||
php -f /path/to/owncloud/occ news:updater:all-feeds
|
||||
php -f /path/to/nextcloud/occ news:updater:all-feeds
|
||||
|
||||
**REST API**:
|
||||
|
||||
|
|
@ -705,12 +737,13 @@ Both APIs will return the following response body or terminal output:
|
|||
After all feed ids and user ids are known, feeds can be updated in parallel.
|
||||
|
||||
**Console API**:
|
||||
|
||||
* **Positional Parameters**:
|
||||
* **{feedId}**: the feed's id
|
||||
* **{userId}**: the user's id
|
||||
|
||||
|
||||
php -f /path/to/owncloud/occ news:updater:update-feed {feedId} {userId}
|
||||
php -f /path/to/nextcloud/occ news:updater:update-feed {feedId} {userId}
|
||||
|
||||
**REST API**:
|
||||
|
||||
|
|
@ -727,7 +760,7 @@ This is used to clean up the database. It removes old read articles which are no
|
|||
|
||||
**Console API**:
|
||||
|
||||
php -f /path/to/owncloud/occ news:updater:after-update
|
||||
php -f /path/to/nextcloud/occ news:updater:after-update
|
||||
|
||||
**REST API**:
|
||||
|
||||
|
|
@ -746,6 +779,7 @@ The retrieve meta data about the app, use the following request:
|
|||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Meta data accessed successfully
|
||||
|
||||
In case of an HTTP 200, the the following response is returned:
|
||||
|
|
@ -768,6 +802,7 @@ In case of an HTTP 200, the the following response is returned:
|
|||
```
|
||||
|
||||
The attributes mean the following:
|
||||
|
||||
* **version**: Abitrary long text, News app version
|
||||
* **issues**: An object containing a dictionary of issues which need to be displayed to the user:
|
||||
* **improperlyConfiguredCron**: Boolean, if true this means that no feed updates are run on the server because the updater is misconfigured
|
||||
|
|
@ -783,12 +818,13 @@ The attributes mean the following:
|
|||
To find out which API levels are supported, make a request to the following route:
|
||||
|
||||
* **Method**: GET
|
||||
* **Route**: https://yourowncloud.com/index.php/apps/news/api
|
||||
* **Route**: https://yournextcloud.com/index.php/apps/news/api
|
||||
* **Authentication**: none
|
||||
|
||||
The following response is being returned:
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: The supported API levels can be parsed from the response
|
||||
* **404**: The user is either running a version prior to **8.8.0** or the News app is disabled or not installed.
|
||||
|
||||
|
|
@ -804,10 +840,11 @@ In case of an HTTP 200, the supported API levels are returned as JSON, e.g.:
|
|||
To find out if a user is running an older News version than **8.8.0**, make a request to the following route:
|
||||
|
||||
* **Method**: GET
|
||||
* **Route**: https://yourowncloud.com/index.php/apps/news/api/v1-2/version
|
||||
* **Route**: https://yournextcloud.com/index.php/apps/news/api/v1-2/version
|
||||
* **Authentication**: [required](#authentication)
|
||||
|
||||
Status codes:
|
||||
|
||||
* **200**: Only the v1-2 API level is supported
|
||||
* **404**: The News app is disabled or not installed.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 678 B |
|
|
@ -0,0 +1,31 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
id="svg4551"
|
||||
viewBox="0 0 32 32"
|
||||
x="0px"
|
||||
y="0px"
|
||||
enable-background="new 0 0 595.275 311.111"
|
||||
width="32"
|
||||
height="32"
|
||||
xml:space="preserve"
|
||||
version="1.1"><metadata
|
||||
id="metadata4557"><rdf:RDF><cc:Work
|
||||
rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs
|
||||
id="defs4555" /><rect
|
||||
id="rect4547"
|
||||
fill="#0082c9"
|
||||
x="0"
|
||||
y="-.0000052588"
|
||||
width="32"
|
||||
height="32"
|
||||
ry="5"
|
||||
rx="5" /><path
|
||||
style="fill:#ffffff;stroke-width:0.92142856"
|
||||
d="m 3.7714273,3.1652662 c -0.5104715,0 -0.9214286,0.4109573 -0.9214286,0.9214286 v 1.842857 c 0,0.5104714 0.4109571,0.9214286 0.9214286,0.9214286 H 27.72857 c 0.510471,0 0.921428,-0.4109572 0.921428,-0.9214286 v -1.842857 c 0,-0.5104713 -0.410957,-0.9214286 -0.921428,-0.9214286 z m 0,7.3714278 c -0.5104715,0 -0.9214286,0.410958 -0.9214286,0.921429 v 1.842857 c 0,0.510472 0.4109571,0.921429 0.9214286,0.921429 H 20.357141 c 0.510471,0 0.921429,-0.410957 0.921429,-0.921429 v -1.842857 c 0,-0.510471 -0.410958,-0.921429 -0.921429,-0.921429 z m 0,7.371429 c -0.5104715,0 -0.9214286,0.410957 -0.9214286,0.921428 v 1.842858 c 0,0.510471 0.4109571,0.921429 0.9214286,0.921429 H 25.885712 c 0.510472,0 0.921429,-0.410958 0.921429,-0.921429 v -1.842858 c 0,-0.510471 -0.410957,-0.921428 -0.921429,-0.921428 z m 0,7.371429 c -0.5104715,0 -0.9214286,0.410958 -0.9214286,0.921429 v 1.842857 c 0,0.510472 0.4109571,0.921429 0.9214286,0.921429 H 14.82857 c 0.510472,0 0.921429,-0.410957 0.921429,-0.921429 v -1.842857 c 0,-0.510471 -0.410957,-0.921429 -0.921429,-0.921429 z"
|
||||
id="path4725" /></svg>
|
||||
|
After Width: | Height: | Size: 2.0 KiB |
|
|
@ -0,0 +1,31 @@
|
|||
# Clients
|
||||
|
||||
Clients are applications that use the REST API of News. They are not maintained by the News team.
|
||||
If you are the developer of an app, feel free to create a PR to add your app to this list.
|
||||
|
||||
## Sync Clients
|
||||
|
||||
A sync client can be used to read news and synchronize via the API.
|
||||
|
||||
| Name | OS/Platform | License | Source |
|
||||
|------------------------------------------------------------------------------------------------------------------|------------------------------|----------------------|--------------------------------------------------------------------|
|
||||
| [RSS Guard](https://github.com/martinrotter/rssguard) | Windows, Linux, OS/2, Mac OS | GPL-3.0 License | [GitHub](https://github.com/martinrotter/rssguard) |
|
||||
| [Nextcloud News Reader](https://play.google.com/store/apps/details?id=de.luhmer.owncloudnewsreader) | Android | GPL-3.0 License | [GitHub](https://github.com/nextcloud/news-android-app) |
|
||||
| [OCReader](https://f-droid.org/repository/browse/?fdid=email.schaal.ocreader) | Android | GPL-3.0 License | [GitHub](https://github.com/schaal/ocreader) |
|
||||
| [Newsout](https://play.google.com/store/apps/details?id=com.inspiredandroid.newsout) | Android | Apache-2.0 License | [GitHub](https://github.com/SimonSchubert/NewsOut) |
|
||||
| [Readrops](https://f-droid.org/en/packages/com.readrops.app/) | Android | GPL-3.0 License | [GitHub](https://github.com/readrops/Readrops) |
|
||||
| [CloudNews](https://apps.apple.com/app/cloudnews-owncloud-news-reader/id683859706) | iOS | BSD-2-Clause License | [GitHub](https://github.com/owncloud/news-ios-app) |
|
||||
| [Fiery Feeds](https://apps.apple.com/us/app/fiery-feeds-rss-reader/id1158763303) | iOS | - | - |
|
||||
| [News Checker](https://chrome.google.com/webstore/detail/owncloud-news-checker/hnmagnmdnfdhabdlicankfbfhcdgbfhe) | Google Chrome | - | [GitHub](https://github.com/owncloud-archive/news-chrome-notifier) |
|
||||
| [own News](https://appworld.blackberry.com/webstore/content/32767887/) | Blackberry | - | - |
|
||||
| [FeedSpider](https://www.feedspider.net/) | Firefox OS, webOS, LuneOS | MIT License | [GitHub](https://github.com/OthelloVentures/feedspider) |
|
||||
| [fastReader](https://www.windowsphone.com/en-us/store/app/fastreader/e55e696d-aa45-4a49-bb1c-a1fc7fdabec1) | Windows Phone | - | - |
|
||||
| [py3status](https://github.com/ultrabug/py3status/) | i3wm | BSD-3-Clause License | [GitHub](https://github.com/ultrabug/py3status/) |
|
||||
| [newsboat](https://newsboat.org/) | Unix Terminal | MIT License | [GitHub](https://github.com/newsboat/newsboat) |
|
||||
| [Newsie](https://open-store.io/app/newsie.martinferretti) | Ubuntu Touch | GPL-3.0 License | [GitLab](https://gitlab.com/ferrettim/newsie) |
|
||||
|
||||
## Update Clients
|
||||
|
||||
An update client uses the News API or the OCC CLI to update the feeds in News.
|
||||
|
||||
* [Python multithread updater](https://github.com/nextcloud/news-updater)
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
# Explore Feeds Section
|
||||
|
||||
The News app uses a JSON format to display the feeds in the explore feed section.
|
||||
|
||||
The feeds are stored in a JSON file in the [explore](https://github.com/nextcloud/news/tree/master/lib/Explore/feeds) folder and are localized based on their filename, meaning: feeds.en.json will only be shown for English localized Nextcloud installations, feeds.de.json only for German installations. If no other localization exists, the feeds.en.json will be taken.
|
||||
|
||||
You can also provide your own explore service.
|
||||
|
||||
## Format
|
||||
|
||||
The file has the following format:
|
||||
```js
|
||||
{
|
||||
"Nextcloud": [{ // category
|
||||
"title": "Nextcloud Planet",
|
||||
"favicon": "https://nextcloud.com/contribook/main/images/nextcloud/100.png",
|
||||
"url": "https://nextcloud.com/news/",
|
||||
"feed": "https://nextcloud.com/feed/",
|
||||
"description": "Nextcloud Planet is a blog feed aggregator",
|
||||
"votes": 1000
|
||||
}],
|
||||
}
|
||||
```
|
||||
|
||||
To ease the pain of constructing the JSON object, you can use a nextcloud command to automatically create it:
|
||||
|
||||
php ./occ news:generate-explore https://path.com/to/feed.rss
|
||||
|
||||
By passing a second parameter you can set the vote count which determines the sorting on the explore page:
|
||||
|
||||
php ./occ news:generate-explore https://path.com/to/feed.rss 1000
|
||||
|
||||
You can paste the output directly into the appropriate json file but you may need to add additional categories and commas
|
||||
|
||||
## Using A Webservice Instead of JSON Files
|
||||
|
||||
If you are using the News app in your company/community it might be interesting to offer your users a bunch of easily to discover default feeds. You could also create a website where people can add and up-vote news feeds like bigger cloud feed readers like Feedly do it or even convert their APIs into a service for the News app (if someone wants to provide one for the News app, feel free to contact us by creating an issue in the bug tracker).
|
||||
|
||||
The URL should be a path to a directory which contains a JSON file in the format of **feeds.LANG_CODE.json** where LANG_CODE is a two character language code (e.g. **en** or **de**).
|
||||
|
||||
For example entering the URL **https://domain.com/directory** as explore URL will produce the following request for German users:
|
||||
|
||||
GET https://domain.com/directory/feeds.de.json
|
||||
|
||||
|
||||
**Do not forget to implement [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) in your API, otherwise the request will fail!**
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
## FAQ
|
||||
# FAQ
|
||||
|
||||
### My browser shows a mixed content warning (Connection is Not Secure)
|
||||
## My browser shows a mixed content warning (Connection is Not Secure)
|
||||
If you are serving your Nextcloud over HTTPS your browser will very likely warn you with a yellow warnings sign about your connection not being secure.
|
||||
|
||||
Chrome will show no green HTTPS lock sign, Firefox will show you the following image
|
||||
|
|
@ -8,24 +8,25 @@ Chrome will show no green HTTPS lock sign, Firefox will show you the following i
|
|||
|
||||
Note that this warning **is not red and won't block the page like the following images** which signal **a serious issue**:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### What is the cause of the (yellow) error message
|
||||
### What is the cause of the (yellow) error message
|
||||
|
||||
This warning is caused by [mixed passive content](https://developer.mozilla.org/en/docs/Security/MixedContent) and means that your page loads passive resources from non HTTPS resources, such as:
|
||||
|
||||
* Images
|
||||
* Video/Audio
|
||||
|
||||
This allows a possible attacker to perform a MITM (man-in-the-middle) attack by serving you different images or audio/video.
|
||||
|
||||
#### Why doesn't the News app fix it
|
||||
### Why doesn't the News app fix it
|
||||
|
||||
The News app fully prevents mixed **active** content by only allowing HTTPS iframes from known locations; other possible mixed active content elements such as \<script> are stripped from the feed. Because images and audio/video are an integral part of a feed, we can not simply strip them.
|
||||
The News app fully prevents mixed **active** content by only allowing HTTPS iframes from known locations; other possible mixed active content elements such as <script\> are stripped from the feed. Because images and audio/video are an integral part of a feed, we can not simply strip them.
|
||||
|
||||
Since an attacker can not execute code in contrast to mixed active content, but only replace images/audio/video in your feed reader, this is **not considered to be a security issue**. If, for whatever reason (e.g. feed which would allow fishing), this is a security problem for you, contact the specific feed provider and ask him to serve his feed content over HTTPS.
|
||||
|
||||
#### Why don't you simply use an HTTPS image/audio/video proxy
|
||||
### Why don't you simply use an HTTPS image/audio/video proxy
|
||||
|
||||
For the same reason that we can't fix non HTTPS websites: It does not fix the underlying issue but only silences it. If you are using an image HTTPS proxy, an attacker can simply attack your image proxy since the proxy fetches insecure content. **Even worse**: if your image proxy serves these images from the same domain as your Nextcloud installation you [are vulnerable to XSS via SVG images](https://www.owasp.org/images/0/03/Mario_Heiderich_OWASP_Sweden_The_image_that_called_me.pdf). In addition, people feel safe when essentially they are not.
|
||||
|
||||
|
|
@ -35,19 +36,20 @@ Because we care about our users' security and don't want to hide security warnin
|
|||
|
||||
The only fix for this issue is that feed providers serve their content over HTTPS.
|
||||
|
||||
### I am getting: Exception: Some\\Class does not exist erros in my nextcloud.log
|
||||
This is very often caused by missing or old files, e.g. by failing to upload all of the News app' files or errors during installation. Before you report a bug, please recheck if all files from the archive are in place and accessible.
|
||||
## I am getting: Exception: Some\\Class does not exist errors in my nextcloud.log
|
||||
This is very often caused by missing or old files, e.g. by failing to upload all the News app files or errors during installation. Before you report a bug, please recheck if all files from the archive are in place and accessible.
|
||||
|
||||
### Feeds not updated
|
||||
Feeds can be updated using Nextcloud's system cron or any program that implements the [News app's updater API](https://github.com/nextcloud/news/tree/master/docs/externalapi), most notably [Nextcloud News Updater](https://github.com/nextcloud/news-updater). **The feed update is not run in Webcron and AJAX cron mode!**
|
||||
## Feeds not updated
|
||||
Feeds can be updated using Nextcloud's system cron or an [external updater](https://nextcloud.github.io/news/clients/#update-clients) via the API
|
||||
**The feed update is not run in Webcron and AJAX cron mode!**
|
||||
|
||||
System Cron:
|
||||
### System Cron
|
||||
* Check if you are using the system cron (Cron) setting on the admin page. AJAX and Web cron will not update feeds
|
||||
* Check if the cronjob exists with **crontab -u www-data -e** (replace www-data with your httpd user)
|
||||
* Check the file permissions of the **cron.php** file and if **www-data** (or whatever your httpd user is called like) can read and execute that script
|
||||
* Check if you can execute the cron with **sudo -u www-data php -f nextcloud/cron.php** (replace www-data with your httpd user)
|
||||
* Check your **data/nextcloud.log** for errors
|
||||
* Check if the cronjob is ever executed by placing an **error_log('updating');** in the [background job file](https://github.com/nextcloud/news/blob/master/lib/Cron/Updater.php#L28). If the cronjob runs, there should be an updating log statement in your httpd log.
|
||||
* Check if the cronjob is ever executed by placing an **error_log('updating');** in the [background job file](https://github.com/nextcloud/news/blob/master/lib/Service/UpdaterService.php#L55). If the cronjob runs, there should be an updating log statement in your httpd log.
|
||||
* If there is no **updating** statement in your logs check if your cronjob is executed by executing a different script
|
||||
* Check if the **oc_jobs** table has a **reserved_at** entry with a value other than 0. If it does for whatever reason, set it to 0. You can check this by executing:
|
||||
|
||||
|
|
@ -62,33 +64,32 @@ You will get two rows where column `class`will be `OCA\News\Cron\Updater` and `O
|
|||
```sql
|
||||
UPDATE oc_jobs SET reserved_at = 0 WHERE id = <id from above SELECT statement>;
|
||||
```
|
||||
|
||||
* If your cron works fine but Nextcloud's cronjobs are never executed, file a bug in [server](https://github.com/nextcloud/server/)
|
||||
|
||||
[Nextcloud News Updater](https://github.com/nextcloud/news-updater):
|
||||
* If your cron works fine, but Nextcloud's cronjobs are never executed, file a bug in [server](https://github.com/nextcloud/server/)
|
||||
|
||||
### External Updater
|
||||
* Check if your configuration is set to **not** use the system cron.
|
||||
* Start the updater in loglevel info mode and check if the feed update urls are polled, e.g.:
|
||||
|
||||
nextcloud_news_updater --loglevel info -c /path/to/config.ini
|
||||
|
||||
* Consult the documentation of the updater
|
||||
* Check your **data/nextcloud.log** for errors
|
||||
|
||||
### Adding feeds that use self-signed certificates
|
||||
If you want to add a feed that uses a self-signed certificate that is not signed by a trusted CA the request will fail with "SSL certficate is invalid". A common solution is to turn off the certificate verification **which is wrong** and **makes your installation vulnerable to MITM attacks**. Therefore **turning off certificate verification is not supported**.
|
||||
## Adding feeds that use self-signed certificates
|
||||
If you want to add a feed that uses a self-signed certificate that is not signed by a trusted CA the request will fail with "SSL certificate is invalid". A common solution is to turn off the certificate verification **which is wrong** and **makes your installation vulnerable to MITM attacks**. Therefore **turning off certificate verification is not supported**.
|
||||
|
||||
|
||||
If you have control over the feed in question, consider signing your certificate for free on one of the following providers:
|
||||
* [letsencrypt.com](http://letsencrypt.com/)
|
||||
|
||||
If you do not have control over the chosen feed, you should [download the certificate from the feed's website](http://superuser.com/questions/97201/how-to-save-a-remote-server-ssl-certificate-locally-as-a-file) and [add it to your server's trusted certificates](http://www.onlinesmartketer.com/2009/06/23/curl-adding-installing-trusting-new-self-signed-certificate/). The exact procedure however may vary depending on your distribution.
|
||||
* [Let's Encrypt](https://letsencrypt.org/)
|
||||
* [ZeroSSL](https://zerossl.com/)
|
||||
|
||||
### Is There An Subscription URL To Easily Subscribe To Feeds
|
||||
If you do not have control over the chosen feed, you should [download the certificate from the feed's website](https://superuser.com/questions/97201/how-to-save-a-remote-server-ssl-certificate-locally-as-a-file) and [add it to your server's trusted certificates](https://www.onlinesmartketer.com/2009/06/23/curl-adding-installing-trusting-new-self-signed-certificate/). The exact procedure however may vary depending on your distribution.
|
||||
|
||||
## Is There An Subscription URL To Easily Subscribe To Feeds
|
||||
|
||||
By appending **?subscribe_to=SOME_URL** to your News app URL, you can launch the News app with a pre-filled URL, e.g.:
|
||||
|
||||
https://yourdomain.com/nextcloud/index.php/apps/news?subscribe_to=https://github.com/nextcloud/news/releases
|
||||
|
||||
### Database table grows too big
|
||||
## Database table grows too big
|
||||
|
||||
By default, Nextcloud News purges old news items above a certain threshold each time it fetches new news items. The maximum number of items per feed
|
||||
that should be kept during the purging can be defined through the “Maximum read count per feed” setting in the admin UI or the `autoPurgeCount`
|
||||
|
|
@ -99,7 +100,7 @@ unread, this can lead to an oversized news table over time. As a consequence, th
|
|||
Nextcloud cannot be used.
|
||||
|
||||
The command `occ news:updater:after-update [--purge-unread] [<purge-count>]` can be used to manually purge old news items across the instance. With
|
||||
the `--purge-unread` option, unread items are also purged (starred items are still exempt). If `purge-count` is not specifid, the configured
|
||||
the `--purge-unread` option, unread items are also purged (starred items are still exempt). If `purge-count` is not specified, the configured
|
||||
`autoPurgeCount` is used.
|
||||
|
||||
The purge count only applies to the items that are purged. For example, when purging a feed that has 100 unread items, 100 starred read
|
||||
|
|
@ -1,27 +1,28 @@
|
|||
# How To Write Plugins
|
||||
# Plugins
|
||||
|
||||
Plugins were created to keep the app maintainable while still making it possible to easily implement additional functionality.
|
||||
|
||||
There are essentially three different use cases for plugins:
|
||||
|
||||
* Creating or extending server-side functionality, e.g. creating additional REST API endpoints
|
||||
* Offering article actions such as share via Twitter or E-Mail
|
||||
* Dropping in additional CSS or JavaScript
|
||||
|
||||
## The Basics
|
||||
Whatever plugin you want to create, you first need to create a basic structure. A plugin is basically just an app so you can take advantage of the full [Nextcloud app API](https://docs.nextcloud.org/server/latest/developer_manual/app/index.html). If you want you can [take a look at the developer docs](https://docs.nextcloud.org/server/latest/developer_manual/app/index.html) or [dig into the tutorial](https://docs.nextcloud.org/server/latest/developer_manual/app/tutorial.html).
|
||||
Whatever plugin you want to create, you first need to create a basic structure. A plugin is basically just an app, so you can take advantage of the full [Nextcloud app API](https://docs.nextcloud.org/server/latest/developer_manual/app/index.html). If you want you can [take a look at the developer docs](https://docs.nextcloud.org/server/latest/developer_manual/app/index.html) or [dig into the tutorial](https://docs.nextcloud.org/server/latest/developer_manual/app/tutorial.html).
|
||||
|
||||
However if you just want to start slow, the full process is described below.
|
||||
However, if you just want to start slow, the full process is described below.
|
||||
|
||||
First create the following directories and files:
|
||||
|
||||
* **newsplugin/**
|
||||
* **appinfo/**
|
||||
* **app.php**
|
||||
* **info.xml**
|
||||
* **appinfo/**
|
||||
* **app.php**
|
||||
* **info.xml**
|
||||
|
||||
The first folder name affects the name and namespace of your plugin and only one app can exist using the same name. Choose wisely.
|
||||
|
||||
First let's add some meta data about our app. Open the **newsplugin/appinfo/info.xml** and add the following contents:
|
||||
First let's add some meta ata about our app. Open the **newsplugin/appinfo/info.xml** and add the following contents:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0"?>
|
||||
|
|
@ -40,7 +41,7 @@ First let's add some meta data about our app. Open the **newsplugin/appinfo/info
|
|||
</info>
|
||||
```
|
||||
|
||||
**Note**: You must license your app under the [AGPL 3 or later](http://www.gnu.org/licenses/agpl-3.0.en.html) to comply with the News app's license. Don't forget to add the license as plain text file if you want to distribute your app!
|
||||
**Note**: You must license your app under the [AGPL 3 or later](https://www.gnu.org/licenses/agpl-3.0.en.html) to comply with the News app's license. Don't forget to add the license as plain text file if you want to distribute your app!
|
||||
|
||||
Then we want to make sure that our code is only run if the News app is enabled. To do that put the following PHP code into the **newsplugin/appinfo/app.php** file:
|
||||
|
||||
|
|
@ -54,7 +55,7 @@ if (App::isEnabled('news')) {
|
|||
}
|
||||
```
|
||||
|
||||
If your plugin integrates with an other Nextcloud app, make sure to also require it be installed. If you depend on the bookmarks app for instance use:
|
||||
If your plugin integrates with another Nextcloud app, make sure to also require it be installed. If you depend on the Bookmarks app for instance use:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
|
@ -85,13 +86,13 @@ if (App::isEnabled('news') && class_exists('OCA\News\Plugin\Client\Plugin')) {
|
|||
}
|
||||
```
|
||||
|
||||
This will tell the News app to load load the following files after its own JavaScript and CSS files have been included:
|
||||
This will tell the News app to load the following files after its own JavaScript and CSS files have been included:
|
||||
|
||||
* **newsplugin/js/script.js**
|
||||
* **newspluing/css/style.css**
|
||||
|
||||
### Adding Basic JavaScript Functionality
|
||||
You can basically add any JavaScript you want. If you want to add an additional article action, this is a bit more complicated because it's hard to hook into Angular from the outside. Therefore the News app provides an API which makes creating additional article actions a breeze.
|
||||
You can basically add any JavaScript you want. If you want to add a new article action, this is a bit more complicated because it's hard to hook into Angular from the outside. Therefore, the News app provides an API which makes creating additional article actions a breeze.
|
||||
|
||||
A basic article action looks like this:
|
||||
|
||||
|
|
@ -102,19 +103,20 @@ News.addArticleAction(function($actionsElement, article) {
|
|||
```
|
||||
|
||||
The **addArticleAction** method expects a function with the following parameters:
|
||||
|
||||
* **$actionsElement**: The DOM element wrapped in jQuery where your plugin should be appended to
|
||||
* **article**: The current article's data (readonly!). The article object has the following properties:
|
||||
* **id**: the article id in the News database
|
||||
* **url**: the article url it points to
|
||||
* **id**: the article ID in the News database
|
||||
* **url**: the article URL it points to
|
||||
* **title**: the article title
|
||||
* **author**: the article author
|
||||
* **pubDate**: the article published date, a unix timestamp
|
||||
* **body**: the html content
|
||||
* **pubDate**: the article published date, a Unix timestamp
|
||||
* **body**: the HTML content
|
||||
* **enclosureMime**: if an enclosure is added, this is the mime type
|
||||
* **enclosureLink**: this is the source of the enclosure
|
||||
* **mediaThumbnail**: if there is a media attached, this is its thumbnail
|
||||
* **mediaDescription**: if there is a media attached, this is its description
|
||||
* **feedId**: the feed id it belongs to
|
||||
* **feedId**: the feed ID it belongs to
|
||||
* **unread**: if the article is unread (bool)
|
||||
* **starred**: if the article is starred (bool)
|
||||
* **lastModified**: the last modified date
|
||||
|
|
@ -158,13 +160,13 @@ Then open the **newspluing/css/style.css** file and add the following CSS:
|
|||
Reload the News app and click the three dots menu, sit back and enjoy :)
|
||||
|
||||
## Server-Side Plugin
|
||||
A Server-Side plugin is a plugin that uses the same infrastructure as the News app for its own purposes. An example would be a plugin that makes the starred entries of a user available via an interface or a bookmark app that that also shows starred articles as bookmarks.
|
||||
A Server-Side plugin is a plugin that uses the same infrastructure as the News app for its own purposes. An example would be a plugin that makes the starred entries of a user available via an interface or a bookmark app that also shows starred articles as bookmarks.
|
||||
|
||||
It's very easy to interface with the News app. Because all Classes are registered in the **news/app/application.php** it takes almost no effort to use the same infrastructure.
|
||||
|
||||
**Note**: Keep in mind that these classes are essentially private which means they might break if the News app changes. There is no real public API so use at your own risk ;)
|
||||
|
||||
Since you dont want to extend the app but use its resources, its advised that you dont inherit from the **Application** class but rather include it in your own container in **newsplugin/appinfo/application.php**:
|
||||
Since you don't want to extend the app but use its resources, its advised that you don't inherit from the **Application** class but rather include it in your own container in **newsplugin/appinfo/application.php**:
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
|
@ -201,6 +203,8 @@ Using automatic container assembly you can then use it from your code by simply
|
|||
|
||||
### Examples
|
||||
Client-side plugins:
|
||||
|
||||
* [Mail Share](https://github.com/cosenal/mailsharenewsplugin): Client-side plugin to share articles by email
|
||||
Server-side plugins:
|
||||
|
||||
* [Feed Central](https://github.com/Raydiation/feedcentral): Publish your feeds as RSS
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
# Themes
|
||||
Nextcloud News can look different with the following themes:
|
||||
|
||||
* [Nextcloud News Themes](https://github.com/cwmke/nextcloud-news-themes)
|
||||
|
|
@ -0,0 +1,5 @@
|
|||
# Introduction
|
||||
|
||||
Welcome to the Nextcloud News APP documentation, it contains information for users, administrators and developers. News is an APP for Nextcloud that can be installed from the official [APP Store](https://apps.nextcloud.com/apps/news).
|
||||
|
||||
News offers the user an RSS/Atom feed reader and can be used to subscribe to multiple feeds, which get automatically updated in the background. Additionally, news offers a REST-API that allows clients to synchronize with News.
|
||||
|
|
@ -1,10 +1,13 @@
|
|||
# Installation/Update
|
||||
|
||||
## Dependencies
|
||||
* 64bit OS (starting with News 16.0.0)
|
||||
* PHP >= 7.2
|
||||
* Nextcloud 20
|
||||
* libxml >= 2.7.8
|
||||
|
||||
You also need some PHP extensions:
|
||||
|
||||
* json
|
||||
* simplexml
|
||||
* xml
|
||||
|
|
@ -26,18 +29,19 @@ Also see the [Nextcloud documentation](https://docs.nextcloud.com/server/stable/
|
|||
|
||||
## Before you install/update the News app
|
||||
Before you install the app do the following:
|
||||
|
||||
* Check that your **nextcloud/data/** directory is owned by your web server user and that it is write/readable
|
||||
* Check that your installation fulfills the [requirements listed in the README section](https://github.com/nextcloud/news#dependencies)
|
||||
* Check that your installation fulfills the [requirements listed above](#dependencies)
|
||||
* [Set up Nextcloud Background Jobs](https://docs.nextcloud.org/server/latest/admin_manual/configuration_server/background_jobs_configuration.html#cron) to enable feed updates.
|
||||
|
||||
Then proceed to install the app either from an archive (zip/tar.gz) or clone it from the repository using git
|
||||
|
||||
## Installing from the [app store](https://apps.nextcloud.com/apps/news)
|
||||
This is the easiest solution: Simply go the the apps page (section: "Multimedia") and enable the News app
|
||||
This is the easiest solution: Simply go the apps page (section: "Multimedia") and enable the News app
|
||||
|
||||
## Installing from archive
|
||||
* Go to the [Nextcloud News GitHub releases page](https://github.com/nextcloud/news/releases) and download the latest release/archive to your server
|
||||
* Starting with 8.0.0, there are two different releases: **news.tar.gz** and **Source code**. The first one requires no additional steps, the second one requires you to install the dependencies and compile the JavaScript. Choose the first one if you don't want to work on the code. If you want to install a version prior to 8.0.0, choose the **Source code** download.
|
||||
* The news.tar.gz file contains the compiled and signed app files, if you install from source you have to build the app on your own.
|
||||
* On your server, check if there is a folder called **nextcloud/apps/news**. If there is one, delete it.
|
||||
* Extract the downloaded archive to the **nextcloud/apps/** folder.
|
||||
* Remove the version from the extracted folder (e.g. rename **nextcloud/apps/news-4.0.3/** to **nextcloud/apps/news/**
|
||||
|
|
@ -55,6 +59,7 @@ This is the easiest solution: Simply go the the apps page (section: "Multimedia"
|
|||
|
||||
### Build Dependencies
|
||||
These Dependencies are only relevant if you want to build the source code:
|
||||
|
||||
* make
|
||||
* which
|
||||
* Node.js >= 6
|
||||
|
|
@ -78,7 +83,7 @@ These Dependencies are only relevant if you want to build the source code:
|
|||
git checkout tags/TAG
|
||||
make # if News version >= 8.0.0
|
||||
|
||||
For instance to use the 5.2.8 release, run:
|
||||
For instance, to use the 5.2.8 release, run:
|
||||
|
||||
git checkout tags/5.2.8
|
||||
|
||||
|
|
|
|||
|
|
@ -1,24 +1,23 @@
|
|||
# Maintenance documentation
|
||||
# Maintenance
|
||||
|
||||
## Release
|
||||
Releases should be done by checking `make test`, cleaning using `make distclean` and consequently running `make dist`.
|
||||
This will create an app store ready package to be uploaded.
|
||||
This process should be done by someone who has the private keys and the access to sign and upload such a package.
|
||||
Releases are created automatically by GitHub Actions. A release is triggered via a GitHub Release.
|
||||
The GitHub Action will then start a build based on the git tag. A release can only be approved by [@Grotax](https://github.com/Grotax) or [@SMillerDev](https://github.com/SMillerDev). An admin of the Nextcloud organization can always overwrite these settings. The private key is stored as environmental secret in GitHub. The owner of the private key is [@Grotax](https://github.com/Grotax).
|
||||
|
||||
## Support
|
||||
### PHP
|
||||
While the app should try to support all PHP versions that nextcloud currently supports,
|
||||
the real focus when deciding to cut a PHP version should be on maintenance burden.
|
||||
Users are nice but devs should be a priority in decisions that are likely to impact them significantly.
|
||||
While the app should try to support all PHP versions that Nextcloud currently supports,
|
||||
the real focus when deciding to cut a PHP version should be on maintenance burden.
|
||||
Users are nice, but devs should be a priority in decisions that are likely to impact them significantly.
|
||||
|
||||
### Issues
|
||||
- Bug reports without test cases (feed url and action is enough) can be closed with or without comment.
|
||||
- Bug reports without test cases (feed URL and action is enough) can be closed with or without comment.
|
||||
|
||||
- Feature requests without thoughtful commentary or pull request can be closed with or without comment,
|
||||
unless a developer is interested to support such a feature.
|
||||
|
||||
- Issues without activity in the last 30 days can be closed with or without comment.
|
||||
If this is a bug you care about that isn't getting attention, fix it.
|
||||
If this is a bug you care about that isn't getting attention, fix it.
|
||||
If you're good enough to understand the bug, you're good enough to fix it.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
# What is the update interval?
|
||||
The update interval is used to determine when the next update of all feeds should be done.
|
||||
You can configure this interval as an administrator.
|
||||
|
||||
# What is a good update interval?
|
||||
That depends on your individual needs.
|
||||
Please keep in mind that the lower you set your update interval, the more traffic is generated.
|
||||
|
||||
# Can I set individual update intervals per feed/user?
|
||||
No.
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
site_name: Nextcloud News App
|
||||
repo_url: https://github.com/nextcloud/news
|
||||
edit_uri: blob/master/documentation/
|
||||
|
||||
nav:
|
||||
- index.md
|
||||
- install.md
|
||||
- clients.md
|
||||
- admin.md
|
||||
- faq.md
|
||||
- Features:
|
||||
- Custom CSS: features/customCSS.md
|
||||
- Plugins: features/plugins.md
|
||||
- Themes: features/themes.md
|
||||
- REST API:
|
||||
- API v1: api/api-v1.md
|
||||
- API v2: api/api-v2.md
|
||||
- maintenance.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
logo: assets/logo.svg
|
||||
favicon: assets/favicon.png
|
||||
font: false
|
||||
features:
|
||||
- navigation.indexes
|
||||
- navigation.tracking
|
||||
- navigation.instant
|
||||
- navigation.expand
|
||||
- navigation.sections
|
||||
|
||||
|
||||
# extra:
|
||||
# version:
|
||||
# provider: mike
|
||||
|
|
@ -14,8 +14,7 @@ style('news', 'admin');
|
|||
</p>
|
||||
<p>
|
||||
<em><?php p($l->t(
|
||||
'Disable this if you run a custom updater such as the Python ' .
|
||||
'updater included in the app.'
|
||||
'Disable this if you use a custom updater.'
|
||||
)); ?></em>
|
||||
</p>
|
||||
</div>
|
||||
|
|
@ -101,7 +100,7 @@ style('news', 'admin');
|
|||
'input empty.'
|
||||
)); ?>
|
||||
</em>
|
||||
<a href="https://github.com/nextcloud/news/tree/master/docs/explore"><?php p($l->t(
|
||||
<a href="https://nextcloud.github.io/news/features/admin/"><?php p($l->t(
|
||||
'For more information check the wiki.'
|
||||
)); ?></a>
|
||||
</p>
|
||||
|
|
@ -120,8 +119,8 @@ style('news', 'admin');
|
|||
'Interval in seconds in which the feeds will be updated.'
|
||||
)); ?>
|
||||
</em>
|
||||
<a href="https://github.com/nextcloud/news/tree/master/docs/updateInterval"><?php p($l->t(
|
||||
'For more information check the wiki.'
|
||||
<a href="https://nextcloud.github.io/news/features/admin/"><?php p($l->t(
|
||||
'For more information check the documentation.'
|
||||
)); ?></a>
|
||||
</p>
|
||||
<p><input type="text" name="news-update-interval"
|
||||
|
|
|
|||
Loading…
Reference in New Issue