diff options
-rw-r--r-- | README.md | 1 | ||||
-rw-r--r-- | docs/README.md | 13 | ||||
-rw-r--r-- | docs/developer/README.md | 6 | ||||
-rw-r--r-- | docs/developer/articleenhancers/README.md | 27 | ||||
-rw-r--r-- | docs/explore/README.md | 48 | ||||
-rw-r--r-- | docs/externalapi/Legacy.md (renamed from docs/developer/externalapi/Legacy.md) | 0 | ||||
-rw-r--r-- | docs/feedcss/README.md | 16 | ||||
-rw-r--r-- | docs/plugins/README.md (renamed from docs/developer/plugins/README.md) | 0 |
8 files changed, 77 insertions, 34 deletions
@@ -1,6 +1,5 @@ # Nextcloud News app [![irc](https://img.shields.io/badge/irc%20channel-%23nextcloud--news%20on%20freenode-blue.svg)](https://webchat.freenode.net/?channels=nextcloud-news) -[![Join the chat at https://gitter.im/nextcloud/news](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/nextcloud/news?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://travis-ci.org/nextcloud/news.svg?branch=master)](https://travis-ci.org/nextcloud/news) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/nextcloud/news/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/nextcloud/news/?branch=master) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..f3afcb07c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,13 @@ +# Documentation + + +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 [picoFeed](https://github.com/fguillot/picoFeed) for parsing feeds and full text feeds. picoFeed is a fantastic library so if you [add custom full text configurations](https://github.com/fguillot/picoFeed/blob/master/docs/grabber.markdown#how-to-write-a-grabber-rules-file) or fix bugs, please consider **contributing your changes** back to the library to help others :) + diff --git a/docs/developer/README.md b/docs/developer/README.md deleted file mode 100644 index 5144732f9..000000000 --- a/docs/developer/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Developer Documentation -As a developer you can interact with the News app in the following ways: - -* [External API](externalapi/): API specification for syncing and updating feeds -* [Plugins](plugins/): How to write client and server-side plugins -* [Article enhancers](articleenhancers/): Add custom CSS for a feed or add rules for full text feeds
\ No newline at end of file diff --git a/docs/developer/articleenhancers/README.md b/docs/developer/articleenhancers/README.md deleted file mode 100644 index 34060b491..000000000 --- a/docs/developer/articleenhancers/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# Article Enhancers -You can enhance the feed download and rendering process in the following ways: - -* Adding custom full text rules -* Adding custom CSS - -In any case, please consider **contributing your changes back** to either [picoFeed](https://github.com/fguillot/picoFeed) or [News](https://github.com/nextcloud/news/blob/master/css/custom.css) - -## Custom Full Text Feed Rules -The News app uses [picoFeed](https://github.com/fguillot/picoFeed) for parsing RSS and Atom feeds. It also provides a web scraper which can be extended with custom rules. If you want to extend these rules or add your own ones, follow [the picoFeed documentation](https://github.com/fguillot/picoFeed/blob/master/docs/grabber.markdown#how-to-write-a-grabber-rules-file) - -## Custom CSS -Sometimes you want to add additional CSS for a feed to improve the rendering. This can very easily be done by adding a CSS class to **css/custom.css** following the following naming convention: - -* Take the URL from the \<link> attribute (e.g.: \<link>https://www.google.de/path?my=query \</link>) -* Extract the Domain from the URL (e.g.: www.google.de) -* Strip the leading **www.** (e.g.: google.de) -* Replace all . with - (e.g.: google-de) -* Prepend **custom-** (e.g.: custom-google-de) - -Each class rule should be prefixed with **#app-content** and should only affect the article body. An example rule would be: - -```css -#app-content .custom-google-de .body { - /* Custom CSS rules here */ -} -```
\ No newline at end of file diff --git a/docs/explore/README.md b/docs/explore/README.md new file mode 100644 index 000000000..37b449544 --- /dev/null +++ b/docs/explore/README.md @@ -0,0 +1,48 @@ +# 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/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 +{ + "Tech": [ // category + { + "title": "ownCloud Planet", + "url": "http://owncloud.org/news/", // link to the page so the user can view it + "feed": "http://owncloud.org/feed/", // link to the exact feed location so we can test if the user uses it already + "description": "ownCloud Planet is a feed aggregator", + "votes": 3121, // the higher the vote count, the further up the entry will appear + "favicon": "http://owncloud.org/wp-content/themes/owncloudorgnew/assets/img/common/favicon.png", // optional + }, // etc + ] +} +``` + +To ease the pain of constructing the JSON object, you can use a small script to automatically create it: + + php -f bin/tools/generate_explore.php 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 -f bin/tools/generate_explore.php 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!**
\ No newline at end of file diff --git a/docs/developer/externalapi/Legacy.md b/docs/externalapi/Legacy.md index 6b4afc2c3..6b4afc2c3 100644 --- a/docs/developer/externalapi/Legacy.md +++ b/docs/externalapi/Legacy.md diff --git a/docs/feedcss/README.md b/docs/feedcss/README.md new file mode 100644 index 000000000..74f652eaf --- /dev/null +++ b/docs/feedcss/README.md @@ -0,0 +1,16 @@ +# Custom CSS +Sometimes you want to add additional CSS for a feed to improve the rendering. This can very easily be done by adding a CSS class to **css/custom.css** following the following naming convention: + +* Take the URL from the \<link> attribute (e.g.: \<link>https://www.google.de/path?my=query \</link>) +* Extract the Domain from the URL (e.g.: www.google.de) +* Strip the leading **www.** (e.g.: google.de) +* Replace all . with - (e.g.: google-de) +* Prepend **custom-** (e.g.: custom-google-de) + +Each class rule should be prefixed with **#app-content** and should only affect the article body. An example rule would be: + +```css +#app-content .custom-google-de .body { + /* Custom CSS rules here */ +} +```
\ No newline at end of file diff --git a/docs/developer/plugins/README.md b/docs/plugins/README.md index 4116de3d7..4116de3d7 100644 --- a/docs/developer/plugins/README.md +++ b/docs/plugins/README.md |