Merge pull request #1155 from shaarli/doc-improvements

Improve documentation (#598, #1105)

5 files changed, 178 insertions, 172 deletions

diff --git a/doc/md/3rd-party-libraries.md b/doc/md/3rd-party-libraries.md
index ebab7a46..7e7dd334 100644
--- a/doc/md/3rd-party-libraries.md
+++ b/doc/md/3rd-party-libraries.md
@@ -1,13 +1,21 @@
 ## CSS
-- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/)
-    - resets default CSS properties for all HTML elements (overriding browsers' default values)
-    - ensures custom CSS stylessheets will provide the same results on all browsers
+
+- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - standardize cross-browser rendering
 
 ## Javascript
+
 - [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
 - [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
 - [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
 
 ## PHP
-- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser
+
 - [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP
+
+### Composer
+
+Library | Usage
+---|---
+[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | Import bookmarks from Netscape files
+[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | Parse MarkDown syntax for the MarkDown plugin
+[`slim/slim`](https://packagist.org/packages/slim/slim) | Handle routes and middleware for the REST API
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index b82590f2..14649e06 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -1,8 +1,7 @@
 To install Shaarli, simply place the files in a directory under your webserver's
 Document Root (or directly at the document root).
 
-Also, please make sure your server meets the [requirements](Server-requirements)
-and is properly [configured](Server-configuration).
+Also, please make sure your server is properly [configured](Server-configuration).
 
 Multiple releases branches are available:
 
@@ -23,7 +22,7 @@ Using one of the following methods:
 
 ### Download as an archive
 
-In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies.
+In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. Download our **shaarli-full** archive to include dependencies.
 
 The current latest released version is `v0.9.7`
 
@@ -37,7 +36,7 @@ $ mv Shaarli /path/to/shaarli/
 
 Cloning using `git` or downloading Github branches as zip files requires additional steps:
 
- * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
+ * Install [Composer](Unit-tests.md#install_composer) to manage third-party [PHP dependencies](3rd-party-libraries.md#composer).
  * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies.
  * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation.
 
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index 25dd49fe..ca82b2ec 100644
--- a/doc/md/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -1,139 +1,130 @@
-*Example virtual host configurations for popular web servers*
 
+- [Prerequisites](#prerequisistes)
 - [Apache](#apache)
 - [Nginx](#nginx)
+- [Proxies](#proxies)
+- [See also](#see-also)
 
 ## Prerequisites
 ### Shaarli
-- Shaarli is installed in a directory readable/writeable by the user
-- the correct read/write permissions have been granted to the web server _user and/or group_
-- for HTTPS / SSL:
-    - a key pair (public, private) and a certificate have been generated
-    - the appropriate server SSL extension is installed and active
 
-### HTTPS, TLS and self-signed certificates
-Related guides:
+- A web server and PHP interpreter module/service have been installed.
+- You have write access to the Shaarli installation directory.
+- The correct read/write permissions have been granted to the web server user and group.
+- Your PHP interpreter is compatible with supported PHP versions:
 
-- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
-- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
-- Generate a self-signed certificate (will trigger browser warnings) with apache2:
-  `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
+Version | Status | Shaarli compatibility
+:---:|:---:|:---:
+7.2 | Supported | Yes
+7.1 | Supported | Yes
+7.0 | Supported | Yes
+5.6 | Supported | Yes
+5.5 | EOL: 2016-07-10 | Yes
+5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
+5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
 
-### Proxies
-If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
+- The following PHP extensions are installed on the server:
 
-- `X-Forwarded-Proto`
-- `X-Forwarded-Host`
-- `X-Forwarded-For`
+Extension | Required? | Usage
+---|:---:|---
+[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
+[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
+[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
+[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
+[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
+[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
 
-See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
+--------------------------------------------------------------------------------
 
-## Apache
-### Minimal
-```apache
-<VirtualHost *:80>
-    ServerName   shaarli.my-domain.org
-    DocumentRoot /absolute/path/to/shaarli/
-</VirtualHost>
-```
-### Debug - Log all the things!
-This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
+### SSL/TLS configuration 
 
-See:
+To setup HTTPS / SSL on your webserver (recommended), you must generate a public/private **key pair** and a **certificate**, and install, configure and activate the appropriate **webserver SSL extension**.
 
-- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
-- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
+#### Let's Encrypt
 
-```apache
-<VirtualHost *:80>
-    ServerName   shaarli.my-domain.org
-    DocumentRoot /absolute/path/to/shaarli/
+[Let's Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt) is a certificate authority that provides free TLS/X.509 certificates via an automated process.
 
-    LogLevel  warn
-    ErrorLog  /var/log/apache2/shaarli-error.log
-    CustomLog /var/log/apache2/shaarli-access.log combined
+ * Install `certbot` using the appropriate method described on https://certbot.eff.org/.
+ 
+Location of the `certbot` program and template configuration files may vary depending on which installation method was used. Change the file paths below accordingly. Here is an easy way to create a signed certificate using `certbot`, it assumes `certbot` was installed through APT on a Debian-based distribution:
 
-    php_flag  log_errors on
-    php_flag  display_errors on
-    php_value error_reporting 2147483647
-    php_value error_log /var/log/apache2/shaarli-php-error.log
-</VirtualHost>
-```
+ * Stop the apache2/nginx service.
+ * Run `certbot --agree-tos --standalone --preferred-challenges tls-sni --email "youremail@example.com" --domain yourdomain.example.com`
+ * For the Apache webserver, copy `/usr/lib/python2.7/dist-packages/certbot_apache/options-ssl-apache.conf` to `/etc/letsencrypt/options-ssl-apache.conf` (paths may vary depending on installation method)
+ * For Nginx: TODO
+ * Setup your webserver as described below
+ * Restart the apache2/nginx service.
+
+#### Self-signed certificates
+
+If you don't want to request a certificate from Let's Encrypt, or are unable to (for example, webserver on a LAN, or domain name not registered in the public DNS system), you can generate a self-signed certificate. This certificate will trigger security warnings in web browsers, unless you add it to the browser's SSL store manually.
+
+* Apache: run `make-ssl-cert generate-default-snakeoil --force-overwrite`
+* Nginx: TODO
+
+--------------------------------------------------------------------------------
+
+## Apache
+
+Here is a basic configuration example for the Apache web server with `mod_php`.
+
+In `/etc/apache2/sites-available/shaarli.conf`:
 
-### Standard - Keep access and error logs
 ```apache
-<VirtualHost *:80>
+<VirtualHost *:443>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 
+    # Logging
+    # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
     LogLevel  warn
     ErrorLog  /var/log/apache2/shaarli-error.log
     CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
-```
 
-### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
-See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).
+    # Let's Encrypt SSL configuration (recommended)
+    SSLEngine             on
+    SSLCertificateFile    /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem
+    SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.example.com/privkey.pem
+    Include /etc/letsencrypt/options-ssl-apache.conf
 
-```apache
-<VirtualHost *:443>
-    ServerName   shaarli.my-domain.org
-    DocumentRoot /absolute/path/to/shaarli/
+    # Self-signed SSL cert configuration
+    #SSLEngine             on
+    #SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
+    #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
 
-    SSLEngine             on
-    SSLCertificateFile    /absolute/path/to/the/website/certificate.pem
-    SSLCertificateKeyFile /absolute/path/to/the/website/key.key
+    # Optional, log PHP errors, useful for debugging
+    #php_flag  log_errors on
+    #php_flag  display_errors on
+    #php_value error_reporting 2147483647
+    #php_value error_log /var/log/apache2/shaarli-php-error.log
 
     <Directory /absolute/path/to/shaarli/>
+        #Required for .htaccess support
         AllowOverride All
-        Options Indexes FollowSymLinks MultiViews
         Order allow,deny
-        allow from all
-    </Directory>
+        Allow from all
 
-    LogLevel  warn
-    ErrorLog  /var/log/apache2/shaarli-error.log
-    CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
-<VirtualHost *:80>
-    ServerName   shaarli.my-domain.org
-    Redirect 301 / https://shaarli.my-domain.org
+        Options Indexes FollowSymLinks MultiViews #TODO is Indexes/Multiviews required?
+
+        # Optional - required for playvideos plugin
+        #Header set Content-Security-Policy "script-src 'self' 'unsafe-inline' https://www.youtube.com https://s.ytimg.com 'unsafe-eval'"
+    </Directory>
 
-    LogLevel  warn
-    ErrorLog  /var/log/apache2/shaarli-error.log
-    CustomLog /var/log/apache2/shaarli-access.log combined
 </VirtualHost>
 ```
 
-### .htaccess
+Enable this configuration with `sudo a2ensite shaarli`
 
-Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
+_Note: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled._
 
-**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.
- 
-Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
+_Note: Apache module `mod_rewrite` must be enabled to use the REST API._
 
-## LightHttpd
 
 ## Nginx
-### Foreword
-Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
-
-Required packages:
 
-- [nginx](http://nginx.org)
-- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
+Here is a basic configuration example for the Nginx web server, using the [php-fpm](http://php-fpm.org) PHP FastCGI Process Manager, and Nginx's [FastCGI](https://en.wikipedia.org/wiki/FastCGI) module.
 
-Official documentation:
-
-- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
-- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
-- [Pitfalls](http://wiki.nginx.org/Pitfalls)
-
-Community resources:
-
-- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
-- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
+<!--- TODO refactor everything below this point --->
 
 ### Common setup
 Once Nginx and PHP-FPM are installed, we need to ensure:
@@ -404,3 +395,39 @@ http {
     }
 }
 ```
+
+## Proxies
+If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
+
+- `X-Forwarded-Proto`
+- `X-Forwarded-Host`
+- `X-Forwarded-For`
+
+See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
+
+
+## See also
+
+ * [Server security](Server-security.md)
+
+#### Webservers
+
+- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
+- [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
+- [Server-side TLS (Apache)](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla)
+- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
+- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
+- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
+- [Nginx PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
+- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
+- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
+- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
+
+#### PHP
+
+- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
+- [PHP: Supported versions](http://php.net/supported-versions.php)
+- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
+- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
+- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
+- [PHP: Bugs](https://bugs.php.net/)
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
deleted file mode 100644
index 2dc442df..00000000
--- a/doc/md/Server-requirements.md
+++ /dev/null
@@ -1,42 +0,0 @@
-## PHP
-
-### Release information
-- [PHP: Supported versions](http://php.net/supported-versions.php)
-- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
-- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
-- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
-- [PHP: Bugs](https://bugs.php.net/)
-
-### Supported versions
-Version | Status | Shaarli compatibility
-:---:|:---:|:---:
-7.1 | Supported (v0.9.x) | Yes
-7.0 | Supported | Yes
-5.6 | Supported | Yes
-5.5 | EOL: 2016-07-10 | Yes
-5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
-5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
-
-See also:
-
-- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
-
-### Dependency management
-Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,
-download and install third-party PHP dependencies.
-
-Library | Required? | Usage
----|:---:|---
-[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files
-[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin
-[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API
-
-### Extensions
-Extension | Required? | Usage
----|:---:|---
-[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
-[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
-[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
-[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
-[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
-[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
diff --git a/doc/md/index.md b/doc/md/index.md
index 224070cb..21a63d3c 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -1,19 +1,27 @@
 # [Shaarli](https://github.com/shaarli/Shaarli/) documentation
 
-Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
+The personal, minimalist, super-fast, database free, bookmarking service.
+
+Do you want to share the links you discover?
+Shaarli is a minimalist link sharing service that you can install on your own server.
+It is designed to be personal (single-user), fast and handy.
+
+<!--- TODO screenshots --->
 
-For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
+Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
+For general information, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
 
 If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues).
+
 If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
 
 If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).
 
-_Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the `doc/html/` directory of your Shaarli installation._
+* [GitHub project page](https://github.com/shaarli/Shaarli)
+* [Online documentation](https://shaarli.readthedocs.io/) (this page)
+* [Latest Shaarli releases](https://github.com/shaarli/Shaarli/releases)
+* [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md)
 
-[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli)
-[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues)
-[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/)
 
 ### Demo
 
@@ -22,6 +30,9 @@ It runs the latest development version of Shaarli and is updated/reset daily.
 
 Login: `demo`; Password: `demo`
 
+<!---- TODO review everything below this point --->
+
+
 ## Features
 
 Shaarli can be used:
@@ -42,26 +53,31 @@ Shaarli can be used:
 - to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...).
 
 ### Interface
+
 - minimalist design (simple is beautiful)
 - FAST
 - ATOM and RSS feeds
 - views:
-    - paginated link list
+    - paginated link list (with image and video thumbnails)
     - tag cloud
-    - picture wall: image and video thumbnails
+    - picture wall: image and video thumbnails (with lazy loading)
     - daily: newspaper-like daily digest
     - daily RSS feed
 - permalinks for easy reference
 - links can be public or private
+- thumbnail generation for images and video services
+- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
 - extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage)
 
-### Tag, view and search your links!
+### Tag, view and search your links
+
 - add a custom title and description to archived links
 - add tags to classify and search links
-    - features tag autocompletion, renaming, merging and deletion
+  - features tag autocompletion, renaming, merging and deletion
 - full-text and tag search
 
 ### Easy setup
+
 - dead-simple installation: drop the files, open the page
 - links are stored in a file
     - compact storage
@@ -70,23 +86,19 @@ Shaarli can be used:
 - import and export links as Netscape bookmarks
 
 ### Accessibility
-- Firefox bookmarlet to share links in one click
+
+- bookmarlet to share links in one click
 - support for mobile browsers
-- works with Javascript disabled
+- degrades gracefully with Javascript disabled
 - easy page customization through HTML/CSS/RainTPL
 
 ### Security
-- bruteforce-proof login form
-- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery)
-and session cookie hijacking
-
-### Goodies
-- thumbnail generation for images and video services:
-dailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...
-    - lazy-loading with [bLazy](http://dinbror.dk/blazy/)
-- [PubSubHubbub](https://code.google.com/p/pubsubhubbub/) protocol support
-- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
+
 - discreet pop-up notification when a new release is available
+- bruteforce protection on the login form
+- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking
+
+<!---- TODO Limitations --->
 
 ### REST API
 
@@ -95,28 +107,30 @@ Easily extensible by any client using the REST API exposed by Shaarli.
 See the [API documentation](http://shaarli.github.io/api-documentation/).
 
 ## About
+
 ### Shaarli community fork
+
 This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli
 
 This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/).
 
-The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191)
-that he would have no time to work on Shaarli in the near future.
-The Shaarli community has carried on the work to provide
-[many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master)
-for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+)
-in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
+The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) that he would have no time to work on Shaarli in the near future.
+
+The Shaarli community has carried on the work to provide [many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
+
 
 ### Contributing
+
 If you'd like to help, please:
 - have a look at the open [issues](https://github.com/shaarli/Shaarli/issues)
 and [pull requests](https://github.com/shaarli/Shaarli/pulls)
 - feel free to report bugs (feedback is much appreciated)
-- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/wiki)
+- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/tree/master/doc/md/)
 - propose solutions to existing problems
 - submit pull requests :-)
 
 
 ### License
-Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](COPYING) for a detail of the contributors and licenses for each individual component.
+
+Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail of the contributors and licenses for each individual component. A list of contributors is available [here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS).