miniflux-legacy/README.markdown

282 lines
9.2 KiB
Markdown
Raw Normal View History

2013-03-17 23:16:25 +01:00
Miniflux - Minimalist News Reader
2013-02-18 03:48:21 +01:00
=================================
Miniflux is a minimalist web-based news reader.
Features
--------
- Host anywhere (shared hosting, vps or localhost)
- Easy setup => copy and paste and you are done!
- CSS optimized for readability
2013-07-04 13:01:14 +02:00
- Keeps history of read items
2013-02-18 03:48:21 +01:00
- Remove Feedburner Ads and analytics trackers
2013-07-04 13:01:14 +02:00
- Import/Export of OPML feeds
- Feed updates via a cronjob or with the user interface with one click
2013-02-18 03:48:21 +01:00
- Protected by a login/password (only one possible user)
2013-04-06 03:52:58 +02:00
- Use secure headers (only external images and Youtube/Vimeo videos are allowed)
2013-02-24 20:09:16 +01:00
- Open external links inside a new tab with a `rel="noreferrer"` attribute
2013-03-17 23:16:25 +01:00
- Mobile CSS (responsive design)
- Keyboard shortcuts (pressing '?' displays a pop-up listing the shortcuts; pressing 'q' closes it)
2013-06-15 05:22:22 +02:00
- Basic bookmarks
2013-07-21 17:11:41 +02:00
- Translated in English, French, German, Italian, Czech and Simplified Chinese
2013-07-20 03:01:55 +02:00
- Themes
2013-02-18 03:48:21 +01:00
2013-04-06 03:52:58 +02:00
Todo and known bugs
-------------------
2013-02-18 03:48:21 +01:00
2013-04-06 03:52:58 +02:00
- See Issues: <https://github.com/fguillot/miniflux/issues>
2013-02-18 03:48:21 +01:00
2013-03-17 23:30:07 +01:00
License
-------
- AGPL: <http://www.gnu.org/licenses/agpl-3.0.txt>
2013-04-06 03:58:17 +02:00
Authors
-------
2013-07-09 00:31:25 +02:00
Original author: [Frédéric Guillot](http://fredericguillot.com/)
### Contributors
People who sent one or many pull-requests:
- André Kelpe: https://github.com/fs111
- Ayodio: https://github.com/ayodio
2013-08-04 20:26:46 +02:00
- Bjauy: https://github.com/bjauy
2013-08-18 18:28:15 +02:00
- Chase Arnold: https://github.com/chase4926
2013-07-20 03:01:55 +02:00
- Chris Lemonier: https://github.com/chrislemonier
2013-07-09 00:31:25 +02:00
- Derjus: https://github.com/derjus
- Eauland: https://github.com/eauland
- Félix: https://github.com/dysosmus
- Horsely: https://github.com/horsley
2013-07-14 18:35:11 +02:00
- Ing. Jan Kaláb: https://github.com/Pitel
2013-07-21 17:11:41 +02:00
- James Scott-Brown: https://github.com/jamesscottbrown
2013-07-09 00:31:25 +02:00
- Luca Marra: https://github.com/facciocose
2013-07-20 15:10:17 +02:00
- Maxime: https://github.com/EpocDotFr
2013-07-09 00:31:25 +02:00
- MonsieurPaulLeBoulanger: https://github.com/MonsieurPaulLeBoulanger
- Necku: https://github.com/Necku
- Thiriot Christophe: https://github.com/doubleface
- Ygbillet: https://github.com/ygbillet
2013-07-09 00:40:19 +02:00
PS: Many people sent a bug report too (see [issues tracker](https://github.com/fguillot/miniflux/issues))
2013-07-09 00:39:07 +02:00
Roadmap
-------
- http://miniflux.net/roadmap.html
ChangeLog
2013-07-09 00:40:19 +02:00
---------
2013-07-09 00:39:07 +02:00
- http://miniflux.net/changes.html
2013-04-06 03:58:17 +02:00
2013-02-18 03:48:21 +01:00
Requirements
------------
- Recent version of libxml2 >= 2.7.x (version 2.6.32 on Debian Lenny are not supported anymore)
- PHP >= 5.3.7
2013-03-17 23:16:25 +01:00
- PHP XML extensions (SimpleXML, DOM...)
2013-04-06 03:52:58 +02:00
- PHP Sqlite extension
2013-02-18 03:48:21 +01:00
2013-03-17 23:16:25 +01:00
Libraries used
--------------
2013-02-18 03:48:21 +01:00
- [PicoFeed](https://github.com/fguillot/picoFeed)
- [PicoFarad](https://github.com/fguillot/picoFarad)
- [PicoTools](https://github.com/fguillot/picoTools)
- [PicoDb](https://github.com/fguillot/picoDb)
- [SimpleValidator](https://github.com/fguillot/simpleValidator)
- [PHP 5.5 password backport](https://github.com/ircmaxell/password_compat)
2013-02-18 03:48:21 +01:00
Installation
------------
1. You must have a web server with PHP installed (version 5.3.7 minimum) with the Sqlite and XML extensions
2013-07-04 13:01:14 +02:00
2. Download the source code and copy the directory `miniflux` where you want
3. Check if the directory `data` is writeable (Miniflux stores everything inside a Sqlite database)
2013-03-17 23:16:25 +01:00
4. With your browser go to <http://yourpersonalserver/miniflux>
2013-03-22 00:57:47 +01:00
5. The default login and password is **admin/admin**
2013-03-17 23:16:25 +01:00
6. Start to use the software
FAQ
----
2013-07-04 13:01:14 +02:00
### How do I update my feeds with a cronjob?
2013-03-17 23:16:25 +01:00
2013-05-21 12:25:13 +02:00
You just need to be inside the directory `miniflux` and run the script `cronjob.php`.
Parameters | Type | Value
--------------------|--------------------------------|-----------------------------
2013-05-21 20:18:41 +02:00
--limit | optional | number of feeds
2013-05-21 12:25:13 +02:00
--call-interval | optional, excluded by --limit, require --update-interval | time in minutes < update interval time
--update-interval | optional, excluded by --limit, require --call-interval | time in minutes >= call interval time
2013-03-17 23:16:25 +01:00
2013-05-18 20:35:16 +02:00
Examples:
2013-03-17 23:16:25 +01:00
crontab -e
2013-05-21 12:25:13 +02:00
# Update all feeds
2013-03-17 23:16:25 +01:00
0 */4 * * * cd /path/to/miniflux && php cronjob.php >/dev/null 2>&1
2013-05-18 20:35:16 +02:00
2013-05-21 12:25:13 +02:00
# Update the 10 oldest feeds each time
2013-05-18 20:35:16 +02:00
0 */4 * * * cd /path/to/miniflux && php cronjob.php --limit=10 >/dev/null 2>&1
2013-05-21 12:25:13 +02:00
# Update all feeds in 60 minutes (updates the 8 oldest feeds each time with a total of 120 feeds).
* */4 * * * cd /path/to/miniflux && php cronjob.php --call-interval=4 --update-interval=60 >/dev/null 2>&1
2013-03-17 23:16:25 +01:00
2013-05-22 13:12:58 +02:00
Note: cronjob.php can also be called from the web; in this case specify the options as GET variables.
Example: <http://yourpersonalserver/miniflux/cronjob.php?call-interval=4&update-interval=60>
2013-05-21 20:38:09 +02:00
2013-07-04 13:01:14 +02:00
### How does Miniflux update my feeds from the user interface?
2013-03-17 23:16:25 +01:00
2013-07-04 13:01:14 +02:00
Miniflux uses an Ajax request to refresh each subscription.
2013-03-17 23:16:25 +01:00
By default, there is only 5 feeds updated in parallel.
2013-07-04 13:01:14 +02:00
### I have 600 subscriptions, can Miniflux handle that?
2013-03-17 23:16:25 +01:00
Your life is cluttered.
2013-07-04 13:02:12 +02:00
### Why are there no categories? Why is feature X missing?
Miniflux is a minimalist software. Less is more.
### I found a bug, what next?
2013-03-22 00:57:47 +01:00
Report the bug to the [issues tracker](https://github.com/fguillot/miniflux/issues) and I will fix it.
You can report feeds that doesn't works properly too.
### Which browser is compatible with Miniflux?
2013-07-04 13:01:14 +02:00
Miniflux is tested with the latest versions of Mozilla Firefox, Google Chrome and Safari.
2013-03-22 00:57:47 +01:00
I don't use Microsoft products, and as such I have no idea if Miniflux works correctly with Internet Explorer.
### How do I override application variables?
There are few settings that can't be changed by the user interface.
These parameters are defined with PHP constants.
To override them, create a `config.php` file at the root of the project and change the values.
By example, to override the default HTTP timeout value:
<?php
// My specific HTTP timeout (5 seconds)
define('HTTP_TIMEOUT', 5);
PS: This file must be a PHP file (nothing before the open tag `<?php`).
Actually, the following constants can be overrided:
- `HTTP_TIMEOUT` => default value is 10 seconds
- `APP_VERSION` => default value is master
- `DB_FILENAME` => default value is `data/db.sqlite`
2013-08-30 01:34:11 +02:00
- `DEBUG` => default is true (enable logging of PicoFeed)
- `DEBUG_FILENAME` => default is `data/debug.log`
2013-07-17 03:58:11 +02:00
- `THEME_DIRECTORY` => default is themes
- `SESSION_SAVE_PATH` => default is empty (used to store session files in a custom directory)
### How to change the session save path?
With several shared hosting providers, sessions are cleaned frequently, to avoid to login too often,
you can save sessions in a custom directory.
- Create a directory, by example `sessions`
- This directory must be writeable by the web server user
- This directory must NOT be accessible from the outside world (add a `.htaccess` if necessary)
- Override the application variable like described above: `define('SESSION_SAVE_PATH', 'sessions');`
- Now, your sessions are saved in the directory `sessions`
2013-07-17 03:58:11 +02:00
### How to override/extends the content filtering blacklist/whitelist?
Miniflux use [PicoFeed](https://github.com/fguillot/picoFeed) to parse the content of each item.
These variables are public static arrays, extends the actual array or replace it.
**Be careful, you can break everything by doing that!!!**
Put your modifications in your custom `config.php` like described above.
By example to add a new iframe whitelist:
\PicoFeed\Filter::$iframe_whitelist[] = 'http://www.kickstarter.com';
Or to replace the entire whitelist:
\PicoFeed\Filter::$iframe_whitelist = array('http://www.kickstarter.com');
Available variables:
// Allow only specified tags and attributes
\PicoFeed\Filter::$whitelist_tags
// Strip content of these tags
\PicoFeed\Filter::$blacklist_tags
// Allow only specified URI scheme
\PicoFeed\Filter::$whitelist_scheme
// List of attributes used for external resources: src and href
\PicoFeed\Filter::$media_attributes
// Blacklist of external resources
\PicoFeed\Filter::$media_blacklist
// Required attributes for tags, if the attribute is missing the tag is dropped
\PicoFeed\Filter::$required_attributes
// Add attribute to specified tags
\PicoFeed\Filter::$add_attributes
// Attributes that must be integer
\PicoFeed\Filter::$integer_attributes
// Iframe allowed source
\PicoFeed\Filter::$iframe_whitelist
For more details, have a look to the class `vendor/PicoFeed/Filter.php`.
### Where is the API documentation?
<http://miniflux.net/api.html>
2013-07-17 03:58:11 +02:00
### How to create a theme for Miniflux?
It's very easy to write a custom theme for Miniflux.
A theme is just a CSS file, images and fonts.
A theme doesn't change the behaviour of the application but only the page design.
The first step is to create a new directory structure for your theme:
mkdir -p themes/mysuperskin/{css,img,fonts}
The name of your theme should be only alphanumeric.
There is the following directories inside your theme:
- `css`: Your stylesheet, the file must be named `app.css` (required)
- `img`: Theme images (not required)
- `fonts`: Theme fonts (not required)
For a very basic theme example, have a look to the directory `examples\mytheme`.
Miniflux use responsive design, so it's better if your theme can handle mobile devices.
If you write a very cool theme for Miniflux, **send me your code to be available in the default installation!**
2013-07-20 03:01:55 +02:00
It would be awesome for everybody :)
### List of themes:
2013-07-20 15:10:17 +02:00
- Original theme By Frederic Guillot
- Midnight By Luca Marra
- Green by Maxime (aka EpocDotFr)
### Coding standards for contributors
- Line indentation: 4 spaces
- Line endings: Unix
- File encoding: UTF-8