40 files changed, 421 insertions, 474 deletions

diff --git a/docker/.htaccess b/.docker/.htaccess
index f601c1ee..f601c1ee 100644
--- a/docker/.htaccess
+++ b/.docker/.htaccess
diff --git a/docker/alpine/nginx.conf b/.docker/nginx.conf
index 07fba33f..07fba33f 100644
--- a/docker/alpine/nginx.conf
+++ b/.docker/nginx.conf
diff --git a/docker/alpine/php-fpm.conf b/.docker/php-fpm.conf
index 0843c164..0843c164 100644
--- a/docker/alpine/php-fpm.conf
+++ b/.docker/php-fpm.conf
diff --git a/docker/alpine/services.d/.s6-svscan/finish b/.docker/services.d/.s6-svscan/finish
index 1dadeeaf..1dadeeaf 100755
--- a/docker/alpine/services.d/.s6-svscan/finish
+++ b/.docker/services.d/.s6-svscan/finish
diff --git a/docker/alpine/services.d/nginx/run b/.docker/services.d/nginx/run
index 21e7b0d6..21e7b0d6 100755
--- a/docker/alpine/services.d/nginx/run
+++ b/.docker/services.d/nginx/run
diff --git a/docker/alpine/services.d/php-fpm/run b/.docker/services.d/php-fpm/run
index 21dd0107..21dd0107 100755
--- a/docker/alpine/services.d/php-fpm/run
+++ b/.docker/services.d/php-fpm/run
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..a0d28dc6
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,51 @@
+# Docker-ignore
+.dev
+.git
+.github
+tests
+
+# Shaarli runtime resources
+cache/*
+data/*
+pagecache/*
+tmp/*
+
+# Eclipse project files
+.settings
+.buildpath
+.project
+
+# Raintpl generated pages
+*.rtpl.php
+
+# 3rd-party dependencies
+vendor/
+
+# Release archives
+*.tar.gz
+*.zip
+inc/languages/*/LC_MESSAGES/shaarli.mo
+
+# Development and test resources
+coverage
+doxygen
+sandbox
+phpmd.html
+
+# User plugin configuration
+plugins/*/config.php
+
+# 3rd party themes
+tpl/*
+!tpl/default
+!tpl/vintage
+
+# Front end
+node_modules
+tpl/default/js
+tpl/default/css
+tpl/default/fonts
+tpl/default/img
+tpl/vintage/js
+tpl/vintage/css
+tpl/vintage/img
diff --git a/.gitattributes b/.gitattributes
index 6b6ffbd5..9d22f11b 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -33,7 +33,9 @@ Dockerfile      text
 .travis.yml       export-ignore
 doc/**/*.json     export-ignore
 doc/**/*.md       export-ignore
-docker/           export-ignore
+.docker/          export-ignore
+.dockerignore     export-ignore
+Dockerfile*       export-ignore
 Doxyfile          export-ignore
 Makefile          export-ignore
 node_modules/     export-ignore
diff --git a/.travis.yml b/.travis.yml
index eee1ca74..cb81846f 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -28,6 +28,15 @@ matrix:
         - yarn run build # Just to be sure that the build isn't broken
         - make eslint
         - make sasslint
+    - language: python
+      python: 3.6
+      cache:
+        directories:
+          - $HOME/.cache/pip
+      install:
+        - pip install mkdocs
+      script:
+        - mkdocs build --clean
 
 cache:
   directories:
diff --git a/AUTHORS b/AUTHORS
index c0414c0e..409a0308 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,6 +1,6 @@
-   588  ArthurHoaro <arthur@hoa.ro>
-   283  VirtualTam <virtualtam@flibidi.net>
-   179  nodiscc <nodiscc@gmail.com>
+   647  ArthurHoaro <arthur@hoa.ro>
+   327  VirtualTam <virtualtam@flibidi.net>
+   187  nodiscc <nodiscc@gmail.com>
     56  Sébastien Sauvage <sebsauvage@sebsauvage.net>
     15  Florian Eula <eula.florian@gmail.com>
     13  Emilien Klein <emilien@klein.st>
@@ -9,10 +9,11 @@
      8  Christophe HENRY <christophe.henry@sbgodin.fr>
      6  B. van Berkum <dev@dotmpe.com>
      5  Lucas Cimon <lucas.cimon@gmail.com>
+     5  Mark Schmitz <kramred@gmail.com>
+     5  kalvn <kalvnthereal@gmail.com>
      4  Alexandre Alapetite <alexandre@alapetite.fr>
      4  David Sferruzza <david.sferruzza@gmail.com>
      4  Immánuel Fodor <immanuelfactor+github@gmail.com>
-     4  kalvn <kalvnthereal@gmail.com>
      3  Teromene <teromene@teromene.fr>
      2  Chris Kuethe <chris.kuethe@gmail.com>
      2  Knah Tsaeb <Knah-Tsaeb@knah-tsaeb.org>
