18 files changed, 537 insertions, 88 deletions

diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/Backup,-restore,-import-and-export.md
index 89724857..bb790074 100644
--- a/doc/md/Backup,-restore,-import-and-export.md
+++ b/doc/md/Backup,-restore,-import-and-export.md
@@ -45,6 +45,10 @@ Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/s
 However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
 tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
 
+### Refind
+
+You can use the third-party tool [Derefind](https://github.com/ShawnPConroy/Derefind) to convert refind.com bookmark exports to a format that can be imported into Shaarli.
+
 ## Import Shaarli links to Firefox
 
 - Export your Shaarli links as described above.
diff --git a/doc/md/Bookmarklet.md b/doc/md/Bookmarklet.md
index e53e3261..c899e3cf 100644
--- a/doc/md/Bookmarklet.md
+++ b/doc/md/Bookmarklet.md
@@ -21,7 +21,7 @@ _This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. U
 
 Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
 
-See [#196](https://github.com/shaarli/Shaarli#196).
+See [#196](https://github.com/shaarli/Shaarli/issues/196).
 
 There is an open bug for both Firefox and Chromium:
 
diff --git a/doc/md/Browsing-and-searching.md b/doc/md/Browsing-and-searching.md
index 35707482..16c69855 100644
--- a/doc/md/Browsing-and-searching.md
+++ b/doc/md/Browsing-and-searching.md
@@ -14,10 +14,24 @@ Use the `Filter by tags` field to restrict displayed links to entries tagged wit
 
 **Hidden tags:** Tags starting with a dot `.` (example `.secret`) are private. They can only be seen and searched when logged in.
 
-Alternatively you can use the `Tag cloud` to discover all tags and click on any of them to display related links.
+### Tag cloud
 
-To search for links that are not tagged, enter `""` in the tag search field.
+The `Tag cloud` page diplays a "cloud" view of all tags in your Shaarli.
+
+ * The most frequently used tags are displayed with a bigger font size.
+ * When sorting by `Most used` or `Alphabetical`, tags are displayed as a _list_, along with counters and edit/delete buttons for each tag.
+ * Clicking on any tag will display a list of all Shaares matching this tag.
+ * Clicking on the counter next to a tag `example`, will filter the tag cloud to only display tags found in Shaares tagged `example`. Repeat this any number of times to further filter the tag cloud. Click `List all links with those tags` to display Shaares matching your current tag filter.
 
 ## 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
+
+Filter buttons can be found at the top left of the link list. They allow you to apply different filters to the list:
+
+ * **Private links:** When this toggle button is enabled, only shaares set to `private` will be shown.
+ * **Untagged links:** When the this toggle button is enabled (top left of the link list), only shaares _without any tags_ will be shown in the link list.
+ 
+Filter buttons are only available when logged in.
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index 8edbeefa..207153b6 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -1,23 +1,7 @@
 _Unofficial but related work on Shaarli. If you maintain one of these,
 please get in touch with us to help us find a way to adapt your work to our fork._
 
-## Community
-- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
-- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
-- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
-- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
-- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
-- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
-- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
-- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
-- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
-
-
-### Articles and social media discussions
-- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176
-- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)
-- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366
-- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)
+## Related software
 
 
 ### REST API clients
@@ -29,28 +13,34 @@ See [REST API](REST-API) for a list of official and community clients.
 - [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
 - [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
 - [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
+- [twemoji](https://github.com/NerosTie/twemoji) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli (Twemoji version) 
 - [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
 - [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
+- [markdown-toolbar](https://github.com/immanuelfodor/shaarli-markdown-toolbar) by [@immanuelfodor](https://github.com/immanuelfodor) - Easily insert markdown syntax into the Description field when editing a link.
 - [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.
+- [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.
 
 
 ### Third-party themes
 See [Theming](Theming) for a list of community-contributed themes, and an installation guide.
 
 
-## Integration with other platforms 
+### Integration with other platforms 
 - [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
 
 
 ### 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 +51,22 @@ 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).
+
+## Community
+- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
+- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
+- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
+- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
+- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
+- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
+- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
+- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
+- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
+
+### Articles and social media discussions
+- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176
+- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)
+- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366
+- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index e5e929ef..0fdbd27d 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.
+### Download as an archive
 
-The current latest released version is `v0.9.1`
+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.
 
-Or in command lines:
+The current latest released version is `v0.9.3`
 
 ```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
+$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.3/shaarli-v0.9.3-full.zip
+$ unzip shaarli-v0.9.3-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,25 +84,34 @@ $ 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
-# clone the repository  
+# clone the repository
 $ 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/Features.md b/doc/md/Features.md
deleted file mode 100644
index eef88d03..00000000
--- a/doc/md/Features.md
+++ /dev/null
@@ -1,25 +0,0 @@
-### Main features
-Shaarli is intended:
-
-- 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/ideas
-- to keep code snippets
-- to keep notes and documentation
-- as a shared clipboard 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 ...)
-
-### 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.
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..2dc442df 100644
--- a/doc/md/Server-requirements.md
+++ b/doc/md/Server-requirements.md
@@ -35,7 +35,8 @@ Library | Required? | Usage
 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 | multibyte (Unicode) string support
+[`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/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
index 37486414..920c7e27 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -55,6 +55,7 @@ _These settings should not be edited_
 - **links_per_page**: Number of shaares displayed per page.  
 - **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).  
 - **enabled_plugins**: List of enabled plugins.
+- **default_note_title**: Default title of a new note.
 
 ### Security
 
@@ -80,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.  
@@ -210,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 b3a08764..1dc07339 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -14,7 +14,7 @@ Shaarli stores all user data under the `data` directory:
 - `data/ipbans.php` - banned IP addresses
 - `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
 
-See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
+See [Shaarli configuration](Shaarli-configuration) for more information about Shaarli resources.
 
 It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
 
@@ -27,7 +27,7 @@ As all user data is kept under `data`, this is the only directory you need to wo
 
 - backup the `data` directory
 - install or update Shaarli:
-    - fresh installation - see [Download and installation](Download and installation)
+    - fresh installation - see [Download and installation](Download-and-installation)
     - update - see the following sections
 - check or restore the `data` directory
 
@@ -35,10 +35,13 @@ As all user data is kept under `data`, this is the only directory you need to wo
 
 All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
 
-We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download and installation) for `git` complete instructions.
+We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation) for `git` complete instructions.
 
 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!
 
+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
@@ -173,7 +192,7 @@ Total 3317 (delta 2050), reused 3301 (delta 2034)to
 
 #### Step 3: configuration
 
-After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli configuration) for more details).
+After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration) for more details).
 
 ## Troubleshooting
 
diff --git a/doc/md/docker/docker-101.md b/doc/md/docker/docker-101.md
index b02dd149..a9c00b85 100644
--- a/doc/md/docker/docker-101.md
+++ b/doc/md/docker/docker-101.md
@@ -60,3 +60,81 @@ wheezy: Pulling from debian
 Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
 Status: Downloaded newer image for debian:wheezy
 ```
+
+Docker re-uses layers already downloaded. In other words if you have images based on Alpine or some Ubuntu version for example, those can share disk space.
+
+### Start a container
+A container is an instance created from an image, that can be run and that keeps running until its main process exits. Or until the user stops the container. 
+
+The simplest way to start a container from image is ``docker run``. It also pulls the image for you if it is not locally available. For more advanced use, refer to ``docker create``.
+
+Stopped containers are not destroyed, unless you specify ``--rm``. To view all created, running and stopped containers, enter:
+```bash
+$ docker ps -a
+```
+
+Some containers may be designed or configured to be restarted, others are not. Also remember both network ports and volumes of a container are created on start, and not editable later.
+
+### Access a running container
+A running container is accessible using ``docker exec``, or ``docker copy``. You can use ``exec`` to start a root shell in the Shaarli container:
+```bash
+$ docker exec -ti <container-name-or-id> bash
+```
+Note the names and ID's of containers are listed in ``docker ps``. You can even type only one or two letters of the ID, given they are unique.
+
+Access can also be through one or more network ports, or disk volumes. Both are specified on and fixed on ``docker create`` or ``run``.
+
+You can view the console output of the main container process too:
+```bash
+$ docker logs -f <container-name-or-id>
+```
+
+### Docker disk use
+Trying out different images can fill some gigabytes of disk quickly. Besides images, the docker volumes usually take up most disk space.
+
+If you care only about trying out docker and not about what is running or saved, the following commands should help you out quickly if you run low on disk space:
+
+```bash
+$ docker rmi -f $(docker images -aq) # remove or mark all images for disposal
+$ docker volume rm $(docker volume ls -q) # remove all volumes
+```
+
+### Systemd config
+Systemd is the process manager of choice on Debian-based distributions. Once you have a ``docker`` service installed, you can use the following steps to set up Shaarli to run on system start.
+
+```bash
+systemctl enable /etc/systemd/system/docker.shaarli.service
+systemctl start docker.shaarli
+systemctl status docker.*
+journalctl -f # inspect system log if needed
+```
+
+You will need sudo or a root terminal to perform some or all of the steps above. Here are the contents for the service file:
+```
+[Unit]
+Description=Shaarli Bookmark Manager Container
+After=docker.service
+Requires=docker.service
+
+
+[Service]
+Restart=always
+
+# Put any environment you want in an included file, like $host- or $domainname in this example
+EnvironmentFile=/etc/sysconfig/box-environment
+
+# It's just an example..
+ExecStart=/usr/bin/docker run \
+  -p 28010:80 \
+  --name ${hostname}-shaarli \
+  --hostname shaarli.${domainname} \
+  -v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \
+  -v /etc/localtime:/etc/localtime:ro \
+  shaarli/shaarli:latest
+
+ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
+
+
+[Install]
+WantedBy=multi-user.target
+```
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..12f7b5d1 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,24 @@ 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/)
 
+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/).
+
 ### Download from DockerHub
 ```bash
 $ docker pull shaarli/shaarli
@@ -69,3 +82,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 24ada6c7..e77b4d3a 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -22,9 +22,25 @@ It runs the latest development version of Shaarli and is updated/reset daily.
 
 Login: `demo`; Password: `demo`
 
-
 ## 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
@@ -78,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