14 files changed, 406 insertions, 45 deletions

diff --git a/doc/md/Browsing-and-searching.md b/doc/md/Browsing-and-searching.md
index 24483139..f948bbe1 100644
--- a/doc/md/Browsing-and-searching.md
+++ b/doc/md/Browsing-and-searching.md
@@ -25,7 +25,7 @@ The `Tag cloud` page diplays a "cloud" view of all tags in your Shaarli.
 
 ## Filtering RSS feeds/Picture wall
 
-RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS feeds).
+RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS-feeds).
 
 ## Filter buttons
 
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index 8edbeefa..3c55e935 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -34,6 +34,7 @@ See [REST API](REST-API) for a list of official and community clients.
 - [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
 - [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
 - [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.
 
 
 ### Third-party themes
@@ -47,10 +48,12 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
 
 
 ### Mobile Apps
-- [ShaarliOS](https://github.com/mro/ShaarliOS) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes,
+- [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension.
 - [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
 - [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
 
+### Browser addons
+ * [Shaarli Web Extension](https://github.com/ikipatang/shaarli-web-extension) - toolbar button to share your current tab with Shaarli.
 
 ### Server apps
 - [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
@@ -61,7 +64,5 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
 - [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).
 - [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
-See the [bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing)
-section on [awesome-selfhosted](https://github.com/Kickball/awesome-selfhosted/).
+See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing).
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index e5e929ef..bbbfc26d 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -4,44 +4,57 @@ 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).
 
-Several releases are available:
+Multiple releases branches are available:
+
+- latest (last release)
+- stable (previous major release)
+- master (development)
+
+Using one of the following methods:
 
 - by downloading full release archives including all dependencies
 - by downloading Github archives
 - by cloning the Git repository
+- using Docker: [see the documentation](docker/shaarli-images.md)
 
----
+--------------------------------------------------------------------------------
 
 ## Latest release (recommended)
+
 ### Download as an archive
-Get the latest released version 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.1`
 
-Or in command lines:
-
 ```bash
 $ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.1/shaarli-v0.9.1-full.zip
 $ unzip shaarli-v0.9.1-full.zip
 $ mv Shaarli /path/to/shaarli/
 ```
 
-In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
-
 ### Using git
 
+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 [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation.
+
 ```
 $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
-$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
+$ git clone -b latest https://github.com/shaarli/Shaarli.git .
 $ composer install --no-dev --prefer-dist
+$ make translate
+$ make htmldoc
 ```
 
+--------------------------------------------------------------------------------
+
 ## Stable version
 
 The stable version has been experienced by Shaarli users, and will receive security updates.
 
+
 ### Download as an archive
 
 As a .zip archive:
@@ -60,9 +73,9 @@ $ tar xvf stable.tar.gz
 $ mv Shaarli-stable /path/to/shaarli/
 ```
 
-### Clone with Git 
+### Using git
 
-[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.
+Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
 
 ```bash
 $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
@@ -71,10 +84,15 @@ $ cd /path/to/shaarli/
 $ composer install --no-dev --prefer-dist
 ```
 
+
+--------------------------------------------------------------------------------
+
 ## Development version (mainline)
 
 _Use at your own risk!_
 
+Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
+
 To get the latest changes from the `master` branch:
 
 ```bash
@@ -83,13 +101,17 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
 # install/update third-party dependencies
 $ cd /path/to/shaarli
 $ composer install --no-dev --prefer-dist
+$ make translate
+$ make htmldoc
 ```
 
+-------------------------------------------------------------------------------
+
 ## Finish Installation
 
 Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
 
-![install screenshot](http://i.imgur.com/wuMpDSN.png)
+![install screenshot](images/install-shaarli.png)
 
 Setup your Shaarli installation, and it's ready to use!
 
diff --git a/doc/md/Firefox-share.md b/doc/md/Firefox-share.md
index 878884a4..9a46b185 100644
--- a/doc/md/Firefox-share.md
+++ b/doc/md/Firefox-share.md
@@ -1,3 +1,6 @@
+| Note | Firefox Share is no longer available for Firefox 57 and later versions. |
+|---------|---------|
+
 ### Add Shaarli as a sharing service to Firefox
 
 - Open your Shaarli and `Login`
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
index 707af762..400b85a9 100644
--- a/doc/md/Server-requirements.md
+++ b/doc/md/Server-requirements.md
@@ -39,3 +39,4 @@ Extension | Required? | Usage
 [`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/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
index 99b25ba7..920c7e27 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -81,6 +81,20 @@ _These settings should not be edited_
 - **page_cache**: Shaarli's internal cache directory.  
 - **ban_file**: Banned IP file path.
 
+### Translation
+
+- **language**: translation language (also see [Translations](Translations))
+    - **auto** (default): The translation language is chosen from the browser locale. 
+    It means that the language can be different for 2 different visitors depending on their locale.  
+    - **en**: Use the English translation.
+    - **fr**: Use the French translation.
+- **mode**: 
+    - **auto** or **php** (default): Use the PHP implementation of gettext (slower)
+    - **gettext**: Use PHP builtin gettext extension 
+    (faster, but requires `php-gettext` to be installed and to reload the web server on update)
+- **extension**: Translation extensions for custom themes or plugins. 
+Must be an associative array: `translation domain => translation path`.
+
 ### Updates
 
 - **check_updates**: Enable or disable update check to the git repository.  
@@ -211,6 +225,13 @@ _These settings should not be edited_
     "plugins": {
         "WALLABAG_URL": "http://demo.wallabag.org",
         "WALLABAG_VERSION": "1"
+    },
+    "translation": {
+        "language": "fr",
+        "mode": "php",
+        "extensions": {
+            "demo": "plugins/demo_plugin/languages/"
+        }
     }
 } ?>
 ```
diff --git a/doc/md/Translations.md b/doc/md/Translations.md
new file mode 100644
index 00000000..54a36655
--- /dev/null
+++ b/doc/md/Translations.md
@@ -0,0 +1,152 @@
+## Translations
+
+Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
+since `>= v0.9.2`.
+
+Note that only the `default` theme supports translations.
+
+### Contributing
+
+We encourage the community to contribute to Shaarli's translation either by improving existing 
+translations or submitting a new language. 
+
+Contributing to the translation does not require development skill.
+
+Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`)
+is not stored on the repository, and is generated during the release process.
+
+### How to
+
+First, install [Poedit](https://poedit.net/) tool.
+
+Poedit will extract strings to translate from the PHP source code.
+
+**Important**: due to the usage of a template engine, it's important to generate PHP cache files to extract 
+every translatable string. 
+
+You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07)  (recommended)
+or visit every template page in your browser to generate cache files, while logged in.
+
+Here is a list :
+
+```
+http://<replace_domain>/
+http://<replace_domain>/?nonope
+http://<replace_domain>/?do=addlink
+http://<replace_domain>/?do=changepasswd
+http://<replace_domain>/?do=changetag
+http://<replace_domain>/?do=configure
+http://<replace_domain>/?do=tools
+http://<replace_domain>/?do=daily
+http://<replace_domain>/?post
+http://<replace_domain>/?do=export
+http://<replace_domain>/?do=import
+http://<replace_domain>/?do=login
+http://<replace_domain>/?do=picwall
+http://<replace_domain>/?do=pluginadmin
+http://<replace_domain>/?do=tagcloud
+http://<replace_domain>/?do=taglist
+```
+
+#### Improve existing translation
+
+In Poedit, click on "Edit a Translation", and from Shaarli's directory open 
+`inc/languages/<lang>/LC_MESSAGES/shaarli.po`. 
+
+The existing list of translatable strings should have been loaded, then click on the "Update" button.
+
+You can start editing the translation.
+
+![poedit-screenshot](images/poedit-1.jpg)
+
+Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
+
+#### Add a new language
+
+Open Poedit and select "Create New Translation", then from Shaarli's directory open 
+`inc/languages/<lang>/LC_MESSAGES/shaarli.po`.
+
+Then select the language you want to create. 
+
+Click on `File > Save as...`, and save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po`.  
+`<new language>` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) 
+format in lowercase (e.g. `de` for German).
+
+Then click on the "Update" button, and you can start to translate every available string.
+
+Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
+
+### Extend Shaarli's translation
+
+If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
+but you won't be able to able to override Shaarli's translation.
+
+However, you can add your own translation domain which extends the main translation list.
+
+> Note that you can find a live example of translation extension in the `demo_plugin`.
+
+First, create your translation files tree directory:
+
+```
+<your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
+```
+
+Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be
+`my_theme.po`.
+
+Users have to register your extension in their configuration with the parameter 
+`translation.extensions.<domain>: <translation files path>`.
+
+Example:
+
+```php
+if (! $conf->exists('translation.extensions.my_theme')) {
+    $conf->set('translation.extensions.my_theme', '<your_module>/languages/');
+    $conf->write(true);
+}
+```
+
+> Note that the page needs to be reloaded after the registration.
+
+It is then recommended to create a custom translation function which will call the `t()` function with your domain.
+For example :
+
+```php
+function my_theme_t($text, $nText = '', $nb = 1)
+{
+    return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain.
+}
+```
+
+All strings which can be translated should be processed through your function:
+
+```php
+my_theme_t('Comment');
+my_theme_t('Comment', 'Comments', 2);
+```
+
+Or in templates:
+
+```php
+{'Comment'|my_theme_t}
+{function="my_theme_t('Comment', 'Comments', 2)"}
+```
+
+> Note than in template, you need to visit your page at least once to generate a cache file.
+
+When you're done, open Poedit and load translation strings from sources:
+
+  1. `File > New`
+  2. Choose your language
+  3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`.
+  4. Go to `Catalog > Properties...` 
+  5. Fill the `Translation Properties` tab
+  6. Add your source path in the `Sources Paths` tab
+  7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines:
+  
+```
+my_theme_t
+my_theme_t:1,2
+```
+
+Click on the "Update" button and you're free to start your translations!
diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
index d200634f..f6030d5c 100644
--- a/doc/md/Unit-tests.md
+++ b/doc/md/Unit-tests.md
@@ -2,12 +2,12 @@
 
 The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
 
-Regarding Composer, you can either use:
+### Install composer
 
-- a system-wide version, e.g. installed through your distro's package manager
-- a local version, downloadable [here](https://getcomposer.org/download/)
+You can either use:
 
-#### Sample usage
+- a system-wide version, e.g. installed through your distro's package manager
+- a local version, downloadable [here](https://getcomposer.org/download/).
 
 ```bash
 # system-wide version
@@ -29,6 +29,8 @@ $ composer update
 
 #### Install and enable Xdebug to generate PHPUnit coverage reports
 
+See http://xdebug.org/docs/install
+
 For Debian-based distros:
 ```bash
 $ aptitude install php5-xdebug
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index 7033cd41..1dc07339 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -39,7 +39,10 @@ We recommend that you use the latest release tarball with the `-full` suffix. It
 
 Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
 
-After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration) for more details).
+If you use translations in gettext mode - meaning you manually changed the default mode -, 
+reload your web server.
+
+After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details).
 
 ## Upgrading with Git
 
@@ -72,6 +75,14 @@ Updating dependencies
     Downloading: 100%
 ```
 
+Shaarli >= `v0.9.2` supports translations:
+
+```bash
+$ make translate
+```
+
+If you use translations in gettext mode, reload your web server.
+
 ### Migrating and upgrading from Sebsauvage's repository
 
 If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
@@ -151,6 +162,14 @@ Updating dependencies
     Downloading: 100%
 ```
 
+Shaarli >= `v0.9.2` supports translations:
+
+```bash
+$ make translate
+```
+
+If you use translations in gettext mode, reload your web server.
+
 Optionally, you can delete information related to the legacy version:
 
 ```bash
diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md
index 91ffecff..6066140e 100644
--- a/doc/md/docker/reverse-proxy-configuration.md
+++ b/doc/md/docker/reverse-proxy-configuration.md
@@ -1,6 +1,120 @@
+## Foreword
+
+This guide assumes that:
+
+- Shaarli runs in a Docker container
+- The host's `10080` port is mapped to the container's `80` port
+- Shaarli's Fully Qualified Domain Name (FQDN) is `shaarli.domain.tld`
+- HTTP traffic is redirected to HTTPS
+
+## Apache
+
+- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
+    - [mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
+    - [Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
+
+The following HTTP headers are set by using the `ProxyPass` directive:
+
+- `X-Forwarded-For`
+- `X-Forwarded-Host`
+- `X-Forwarded-Server`
+
+```apache
+<VirtualHost *:80>
+    ServerName shaarli.domain.tld
+    Redirect permanent / https://shaarli.domain.tld
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerName shaarli.domain.tld
+
+    SSLEngine on
+    SSLCertificateFile    /path/to/cert
+    SSLCertificateKeyFile /path/to/certkey
+
+    LogLevel warn
+    ErrorLog  /var/log/apache2/shaarli-error.log
+    CustomLog /var/log/apache2/shaarli-access.log combined
+
+    RequestHeader set X-Forwarded-Proto "https"
+
+    ProxyPass        / http://127.0.0.1:10080/
+    ProxyPassReverse / http://127.0.0.1:10080/
+</VirtualHost>
+```
 
-TODO, see https://github.com/shaarli/Shaarli/issues/888
 
 ## HAProxy
 
+- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/)
+
+```conf
+global
+    [...]
+
+defaults
+    [...]
+
+frontend http-in
+    bind :80
+        redirect scheme https code 301 if !{ ssl_fc }
+
+        bind :443 ssl crt /path/to/cert.pem
+
+        default_backend shaarli
+
+
+backend shaarli
+    mode http
+    option http-server-close
+    option forwardfor
+    reqadd X-Forwarded-Proto: https
+
+    server shaarli1 127.0.0.1:10080
+```
+
+
 ## Nginx
+
+- [Nginx documentation](https://nginx.org/en/docs/)
+
+```nginx
+http {
+    [...]
+
+    index index.html index.php;
+
+    root        /home/john/web;
+    access_log  /var/log/nginx/access.log;
+    error_log   /var/log/nginx/error.log;
+
+        server {
+                listen       80;
+                server_name  shaarli.domain.tld;
+                return       301 https://shaarli.domain.tld$request_uri;
+        }
+
+        server {
+                listen       443 ssl http2;
+                server_name  shaarli.domain.tld;
+
+        ssl_certificate       /path/to/cert
+        ssl_certificate_key   /path/to/certkey
+
+                location / {
+                        proxy_set_header  X-Real-IP         $remote_addr;
+                        proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
+                        proxy_set_header  X-Forwarded-Proto $scheme;
+                        proxy_set_header  X-Forwarded-Host  $host;
+
+                        proxy_pass             http://localhost:10080/;
+                        proxy_set_header Host  $host;
+                        proxy_connect_timeout  30s;
+                        proxy_read_timeout     120s;
+
+                        access_log      /var/log/nginx/shaarli.access.log;
+                        error_log       /var/log/nginx/shaarli.error.log;
+                }
+        }
+}
+```
diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md
index 6d108d21..5491ee76 100644
--- a/doc/md/docker/shaarli-images.md
+++ b/doc/md/docker/shaarli-images.md
@@ -1,3 +1,6 @@
+A brief guide on getting starting using docker is given in [Docker 101](docker-101.md).
+To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](../Upgrade-and-migration.md).
+
 ## Get and run a Shaarli image
 
 ### DockerHub repository
@@ -5,14 +8,23 @@ The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaa
 repository.
 
 ### Available image tags
-- `latest`: master branch (tarball release)
+- `latest`: latest branch (tarball release)
+- `master`: master branch (tarball release)
 - `stable`: stable branch (tarball release)
 
-All images rely on:
+The `latest` and `master` images rely on:
+
+- [Alpine Linux](https://www.alpinelinux.org/)
+- [PHP7-FPM](http://php-fpm.org/)
+- [Nginx](http://nginx.org/)
+
+The `stable` image relies on:
+
 - [Debian 8 Jessie](https://hub.docker.com/_/debian/)
 - [PHP5-FPM](http://php-fpm.org/)
 - [Nginx](http://nginx.org/)
 
+
 ### Download from DockerHub
 ```bash
 $ docker pull shaarli/shaarli
@@ -69,3 +81,14 @@ backstabbing_galileo
 $ docker ps -a
 CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
 ```
+
+### 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):
+```
+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
+```
diff --git a/doc/md/images/install-shaarli.png b/doc/md/images/install-shaarli.png
new file mode 100644
index 00000000..7ae33816
--- /dev/null
+++ b/doc/md/images/install-shaarli.png
diff --git a/doc/md/images/poedit-1.jpg b/doc/md/images/poedit-1.jpg
new file mode 100644
index 00000000..673ae6d6
--- /dev/null
+++ b/doc/md/images/poedit-1.jpg
diff --git a/doc/md/index.md b/doc/md/index.md
index 2b7d0f00..e77b4d3a 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -22,20 +22,25 @@ It runs the latest development version of Shaarli and is updated/reset daily.
 
 Login: `demo`; Password: `demo`
 
-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):
-```
-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
-```
-
-A brief guide on getting starting using docker is given in [Docker 101](docker/docker-101).
-To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](Upgrade-and-migration) documentation.
-
 ## 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 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 ...).
+
 ### Interface
 - minimalist design (simple is beautiful)
 - FAST
@@ -89,14 +94,12 @@ Easily extensible by any client using the REST API exposed by Shaarli.
 
 See the [API documentation](http://shaarli.github.io/api-documentation/).
 
-### Other usages
-Though Shaarli is primarily a bookmarking application, it can serve other purposes
-(see [Features](Features)):
-
-- micro-blogging
-- pastebin
-- online notepad
-- snippet archive
+### Using Shaarli as a blog, notepad, pastebin...
+- Go to your Shaarli setup and log in
+- Click the `Add Link` button
+- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
+- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
+- Voilà!  Your article is now published (privately if you selected that option) and accessible using its permalink.
 
 ## About
 ### Shaarli community fork