@@ -24,11 +25,15 @@
      2  julienCXX <software@chmodplusx.eu>
      2  philipp-r <philipp-r@users.noreply.github.com>
      1  Adrien Oliva <adrien.oliva@yapbreak.fr>
+     1  Alexandre G.-Raymond <alex@ndre.gr>
      1  Alexis J <alexis@effingo.be>
+     1  Angristan <angristan@users.noreply.github.com>
      1  BoboTiG <bobotig@gmail.com>
      1  Bronco <bronco@warriordudimanche.net>
+     1  Buster One <37770318+buster-one@users.noreply.github.com>
      1  D Low <daniellowtw@gmail.com>
      1  Daniel Jakots <vigdis@chown.me>
+     1  Dennis Verspuij <dennisverspuij@users.noreply.github.com>
      1  Dimtion <zizou.xena@gmail.com>
      1  Fanch <fanch-github@qth.fr>
      1  Felix Bartels <felix@host-consultants.de>
@@ -37,6 +42,7 @@
      1  Franck Kerbiriou <FranckKe@users.noreply.github.com>
      1  Gary Marigliano <gmarigliano93@gmail.com>
      1  Guillaume Virlet <github@virlet.org>
+     1  Jonathan Amiez <jonathan.amiez@gmail.com>
      1  Jonathan Druart <jonathan.druart@gmail.com>
      1  Julien Pivotto <roidelapluie@inuits.eu>
      1  Kevin Canévet <kevin@streamroot.io>
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3218f4d8..bafbd06c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,10 +5,58 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [v0.10.0](https://github.com/shaarli/Shaarli/releases/tag/v0.10.0) - UNPUBLISHED
+**PHP 5.5 compatibility has been dropped.** Shaarli now requires at least PHP 5.6.
+
+### Added
+- Add a filter to display public links only
+- Add PHP 7.2 support
+- Add German translation
+- Resolve front-end dependencies from NPM
+- Build front-end bundles with Yarn and Webpack
+- Lint Javascript code with ESLint
+- Lint SASS code with SASSLint
+- Support redirection in cURL download callback
+- Introduce multi-stage builds for Docker images
+- Use Travis matrix and stages to run Javascript tests in a dedicated environment
+
+### Changed
+- Use a specific page title in all pages
+- Daily: run hooks before creating the columns
+- Load theme translations files automatically
+- Make max download size and timeout configurable
+- Make Nginx logs accessible as stdout/stderr for Docker images
+- Update buttons used to toggle link visibility filters
+- Rewrite Javascript code for ES6 compliance
+- Refactor IP ban management
+- Refactor user login management
+- Refactor server-side session management
+- Update Doxygen configuration
+- Update Parsedown
+
+### Removed
+- Drop support for PHP 5.5
+- Remove vendored front-end libraries
+- Remove environment specific .gitignore entries
+
+### Fixed
+- Ignore the case while checking DOCTYPE during the file import
+- Fix removal of on=... attributes from html generated from Markdown
+- httpd: always forward the 'Authorization' header
+- Ensure user-specific CSS file is loaded
+- Fix feed permalink rendering when Markdown escaping is enabled
+- Fix order of tags with the same number of occurrences
+
+### Security
+- Update `.htaccess` to prevent accessing Git metadata when using a Git-based installation
+
+
+## [v0.9.7](https://github.com/shaarli/Shaarli/releases/tag/v0.9.7) - 2018-06-20
+### Changed
+- Build the Docker images from the local Git sources
 
 
 ## [v0.9.6](https://github.com/shaarli/Shaarli/releases/tag/v0.9.6) - 2018-03-25
-## Changed
+### Changed
 - htaccess: prevent accessing resources not managed by SCM
 - htaccess: always forward the 'Authorization' HTTP header
 
@@ -222,6 +270,19 @@ Theming:
 - Markdown plugin: escape HTML entities by default
 
 
+## [v0.8.7](https://github.com/shaarli/Shaarli/releases/tag/v0.8.7) - 2018-06-20
+### Changed
+- Build the Docker image from the local Git sources
+
+### Removed
+- Disable PHP 5.3 Travis build (unsupported)
+
+
+## [v0.8.6](https://github.com/shaarli/Shaarli/releases/tag/v0.8.6) - 2018-02-19
+### Changed
+- Run version check tests against the 'stable' branch
+
+
 ## [v0.8.5](https://github.com/shaarli/Shaarli/releases/tag/v0.8.5) - 2018-01-04
 **XSS vulnerability fixed. Please update.**
 
diff --git a/docker/alpine/Dockerfile.master b/Dockerfile
index 7bbe1fb7..6261e81b 100644
--- a/docker/alpine/Dockerfile.master
+++ b/Dockerfile
@@ -1,13 +1,20 @@
 # Stage 1:
-# - Get Shaarli sources
+# - Copy Shaarli sources
+# - Build documentation
+FROM python:3-alpine as docs
+ADD . /usr/src/app/shaarli
+RUN cd /usr/src/app/shaarli \
+    && pip install --no-cache-dir mkdocs \
+    && mkdocs build --clean
+
+# Stage 2:
 # - Resolve PHP dependencies with Composer
 FROM composer:latest as composer
-RUN curl -L https://github.com/shaarli/Shaarli/archive/master.tar.gz | tar xzf - \
-    && mv Shaarli-master shaarli \
-    && cd shaarli \
+COPY --from=docs /usr/src/app/shaarli /app/shaarli
+RUN cd shaarli \
     && composer --prefer-dist --no-dev install
 
-# Stage 2:
+# Stage 3:
 # - Frontend dependencies
 FROM node:9.9-alpine as node
 COPY --from=composer /app/shaarli shaarli
@@ -16,9 +23,9 @@ RUN cd shaarli \
     && yarn run build \
     && rm -rf node_modules
 
-# Stage 3:
+# Stage 4:
 # - Shaarli image
-FROM alpine:3.6
+FROM alpine:3.7
 LABEL maintainer="Shaarli Community"
 
 RUN apk --update --no-cache add \
@@ -39,9 +46,9 @@ RUN apk --update --no-cache add \
         php7-zlib \
         s6
 
-COPY nginx.conf /etc/nginx/nginx.conf
-COPY php-fpm.conf /etc/php7/php-fpm.conf
-COPY services.d /etc/services.d
+COPY .docker/nginx.conf /etc/nginx/nginx.conf
+COPY .docker/php-fpm.conf /etc/php7/php-fpm.conf
+COPY .docker/services.d /etc/services.d
 
 RUN rm -rf /etc/php7/php-fpm.d/www.conf \
     && sed -i 's/post_max_size.*/post_max_size = 10M/' /etc/php7/php.ini \
@@ -55,6 +62,7 @@ RUN chown -R nginx:nginx . \
     && ln -sf /dev/stdout /var/log/nginx/shaarli.access.log \
     && ln -sf /dev/stderr /var/log/nginx/shaarli.error.log
 
+VOLUME /var/www/shaarli/cache
 VOLUME /var/www/shaarli/data
 
 EXPOSE 80
diff --git a/docker/alpine/Dockerfile.armhf.master b/Dockerfile.armhf
index 6c89adc3..5dcc34aa 100644
--- a/docker/alpine/Dockerfile.armhf.master
+++ b/Dockerfile.armhf
@@ -1,5 +1,5 @@
 FROM lsiobase/alpine.armhf:3.6
-MAINTAINER Shaarli Community
+LABEL maintainer="Shaarli Community"
 
 RUN apk --update --no-cache add \
         ca-certificates \
@@ -21,9 +21,9 @@ RUN apk --update --no-cache add \
         php7-zlib \
         s6
 
-COPY nginx.conf /etc/nginx/nginx.conf
-COPY php-fpm.conf /etc/php7/php-fpm.conf
-COPY services.d /etc/services.d
+COPY .docker/nginx.conf /etc/nginx/nginx.conf
+COPY .docker/php-fpm.conf /etc/php7/php-fpm.conf
+COPY .docker/services.d /etc/services.d
 
 RUN curl -sS https://getcomposer.org/installer | php7 -- --install-dir=/usr/local/bin --filename=composer \
     && rm -rf /etc/php7/php-fpm.d/www.conf \
diff --git a/Makefile b/Makefile
index 4adbdd68..b0cdadf0 100644
--- a/Makefile
+++ b/Makefile
@@ -207,7 +207,7 @@ htmldoc:
         python3 -m venv venv/
         bash -c 'source venv/bin/activate; \
         pip install mkdocs; \
-        mkdocs build'
+        mkdocs build --clean'
         find doc/html/ -type f -exec chmod a-x '{}' \;
         rm -r venv
 
diff --git a/README.md b/README.md
index df9018b6..8199e3f8 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,10 @@ _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._
 
-[![](https://img.shields.io/badge/stable-v0.8.6-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.8.6)
+[![](https://img.shields.io/badge/stable-v0.8.7-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.8.7)
 [![](https://img.shields.io/travis/shaarli/Shaarli/stable.svg?label=stable)](https://travis-ci.org/shaarli/Shaarli)
 &bull;
-[![](https://img.shields.io/badge/latest-v0.9.6-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.9.6)
+[![](https://img.shields.io/badge/latest-v0.9.7-blue.svg)](https://github.com/shaarli/Shaarli/releases/tag/v0.9.7)
 [![](https://img.shields.io/travis/shaarli/Shaarli/latest.svg?label=latest)](https://travis-ci.org/shaarli/Shaarli)
 &bull;
 [![](https://img.shields.io/badge/master-v0.10.x-blue.svg)](https://github.com/shaarli/Shaarli)
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/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index 7c570acf..49c20c9c 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -32,7 +32,8 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
 - [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
 - [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar
 - [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle
-
+- [Shaarli app for Cloudron](https://git.cloudron.io/cloudron/shaarli-app) - Effortlessly run Shaarli with the help of [Cloudron](https://cloudron.io/) [![Install](https://cloudron.io/img/button.svg)](https://cloudron.io/button.html?app=com.github.shaarli)
+- [Shaarli_ynh](https://github.com/YunoHost-Apps/shaarli_ynh) - Shaarli is available as a [Yunohost](https://yunohost.org) app [![Install Shaarli with YunoHost](https://install-app.yunohost.org/install-with-yunohost.png)](https://install-app.yunohost.org/?app=shaarli)
 
 ### Mobile Apps
 - [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension.
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index 20138f49..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,13 +22,13 @@ 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.6`
+The current latest released version is `v0.9.7`
 
 ```bash
-$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.6/shaarli-v0.9.6-full.zip
-$ unzip shaarli-v0.9.6-full.zip
+$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.7/shaarli-v0.9.7-full.zip
+$ unzip shaarli-v0.9.7-full.zip
 $ mv Shaarli /path/to/shaarli/
 ```
 
@@ -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.
 
@@ -94,7 +93,7 @@ $ composer install --no-dev --prefer-dist
 _Use at your own risk!_
 
 Install [Composer](Unit-tests.md#install_composer) to manage Shaarli PHP dependencies,
-and [yarn](https://yarnpkg.com/lang/en/docs/install/) 
+and [yarn](https://yarnpkg.com/lang/en/docs/install/)
 for front-end dependencies.
 
 To get the latest changes from the `master` branch:
diff --git a/doc/md/FAQ.md b/doc/md/FAQ.md
index 77faf117..a2ec7d57 100644
--- a/doc/md/FAQ.md
+++ b/doc/md/FAQ.md
@@ -22,7 +22,9 @@ With Shaarli:
 Shaarli stands for _shaaring_ your _links_.
 
 ### My Shaarli is broken!
-First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
+First of all, ensure that both the [web server](Server-configuration) and
+[Shaarli](Shaarli-configuration) are correctly configured, and that your
+installation is [supported](Server-configuration).
 
 If everything looks right but the issue(s) remain(s), please:
 
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
index 68a83c00..c016de56 100644
--- a/doc/md/REST-API.md
+++ b/doc/md/REST-API.md
@@ -3,8 +3,9 @@
 See the [REST API documentation](http://shaarli.github.io/api-documentation/)
 for a list of available endpoints and parameters.
 
-Please ensure that your server meets the [requirements](Server-requirements)
-and is properly [configured](Server-configuration):
+Please ensure that your server meets the
+[requirements](Server-configuration#prerequisites) and is properly
+[configured](Server-configuration):
 
 - URL rewriting is enabled (see specific Apache and Nginx sections)
 - the server's timezone is properly defined
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/Sharing-content.md b/doc/md/Sharing-content.md
index faacc1f9..4910ff6c 100644
--- a/doc/md/Sharing-content.md
+++ b/doc/md/Sharing-content.md
@@ -1,4 +1,4 @@
-Content posted to Shaarli is separated in items called _Shaares_. For each Shaare, 
+Content posted to Shaarli is separated in items called _Shaares_. For each Shaare,
 you can customize the following aspects:
 
  * URL to link to
@@ -13,10 +13,10 @@ you can customize the following aspects:
 
 While logged in to your Shaarli, you can add new Shaares in several ways:
 
- * [+Shaare button]
- * [Bookmarklet]
+ * [+Shaare button](#shaare-button)
+ * [Bookmarklet](#bookmarklet)
  * [Firefox Share](#firefox-share)
- * Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps)
+ * Third-party [apps and browser addons](Community-&-Related-software.md#mobile-apps)
  * [REST API](https://shaarli.github.io/api-documentation/)
 
 ### +Shaare button
@@ -33,14 +33,14 @@ While logged in to your Shaarli, you can add new Shaares in several ways:
 
 ### Bookmarklet
 
-The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special 
-browser bookmark you can use to add new content to your Shaarli. This bookmarklet is 
+The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special
+browser bookmark you can use to add new content to your Shaarli. This bookmarklet is
 compatible with Firefox, Opera, Chrome and Safari. To set it up:
 
  * Access the `Tools` page from the button in the toolbar.
  * Drag the **`✚Shaare link` button** to your browser's bookmarks bar.
 
-Once this is done, you can shaare any URL you are visiting simply by clicking the 
+Once this is done, you can shaare any URL you are visiting simply by clicking the
 bookmarklet in your browser! The same `New Shaare` dialog as above is displayed.
 
 | Note | Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunately, there is nothing Shaarli can do about it. \[[1](https://github.com/shaarli/Shaarli/issues/196)]\ \[[2](https://bugzilla.mozilla.org/show_bug.cgi?id=866522)]\ \[[3](https://code.google.com/p/chromium/issues/detail?id=233903)]\ |
@@ -59,8 +59,8 @@ 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)
+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. |
 |---------|---------|
@@ -74,15 +74,15 @@ _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
 
 Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button.
 
-Editing a Shaare will not change it's permalink, each permalink always points to the 
+Editing a Shaare will not change it's permalink, each permalink always points to the
 latest revision of a Shaare.
 
 --------------------------------------------------------------------------------
 
 ## Using shaarli as a blog, notepad, pastebin...
 
-While adding or editing a link, leave the URL field blank to create a text-only 
-("note") post. This allows you to post any kind of text content, such as blog 
-articles, private or public notes, snippets... There is no character limit! You can 
+While adding or editing a link, leave the URL field blank to create a text-only
+("note") post. This allows you to post any kind of text content, such as blog
+articles, private or public notes, snippets... There is no character limit! You can
 access your Shaare from its permalink.
 
diff --git a/doc/md/Unit-tests-Docker.md b/doc/md/Unit-tests-Docker.md
index c2de7cc7..59bd5b45 100644
--- a/doc/md/Unit-tests-Docker.md
+++ b/doc/md/Unit-tests-Docker.md
@@ -8,7 +8,7 @@ Read first:
 
 ### Docker test images
 
-Test Dockerfiles are located under `docker/tests/<distribution>/Dockerfile`,
+Test Dockerfiles are located under `tests/docker/<distribution>/Dockerfile`,
 and can be used to build Docker images to run Shaarli test suites under common
 Linux environments.
 
@@ -27,7 +27,7 @@ What's behind the curtains:
     - test PHP dependencies (OS packages)
     - Composer
 - the local workspace is mapped to the container's `/shaarli/` directory,
-- the files are rsync'd to so tests are run using a standard Linux user account
+- the files are rsync'd so tests are run using a standard Linux user account
   (running tests as `root` would bypass permission checks and may hide issues)
 - the tests are run inside the container.
 
@@ -36,7 +36,7 @@ What's behind the curtains:
 ```bash
 # build the Debian 9 Docker image
 $ cd /path/to/shaarli
-$ cd docker/test/debian9
+$ cd tests/docker/debian9
 $ docker build -t shaarli-test:debian9 .
 ```
 
diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md
index 12f7b5d1..5948949a 100644
--- a/doc/md/docker/shaarli-images.md
+++ b/doc/md/docker/shaarli-images.md
@@ -8,9 +8,9 @@ The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaa
 repository.
 
 ### Available image tags
-- `latest`: latest branch (tarball release)
-- `master`: master branch (tarball release)
-- `stable`: stable branch (tarball release)
+- `latest`: latest branch
+- `master`: master branch
+- `stable`: stable branch
 
 The `latest` and `master` images rely on:
 
@@ -24,11 +24,18 @@ The `stable` image relies on:
 - [PHP5-FPM](http://php-fpm.org/)
 - [Nginx](http://nginx.org/)
 
-Additional [Dockerfiles](https://github.com/shaarli/Shaarli/tree/master/docker) are provided for the `arm32v7` platform, relying on [Linuxserver.io Alpine armhf images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be built using [`docker build`](https://docs.docker.com/engine/reference/commandline/build/) on an `arm32v7` machine or using an emulator such as [qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/).
+Additional Dockerfiles are provided for the `arm32v7` platform, relying on
+[Linuxserver.io Alpine armhf
+images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be
+built using [`docker
+build`](https://docs.docker.com/engine/reference/commandline/build/) on an
+`arm32v7` machine or using an emulator such as
+[qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/).
 
-### Download from DockerHub
-```bash
+### Download from Docker Hub
+```shell
 $ docker pull shaarli/shaarli
+
 latest: Pulling from shaarli/shaarli
 32716d9fcddb: Pull complete
 84899d045435: Pull complete
@@ -46,7 +53,7 @@ Status: Downloaded newer image for shaarli/shaarli:latest
 ```
 
 ### Create and start a new container from the image
-```bash
+```shell
 # map the host's :8000 port to the container's :80 port
 $ docker create -p 8000:80 shaarli/shaarli
 d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
@@ -62,7 +69,7 @@ d40b7af693d6  shaarli/shaarli  /usr/bin/supervisor  15 seconds ago  Up 4 seconds
 ```
 
 ### Stop and destroy a container
-```bash
+```shell
 $ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!
 backstabbing_galileo
 
@@ -84,12 +91,34 @@ CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS
 ```
 
 ### Automatic builds
+Docker users can start a personal instance from an
+[autobuild image](https://hub.docker.com/r/shaarli/shaarli/).
+For example to start a temporary Shaarli at ``localhost:8000``, and keep session
+data (config, storage):
 
-Docker users can start a personal instance from an [autobuild image](https://hub.docker.com/r/shaarli/shaarli/). For example to start a temporary Shaarli at ``localhost:8000``, and keep session data (config, storage):
-```
+```shell
 MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P)
 docker run -ti --rm \
          -p 8000:80 \
          -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \
          shaarli/shaarli
 ```
+
+### Volumes and data persistence
+Data can be persisted by [using volumes](https://docs.docker.com/storage/volumes/).
+Volumes allow to keep your data when renewing and/or updating container images:
+
+```shell
+# Create data volumes
+$ docker volume create shaarli-data
+$ docker volume create shaarli-cache
+
+# Create and start a Shaarli container using these volumes to persist data
+$ docker create \
+    --name shaarli \
+    -v shaarli-cache:/var/www/shaarli/cache \
+    -v shaarli-data:/var/www/shaarli/data \
+    -p 8000:80 \
+    shaarli/shaarli:master
+$ docker start shaarli
+```
diff --git a/doc/md/index.md b/doc/md/index.md
index 224070cb..c18332b4 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,39 @@ 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).
 
diff --git a/docker/alpine/Dockerfile.armhf.latest b/docker/alpine/Dockerfile.armhf.latest
deleted file mode 100644
index 824a1926..00000000
--- a/docker/alpine/Dockerfile.armhf.latest
+++ /dev/null
@@ -1,49 +0,0 @@
-FROM lsiobase/alpine.armhf:3.6
-MAINTAINER Shaarli Community
-
-RUN apk --update --no-cache add \
-        ca-certificates \
-        curl \
-        nginx \
-        php7 \
-        php7-ctype \
-        php7-curl \
-        php7-fpm \
-        php7-gd \
-        php7-iconv \
-        php7-intl \
-        php7-json \
-        php7-mbstring \
-        php7-openssl \
-        php7-phar \
-        php7-session \
-        php7-xml \
-        php7-zlib \
-        s6
-
-COPY nginx.conf /etc/nginx/nginx.conf
-COPY php-fpm.conf /etc/php7/php-fpm.conf
-COPY services.d /etc/services.d
-
-RUN curl -sS https://getcomposer.org/installer | php7 -- --install-dir=/usr/local/bin --filename=composer \
-    && rm -rf /etc/php7/php-fpm.d/www.conf \
-    && sed -i 's/post_max_size.*/post_max_size = 10M/' /etc/php7/php.ini \
-    && sed -i 's/upload_max_filesize.*/upload_max_filesize = 10M/' /etc/php7/php.ini
-
-
-WORKDIR /var/www
-RUN curl -L https://github.com/shaarli/Shaarli/archive/latest.tar.gz | tar xzf - \
-    && mv Shaarli-latest shaarli \
-    && cd shaarli \
-    && composer --prefer-dist --no-dev install \
-    && rm -rf ~/.composer \
-    && chown -R nginx:nginx . \
-    && ln -sf /dev/stdout /var/log/nginx/shaarli.access.log \
-    && ln -sf /dev/stderr /var/log/nginx/shaarli.error.log
-
-VOLUME /var/www/shaarli/data
-
-EXPOSE 80
-
-ENTRYPOINT ["/bin/s6-svscan", "/etc/services.d"]
-CMD []
diff --git a/docker/alpine/Dockerfile.latest b/docker/alpine/Dockerfile.latest
deleted file mode 100644
index 755d8751..00000000
--- a/docker/alpine/Dockerfile.latest
+++ /dev/null
@@ -1,54 +0,0 @@
-# Stage 1:
-# - Get Shaarli sources
-# - Resolve PHP dependencies with Composer
-FROM composer:latest as composer
-RUN curl -L https://github.com/shaarli/Shaarli/archive/latest.tar.gz | tar xzf - \
-    && mv Shaarli-latest shaarli \
-    && cd shaarli \
-    && composer --prefer-dist --no-dev install
-
-# Stage 2:
-# - Shaarli image
-FROM alpine:3.6
-LABEL maintainer="Shaarli Community"
-
-RUN apk --update --no-cache add \
-        ca-certificates \
-        nginx \
-        php7 \
-        php7-ctype \
-        php7-curl \
-        php7-fpm \
-        php7-gd \
-        php7-iconv \
-        php7-intl \
-        php7-json \
-        php7-mbstring \
-        php7-openssl \
-        php7-session \
-        php7-xml \
-        php7-zlib \
-        s6
-
-COPY nginx.conf /etc/nginx/nginx.conf
-COPY php-fpm.conf /etc/php7/php-fpm.conf
-COPY services.d /etc/services.d
-
-RUN rm -rf /etc/php7/php-fpm.d/www.conf \
-    && sed -i 's/post_max_size.*/post_max_size = 10M/' /etc/php7/php.ini \
-    && sed -i 's/upload_max_filesize.*/upload_max_filesize = 10M/' /etc/php7/php.ini
-
-
-WORKDIR /var/www
-COPY --from=composer /app/shaarli shaarli
-
-RUN chown -R nginx:nginx . \
-    && ln -sf /dev/stdout /var/log/nginx/shaarli.access.log \
-    && ln -sf /dev/stderr /var/log/nginx/shaarli.error.log
-
-VOLUME /var/www/shaarli/data
-
-EXPOSE 80
-
-ENTRYPOINT ["/bin/s6-svscan", "/etc/services.d"]
-CMD []
diff --git a/docker/alpine/IMAGE.md b/docker/alpine/IMAGE.md
deleted file mode 100644
index a8952257..00000000
--- a/docker/alpine/IMAGE.md
+++ /dev/null
@@ -1,10 +0,0 @@
-## Alpine images
-- [Alpine Linux](https://www.alpinelinux.org/)
-- [PHP-FPM](http://php-fpm.org/)
-- [Nginx](http://nginx.org/)
-
-### `shaarli/shaarli:latest`
-- [Shaarli](https://github.com/shaarli/Shaarli), `latest` branch
-
-### `shaarli/shaarli:master`
-- [Shaarli](https://github.com/shaarli/Shaarli), `master` branch
diff --git a/docker/debian/Dockerfile.stable b/docker/debian/Dockerfile.stable
deleted file mode 100644
index fc9588b0..00000000
--- a/docker/debian/Dockerfile.stable
+++ /dev/null
@@ -1,37 +0,0 @@
-FROM debian:jessie
-MAINTAINER Shaarli Community
-
-ENV TERM dumb
-RUN apt-get update \
-    && apt-get install --no-install-recommends -y \
-       ca-certificates \
-       curl \
-       nginx-light \
-       php5-curl \
-       php5-fpm \
-       php5-gd \
-       php5-intl \
-       supervisor \
-    && apt-get clean
-
-RUN sed -i 's/post_max_size.*/post_max_size = 10M/' /etc/php5/fpm/php.ini
-RUN sed -i 's/upload_max_filesize.*/upload_max_filesize = 10M/' /etc/php5/fpm/php.ini
-COPY nginx.conf /etc/nginx/nginx.conf
-COPY supervised.conf /etc/supervisor/conf.d/supervised.conf
-
-ADD https://getcomposer.org/composer.phar /usr/local/bin/composer
-RUN chmod 755 /usr/local/bin/composer
-
-WORKDIR /var/www
-RUN curl -L https://github.com/shaarli/Shaarli/archive/stable.tar.gz | tar xzf - \
-    && mv Shaarli-stable shaarli \
-    && cd shaarli \
-    && composer --prefer-dist --no-dev install
-RUN rm -rf html \
-    && chown -R www-data:www-data .
-
-VOLUME /var/www/shaarli/data
-
-EXPOSE 80
-
-CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/supervisord.conf"]
diff --git a/docker/debian/IMAGE.md b/docker/debian/IMAGE.md
deleted file mode 100644
index d85b1d7a..00000000
--- a/docker/debian/IMAGE.md
+++ /dev/null
@@ -1,5 +0,0 @@
-## shaarli:stable
-- [Debian 8 Jessie](https://hub.docker.com/_/debian/)
-- [PHP5-FPM](http://php-fpm.org/)
-- [Nginx](http://nginx.org/)
-- [Shaarli (stable)](https://github.com/shaarli/Shaarli/tree/stable)
diff --git a/docker/debian/nginx.conf b/docker/debian/nginx.conf
deleted file mode 100644
index e8754d9b..00000000
--- a/docker/debian/nginx.conf
+++ /dev/null
@@ -1,72 +0,0 @@
-user www-data www-data;
-daemon off;
-worker_processes 4;
-
-events {
-    worker_connections  768;
-}
-
-http {
-    include            mime.types;
-    default_type       application/octet-stream;
-    keepalive_timeout  20;
-
-    client_max_body_size 10m;
-
-    index index.html index.php;
-
-    server {
-        listen       80;
-        root         /var/www/shaarli;
-
-        access_log  /var/log/nginx/shaarli.access.log;
-        error_log   /var/log/nginx/shaarli.error.log;
-
-        location ~ /\. {
-            # deny access to dotfiles
-            access_log off;
-            log_not_found off;
-            deny all;
-        }
-        
-        location ~ ~$ {
-            # deny access to temp editor files, e.g. "script.php~"
-            access_log off;
-            log_not_found off;
-            deny all;
-        }
-
-        location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
-            # cache static assets
-            expires    max;
-            add_header Pragma public;
-            add_header Cache-Control "public, must-revalidate, proxy-revalidate";
-        }
-
-        location = /favicon.ico {
-            # serve the Shaarli favicon from its custom location
-            alias /var/www/shaarli/images/favicon.ico;
-        }
-
-        location / {
-            # Slim - rewrite URLs
-            try_files $uri /index.php$is_args$args;
-        }
-
-        location ~ (index)\.php$ {
-            # Slim - split URL path into (script_filename, path_info)
-            try_files $uri =404;
-            fastcgi_split_path_info ^(.+\.php)(/.+)$;
-
-            # filter and proxy PHP requests to PHP-FPM
-            fastcgi_pass   unix:/var/run/php5-fpm.sock;
-            fastcgi_index  index.php;
-            include        fastcgi.conf;
-        }
-
-        location ~ \.php$ {
-            # deny access to all other PHP scripts
-            deny all;
-        }
-    }
-}
diff --git a/docker/debian/supervised.conf b/docker/debian/supervised.conf
deleted file mode 100644
index 5acd9795..00000000
--- a/docker/debian/supervised.conf
+++ /dev/null
@@ -1,13 +0,0 @@
-[program:php5-fpm]
-command=/usr/sbin/php5-fpm -F
-priority=5
-autostart=true
-autorestart=true
-
-[program:nginx]
-command=/usr/sbin/nginx
-priority=10
-autostart=true
-autorestart=true
-stdout_events_enabled=true
-stderr_events_enabled=true
diff --git a/index.php b/index.php
index 6dcec9b2..29d67f62 100644
--- a/index.php
+++ b/index.php
@@ -48,7 +48,7 @@ if (! file_exists(__DIR__ . '/vendor/autoload.php')) {
         ."If you installed Shaarli through Git or using the development branch,\n"
         ."please refer to the installation documentation to install PHP"
         ." dependencies using Composer:\n"
-        ."- https://shaarli.readthedocs.io/en/master/Server-requirements/\n"
+        ."- https://shaarli.readthedocs.io/en/master/Server-configuration/\n"
         ."- https://shaarli.readthedocs.io/en/master/Download-and-Installation/";
     exit;
 }
@@ -174,7 +174,7 @@ if (! is_file($conf->getConfigFileExt())) {
     }
 
     // Display the installation form if no existing config is found
-    install($conf, $sessionManager);
+    install($conf, $sessionManager, $loginManager);
 }
 
 $loginManager->checkLoginState($_COOKIE, $clientIpId);
@@ -1823,8 +1823,9 @@ function lazyThumbnail($conf, $url,$href=false)
  *
  * @param ConfigManager  $conf           Configuration Manager instance.
  * @param SessionManager $sessionManager SessionManager instance
+ * @param LoginManager   $loginManager   LoginManager instance
  */
-function install($conf, $sessionManager) {
+function install($conf, $sessionManager, $loginManager) {
     // On free.fr host, make sure the /sessions directory exists, otherwise login will not work.
     if (endsWith($_SERVER['HTTP_HOST'],'.free.fr') && !is_dir($_SERVER['DOCUMENT_ROOT'].'/sessions')) mkdir($_SERVER['DOCUMENT_ROOT'].'/sessions',0705);
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 8ba25540..a1226e8f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,13 +5,13 @@ site_description: The personal, minimalist, super-fast, database free, bookmarki
 theme: readthedocs
 docs_dir: doc/md
 site_dir: doc/html
+strict: true
 
 pages:
 - Home: index.md
 - Setup:
     - Download and Installation: Download-and-Installation.md
     - Upgrade and migration: Upgrade-and-migration.md
-    - Server requirements: Server-requirements.md
     - Server configuration: Server-configuration.md
     - Server security: Server-security.md
     - Shaarli configuration: Shaarli-configuration.md
@@ -24,7 +24,7 @@ pages:
 - Usage:
     - Browsing and searching: Browsing-and-searching.md
     - Sharing content: Sharing-content.md
-    - RSS feeds: RSS-feeds.md 
+    - RSS feeds: RSS-feeds.md
     - REST API: REST-API.md
     - Community & Related software: Community-&-Related-software.md
 - How To:
diff --git a/docker/test/alpine36/Dockerfile b/tests/docker/alpine36/Dockerfile
index fa84f6e2..fa84f6e2 100644
--- a/docker/test/alpine36/Dockerfile
+++ b/tests/docker/alpine36/Dockerfile
diff --git a/docker/test/debian8/Dockerfile b/tests/docker/debian8/Dockerfile
index eaa34e9b..eaa34e9b 100644
--- a/docker/test/debian8/Dockerfile
+++ b/tests/docker/debian8/Dockerfile
diff --git a/docker/test/debian9/Dockerfile b/tests/docker/debian9/Dockerfile
index 3ab4b93d..3ab4b93d 100644
--- a/docker/test/debian9/Dockerfile
+++ b/tests/docker/debian9/Dockerfile
diff --git a/docker/test/ubuntu16/Dockerfile b/tests/docker/ubuntu16/Dockerfile
index e53ed9e3..e53ed9e3 100644
--- a/docker/test/ubuntu16/Dockerfile
+++ b/tests/docker/ubuntu16/Dockerfile
diff --git a/tpl/default/includes.html b/tpl/default/includes.html
index 34e0ff01..5ccacaaf 100644
--- a/tpl/default/includes.html
+++ b/tpl/default/includes.html
@@ -2,6 +2,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="format-detection" content="telephone=no" />
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="same-origin">
 <link rel="alternate" type="application/atom+xml" href="{$feedurl}?do=atom{$searchcrits}#" title="ATOM Feed" />
 <link rel="alternate" type="application/rss+xml" href="{$feedurl}?do=rss{$searchcrits}#" title="RSS Feed" />
 <link href="img/favicon.png" rel="shortcut icon" type="image/png" />