18 files changed, 377 insertions, 93 deletions

diff --git a/doc/custom_theme/main.html b/doc/custom_theme/main.html
new file mode 100644
index 00000000..cc2a703e
--- /dev/null
+++ b/doc/custom_theme/main.html
@@ -0,0 +1,23 @@
+{% extends "base.html" %}
+
+{#
+The entry point for the ReadTheDocs Theme.
+ 
+Any theme customisations should override this file to redefine blocks defined in
+the various templates. The custom theme should only need to define a main.html
+which `{% extends "base.html" %}` and defines various blocks which will replace
+the blocks defined in base.html and its included child templates.
+#}
+
+{%- block site_meta %}
+<meta charset="utf-8">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+
+{%- if 'media.readthedocs.org' not in config.extra_css[0] %}
+<meta name="robots" content="noindex, nofollow">
+{%- endif %}
+
+{% if page and page.is_homepage %}<meta name="description" content="{{ config.site_description }}">{% endif %}
+{% if config.site_author %}<meta name="author" content="{{ config.site_author }}">{% endif %}
+{%- endblock %}
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index 49c20c9c..c66d1c70 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -22,7 +22,8 @@ See [REST API](REST-API) for a list of official and community clients.
 - [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
 - [shaarli2mastodon](https://github.com/kalvn/shaarli2mastodon) by [@kalvn](https://github.com/kalvn) - This Shaarli plugin allows you to automatically publish links you post on your Mastodon timeline.
 - [shaarli-descriptor](https://github.com/immanuelfodor/shaarli-descriptor) by [@immanuelfodor](https://github.com/immanuelfodor) - Customize the default height/number of rows of the Description field when editing a link.
-
+- [urlextern](https://github.com/trailjeep/shaarli-urlextern) by [@trailjeep](https://github.com/trailjeep) - Shaarli plugin to open external links in a new tab/window.
+- [favicons](https://github.com/trailjeep/shaarli-favicons) by [@trailjeep](https://github.com/trailjeep) - Shaarli plugin to add favicon/filetype icons to links.
 
 ### Third-party themes
 See [Theming](Theming) for a list of community-contributed themes, and an installation guide.
@@ -51,7 +52,7 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
 - [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among French shaarliers: [shaarli.fr](http://shaarli.fr/))
 - [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
 - [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
-- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
+- [Self dead link](https://framagit.org/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://framagit.org/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
 - [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html. 
 
 ## Alternatives to Shaarli
diff --git a/doc/md/Link-structure.md b/doc/md/Link-structure.md
new file mode 100644
index 00000000..0a2d0f88
--- /dev/null
+++ b/doc/md/Link-structure.md
@@ -0,0 +1,18 @@
+## Link structure
+
+Every link available through the `LinkDB` object is represented as an array 
+containing the following fields:
+
+  * `id` (integer): Unique identifier.
+  * `title` (string): Title of the link.
+  * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.).  
+           Can be absolute or relative for Notes.
+  * `real_url` (string): Real destination URL, can be redirected, encoded, etc.
+  * `shorturl` (string): Permalink small hash.
+  * `description` (string): Link text description.
+  * `private` (boolean): whether the link is private or not.
+  * `tags` (string): all link tags separated by a single space
+  * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any.
+  * `created` (DateTime): link creation date time.
+  * `updated` (DateTime): last modification date time.
+  
\ No newline at end of file
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
index c016de56..11bd1cd2 100644
--- a/doc/md/REST-API.md
+++ b/doc/md/REST-API.md
@@ -152,3 +152,22 @@ See the reference API client:
 
 - [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
 - [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github
+
+## Troubleshooting
+
+### Debug mode
+
+> This should never be used in a production environment.
+
+For security reasons, authentication issues will always return an `HTTP 401` error code without any detail.
+
+It is possible to enable the debug mode in `config.json.php` 
+to get the actual error message in the HTTP response body with:
+
+```json
+{
+  "dev": {
+    "debug": true
+  }
+}
+```
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index ca82b2ec..78083a46 100644
--- a/doc/md/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -18,7 +18,7 @@ Version | Status | Shaarli compatibility
 7.2 | Supported | Yes
 7.1 | Supported | Yes
 7.0 | Supported | Yes
-5.6 | Supported | Yes
+5.6 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x)
 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)
@@ -29,7 +29,7 @@ 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-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails
 [`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)
@@ -397,6 +397,7 @@ 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`
@@ -405,6 +406,12 @@ If Shaarli is served behind a proxy (i.e. there is a proxy server between client
 
 See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
 
+## Robots and crawlers
+
+Shaarli disallows indexing and crawling of your local documentation pages by search engines, using `<meta name="robots">` HTML tags.
+Your Shaarli instance and other pages you host may still be indexed by various robots on the public Internet.
+You may want to setup a robots.txt file or other crawler control mechanism on your server.
+See [[1]](https://en.wikipedia.org/wiki/Robots_exclusion_standard), [[2]](https://support.google.com/webmasters/answer/6062608?hl=en) and [[3]](https://developers.google.com/search/reference/robots_meta_tag)
 
 ## See also
 
diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md
index 4910ff6c..9a16fc62 100644
--- a/doc/md/Sharing-content.md
+++ b/doc/md/Sharing-content.md
@@ -15,7 +15,6 @@ While logged in to your Shaarli, you can add new Shaares in several ways:
 
  * [+Shaare button](#shaare-button)
  * [Bookmarklet](#bookmarklet)
- * [Firefox Share](#firefox-share)
  * Third-party [apps and browser addons](Community-&-Related-software.md#mobile-apps)
  * [REST API](https://shaarli.github.io/api-documentation/)
 
@@ -52,22 +51,6 @@ bookmarklet in your browser! The same `New Shaare` dialog as above is displayed.
 ![](images/bookmarklet.png)
 
 
-### Firefox Share
-
-Before using Firefox Share, you must first add Shaarli as a sharing provider:
-
-- Click the `Tools` button in the top bar
-- Click the `✚Add to Firefox social` button and accept the activation.
-
-Once this is done, you can share any URL you are visiting by clicking the Firefox
-_Share_ button ![images/firefoxshare.png](images/firefoxshare.png)
-
-| Note | Firefox Share is no longer available for Firefox 57 and later versions. |
-|---------|---------|
-
-| Note | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plaintext HTTP connections. |
-|---------|---------|
-
 --------------------------------------------------------------------------------
 
 ## Editing Shaares
diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/guides/backup-restore-import-export.md
index bb790074..bb790074 100644
--- a/doc/md/Backup,-restore,-import-and-export.md
+++ b/doc/md/guides/backup-restore-import-export.md
diff --git a/doc/md/guides/images/01-create-droplet-distro.jpg b/doc/md/guides/images/01-create-droplet-distro.jpg
new file mode 100644
index 00000000..63682ba8
--- /dev/null
+++ b/doc/md/guides/images/01-create-droplet-distro.jpg
diff --git a/doc/md/guides/images/02-create-droplet-region.jpg b/doc/md/guides/images/02-create-droplet-region.jpg
new file mode 100644
index 00000000..135a78be
--- /dev/null
+++ b/doc/md/guides/images/02-create-droplet-region.jpg
diff --git a/doc/md/guides/images/03-create-droplet-size.jpg b/doc/md/guides/images/03-create-droplet-size.jpg
new file mode 100644
index 00000000..aa5b2fd2
--- /dev/null
+++ b/doc/md/guides/images/03-create-droplet-size.jpg
diff --git a/doc/md/guides/images/04-finalize.jpg b/doc/md/guides/images/04-finalize.jpg
new file mode 100644
index 00000000..68ec0dc5
--- /dev/null
+++ b/doc/md/guides/images/04-finalize.jpg
diff --git a/doc/md/guides/images/05-droplet.jpg b/doc/md/guides/images/05-droplet.jpg
new file mode 100644
index 00000000..44e93a1e
--- /dev/null
+++ b/doc/md/guides/images/05-droplet.jpg
diff --git a/doc/md/guides/images/06-domain.jpg b/doc/md/guides/images/06-domain.jpg
new file mode 100644
index 00000000..5827dd93
--- /dev/null
+++ b/doc/md/guides/images/06-domain.jpg
diff --git a/doc/md/guides/images/07-installation.jpg b/doc/md/guides/images/07-installation.jpg
new file mode 100644
index 00000000..42cc9f10
--- /dev/null
+++ b/doc/md/guides/images/07-installation.jpg
diff --git a/doc/md/guides/install-shaarli-with-debian9-and-docker.md b/doc/md/guides/install-shaarli-with-debian9-and-docker.md
new file mode 100644
index 00000000..f1b26d47
--- /dev/null
+++ b/doc/md/guides/install-shaarli-with-debian9-and-docker.md
@@ -0,0 +1,257 @@
+_Last updated on 2018-07-01._
+
+## Goals
+- Getting a Virtual Private Server (VPS)
+- Running Shaarli:
+    - as a Docker container,
+    - using the Træfik reverse proxy,
+    - securized with TLS certificates from Let's Encrypt.
+
+
+The following components and tools will be used:
+
+- [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in
+  server environments;
+- [Docker](https://docs.docker.com/engine/docker-overview/), an open platform
+  for developing, shipping, and running applications;
+- [Docker Compose](https://docs.docker.com/compose/), a tool for defining and
+  running multi-container Docker applications.
+
+
+More information can be found in the [Resources](#resources) section at the
+bottom of the guide.
+
+## Getting a Virtual Private Server
+For this guide, I went for the smallest VPS available from DigitalOcean,
+a Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD storage, which costs
+$5/month ($0.007/hour):
+
+- [Droplets Overview](https://www.digitalocean.com/docs/droplets/overview/)
+- [Pricing](https://www.digitalocean.com/pricing/)
+- [How to Create a Droplet from the DigitalOcean Control Panel](https://www.digitalocean.com/docs/droplets/how-to/create/)
+- [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/)
+- [Initial Server Setup with Debian 8](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8) (also applies to Debian 9)
+- [An Introduction to Securing your Linux VPS](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)
+
+### Creating a Droplet
+Select `Debian 9` as the Droplet distribution:
+
+<img src="../images/01-create-droplet-distro.jpg"
+     width="500px"
+     alt="Droplet distribution" />
+
+Choose a region that is geographically close to you:
+
+<img src="../images/02-create-droplet-region.jpg"
+     width="500px"
+     alt="Droplet region" />
+
+Choose a Droplet size that corresponds to your usage and budget:
+
+<img src="../images/03-create-droplet-size.jpg"
+     width="500px"
+     alt="Droplet size" />
+
+Finalize the Droplet creation:
+
+<img src="../images/04-finalize.jpg"
+     width="500px"
+     alt="Droplet finalization" />
+
+Droplet information is displayed on the Control Panel:
+
+<img src="../images/05-droplet.jpg"
+     width="500px"
+     alt="Droplet summary" />
+
+Once your VPS has been created, you will receive an e-mail with connection
+instructions.
+
+## Obtaining a domain name
+After creating your VPS, it will be reachable using its IP address; some hosting
+providers also create a DNS record, e.g. `ns4853142.ip-01-47-127.eu`.
+
+A domain name (DNS record) is required to obtain a certificate and setup HTTPS
+(HTTP with TLS encryption).
+
+Domain names can be obtained from registrars through hosting providers such as
+[Gandi](https://www.gandi.net/en/domain).
+
+Once you have your own domain, you need to create a new DNS record that points
+to your VPS' IP address:
+
+<img src="../images/06-domain.jpg"
+     width="650px"
+     alt="Domain configuration" />
+
+## Host setup
+Now's the time to connect to your freshly created VPS!
+
+```shell
+$ ssh root@188.166.85.8
+
+Linux stretch-shaarli-02 4.9.0-6-amd64 #1 SMP Debian 4.9.88-1+deb9u1 (2018-05-07) x86_64
+
+The programs included with the Debian GNU/Linux system are free software;
+the exact distribution terms for each program are described in the
+individual files in /usr/share/doc/*/copyright.
+
+Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
+permitted by applicable law.
+Last login: Sun Jul  1 11:20:18 2018 from <REDACTED>
+
+root@stretch-shaarli-02:~$
+```
+
+### Updating the system
+```shell
+root@stretch-shaarli-02:~$ apt update && apt upgrade -y
+```
+
+### Setting up Docker
+_The following instructions are from the
+[Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
+guide._
+
+Install package dependencies:
+
+```shell
+root@stretch-shaarli-02:~$ apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common
+```
+
+Add Docker's package repository GPG key:
+
+```shell
+root@stretch-shaarli-02:~$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
+```
+
+Add Docker's package repository:
+
+```shell
+root@stretch-shaarli-02:~$ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian stretch stable"
+```
+
+Update package lists and install Docker:
+
+```shell
+root@stretch-shaarli-02:~$ apt update && apt install -y docker-ce
+```
+
+Verify Docker is properly configured by running the `hello-world` image:
+
+```shell
+root@stretch-shaarli-02:~$ docker run hello-world
+```
+
+### Setting up Docker Compose
+_The following instructions are from the
+[Install Docker Compose](https://docs.docker.com/compose/install/)
+guide._
+
+Download the current version from the release page:
+
+```shell
+root@stretch-shaarli-02:~$ curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
+root@stretch-shaarli-02:~$ chmod +x /usr/local/bin/docker-compose
+```
+
+## Running Shaarli
+Shaarli comes with a configuration file for Docker Compose, that will setup:
+
+- a local Docker network
+- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Shaarli data
+- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Træfik TLS configuration and certificates
+- a [Shaarli](https://hub.docker.com/r/shaarli/shaarli/) instance
+- a [Træfik](https://hub.docker.com/_/traefik/) instance
+
+[Træfik](https://docs.traefik.io/) is a modern HTTP reverse proxy, with native
+support for Docker and [Let's Encrypt](https://letsencrypt.org/).
+
+### Compose configuration
+Create a new directory to store the configuration:
+
+```shell
+root@stretch-shaarli-02:~$ mkdir shaarli && cd shaarli
+root@stretch-shaarli-02:~/shaarli$
+```
+
+Download the current version of Shaarli's `docker-compose.yml`:
+
+```shell
+root@stretch-shaarli-02:~/shaarli$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml
+```
+
+Create the `.env` file and fill in your VPS and domain information (replace
+`<MY_SHAARLI_DOMAIN>` and `<MY_CONTACT_EMAIL>` with your actual information):
+
+```shell
+root@stretch-shaarli-02:~/shaarli$ vim .env
+```
+
+```shell
+SHAARLI_VIRTUAL_HOST=<MY_SHAARLI_DOMAIN>
+SHAARLI_LETSENCRYPT_EMAIL=<MY_CONTACT_EMAIL>
+```
+
+### Pull the Docker images
+```shell
+root@stretch-shaarli-02:~/shaarli$ docker-compose pull
+Pulling shaarli ... done
+Pulling traefik ... done
+```
+
+### Run!
+```shell
+root@stretch-shaarli-02:~/shaarli$ docker-compose up -d
+Creating network "shaarli_http-proxy" with the default driver
+Creating volume "shaarli_traefik-acme" with default driver
+Creating volume "shaarli_shaarli-data" with default driver
+Creating shaarli_shaarli_1 ... done
+Creating shaarli_traefik_1 ... done
+```
+
+## Conclusion
+Congratulations! Your Shaarli instance should be up and running, and available
+at `https://<MY_SHAARLI_DOMAIN>`.
+
+<img src="../images/07-installation.jpg"
+     width="500px"
+     alt="Shaarli installation page" />
+
+## Resources
+### Related Shaarli documentation
+- [Docker 101](../docker/docker-101.md)
+- [Shaarli images](../docker/shaarli-images.md)
+
+### Hosting providers
+- [DigitalOcean](https://www.digitalocean.com/)
+- [Gandi](https://www.gandi.net/en)
+- [OVH](https://www.ovh.co.uk/)
+- [RackSpace](https://www.rackspace.com/)
+- etc.
+
+### Domain Names and Registrars
+- [Introduction to the Domain Name System (DNS)](https://opensource.com/article/17/4/introduction-domain-name-system-dns)
+- [ICANN](https://www.icann.org/)
+- [Domain name registrar](https://en.wikipedia.org/wiki/Domain_name_registrar)
+- [OVH Domain Registration](https://www.ovh.co.uk/domains/)
+- [Gandi Domain Registration](https://www.gandi.net/en/domain)
+
+### HTTPS and Security
+- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security)
+- [Let's Encrypt](https://letsencrypt.org/)
+
+### Docker
+- [Docker Overview](https://docs.docker.com/engine/docker-overview/)
+- [Docker Documentation](https://docs.docker.com/)
+- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
+- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
+- [Volumes](https://docs.docker.com/storage/volumes/)
+- [Install Docker Compose](https://docs.docker.com/compose/install/)
+- [docker-compose logs](https://docs.docker.com/compose/reference/logs/)
+
+### Træfik
+- [Getting Started](https://docs.traefik.io/)
+- [Docker backend](https://docs.traefik.io/configuration/backends/docker/)
+- [Let's Encrypt and Docker](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/)
+- [traefik](https://hub.docker.com/_/traefik/) Docker image
diff --git a/doc/md/Various-hacks.md b/doc/md/guides/various-hacks.md
index 0074ae9f..0074ae9f 100644
--- a/doc/md/Various-hacks.md
+++ b/doc/md/guides/various-hacks.md
diff --git a/doc/md/images/icon.png b/doc/md/images/icon.png
new file mode 100644
index 00000000..530d7469
--- /dev/null
+++ b/doc/md/images/icon.png
diff --git a/doc/md/index.md b/doc/md/index.md
index c18332b4..220eeec1 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -1,25 +1,19 @@
-# [Shaarli](https://github.com/shaarli/Shaarli/) documentation
+# <img src="images/icon.png" width="20px" height="20px"> 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.
+Shaarli is a minimalist bookmark manager and link sharing service that you can install on your own server.
 It is designed to be personal (single-user), fast and handy.
 
 <!-- TODO screenshots -->
 
-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).
+Visit the pages in the sidebar to find information on how to setup, use, configure, tweak and troubleshoot Shaarli.
 
-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).
 
 * [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)
+* [Online documentation](https://shaarli.readthedocs.io/)
+* [Latest releases](https://github.com/shaarli/Shaarli/releases)
 * [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md)
 
 
@@ -30,87 +24,70 @@ 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:
 
-- to share, comment and save interesting links and news.
-- to bookmark useful/frequent personal links (as private links) and share them between computers.
-- as a minimal blog/microblog/writing platform (no character limit).
-- as a read-it-later list (for example items tagged `readlater`).
-- to draft and save articles/posts/ideas.
-- to keep code snippets.
-- to keep notes and documentation.
-- as a shared clipboard/notepad/pastebin between machines.
-- as a todo list.
-- to store playlists (e.g. with the `music` or `video` tags).
+- to share, comment and save interesting links and news
+- to bookmark useful/frequent links and share them between computers
+- as a minimal blog/microblog/writing platform
+- as a read-it-later list
+- to draft and save articles/posts/ideas
+- to keep notes, documentation and code snippets
+- as a shared clipboard/notepad/pastebin between machines
+- as a todo list
+- to store media playlists
 - to keep extracts/comments from webpages that may disappear.
-- to keep track of ongoing discussions (for example items tagged `discussion`).
-- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags.
-- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...).
+- to keep track of ongoing discussions
+- to feed other blogs, aggregators, social networks... using RSS feeds
 
-### Interface
+### Edit, view and search your links
 
-- minimalist design (simple is beautiful)
+- Minimalist design
 - FAST
-- ATOM and RSS feeds
-- views:
-    - paginated link list (with image and video thumbnails)
-    - tag cloud
-    - 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
+- Customizable link titles and descriptions
+- Tags to organize your links (features tag autocompletion, renaming, merging and deletion)
+- Search by tag or using the full-text search
+- Public and private links (visible only to logged-in users)
+- Unique permalinks for easy reference
+- Paginated link list (with image and video thumbnails)
+- Tag cloud and list views
+- Picture wall: image and video thumbnails view (with lazy loading)
+- ATOM and RSS feeds (can also be filtered using tags or text search)
+- Daily: newspaper-like daily digest (and daily RSS feed)
 - 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
-
-- add a custom title and description to archived links
-- add tags to classify and search links
-  - features tag autocompletion, renaming, merging and deletion
-- full-text and tag search
+- Extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage)
 
 ### Easy setup
 
-- dead-simple installation: drop the files, open the page
-- links are stored in a file
-    - compact storage
-    - no database required
-    - easy backup: simply copy the datastore file
-- import and export links as Netscape bookmarks
+- Dead-simple installation: drop the files, open the page
+- Links are stored in a file (no database required, easy backup: simply copy the datastore file)
+- Import and export links as Netscape bookmarks compatible with most Web browsers
 
 ### Accessibility
 
-- bookmarlet to share links in one click
-- support for mobile browsers
-- degrades gracefully with Javascript disabled
-- easy page customization through HTML/CSS/RainTPL
+- Bookmarklet and other tools to share links in one click
+- Support for mobile browsers
+- Degrades gracefully with Javascript disabled
+- Easy page customization through HTML/CSS/RainTPL
 
 ### Security
 
-- 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
+- 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
 
-Easily extensible by any client using the REST API exposed by Shaarli.
-
-See the [API documentation](http://shaarli.github.io/api-documentation/).
+- Easily extensible by any client using the REST API exposed by Shaarli ([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 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/).
 
@@ -123,16 +100,15 @@ in this repository, and will keep maintaining the project for the foreseeable
 future, while keeping Shaarli simple and efficient.
 
 
-### Contributing
+### Contributing and getting help
 
-If you'd like to help, please:
+Feedback is very appreciated!
 
-- 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/tree/master/doc/md/)
-- propose solutions to existing problems
-- submit pull requests :-)
+- 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).
+- Have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) and [pull requests](https://github.com/shaarli/Shaarli/pulls)
+- 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).
+- If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
+- Feel free to propose solutions to existing problems, help us improve the documentation and translations, and submit pull requests :-)
 
 
 ### License