From fdf88d194874a533cf3a8de3d317d70018aa8a62 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Wed, 12 Oct 2016 12:36:59 +0200 Subject: Bump version to v0.8.0 Signed-off-by: ArthurHoaro --- doc/3rd-party-libraries.html | 9 +- doc/3rd-party-libraries.md | 1 + doc/Backup,-restore,-import-and-export.html | 34 ++- doc/Backup,-restore,-import-and-export.md | 31 +++ doc/Browsing-and-searching.html | 8 +- doc/Coding-guidelines.html | 8 +- doc/Community-&-Related-software.html | 11 +- doc/Community-&-Related-software.md | 3 +- ...installation-over-SSH-and-serve-it-locally.html | 58 ++-- doc/Create-and-serve-multiple-Shaarlis-(farm).html | 52 ++-- doc/Datastore-hacks.html | 8 +- doc/Development.html | 8 +- doc/Directory-structure.html | 60 ++--- doc/Docker.html | 104 ++++--- doc/Download-CSS-styles-from-an-OPML-list.html | 12 +- doc/Download-and-Installation.html | 165 ++++++++++++ doc/Download-and-Installation.md | 97 +++++++ doc/Download.html | 123 --------- doc/Download.md | 31 --- ...xample-patch---add-new-via-field-for-links.html | 8 +- doc/FAQ.html | 8 +- doc/Firefox-share.html | 8 +- doc/GnuPG-signature.html | 58 ++-- doc/Home.html | 8 +- doc/Plugin-System.html | 8 +- doc/Plugins.html | 8 +- doc/RSS-feeds.html | 8 +- doc/Release-Shaarli.html | 69 +++-- doc/Release-Shaarli.md | 24 +- doc/Security.html | 8 +- doc/Server-configuration.html | 41 ++- doc/Server-configuration.md | 12 - doc/Server-requirements.html | 46 +++- doc/Server-requirements.md | 19 +- doc/Server-security.html | 28 +- doc/Server-security.md | 14 + doc/Shaarli-configuration.html | 277 ++++++++++--------- doc/Shaarli-configuration.md | 298 +++++++++++++-------- doc/Shaarli-installation.html | 72 ----- doc/Shaarli-installation.md | 6 - doc/Sharing-button.html | 8 +- doc/Static-analysis.html | 8 +- doc/TODO.html | 74 ----- doc/TODO.md | 4 - doc/Theming.html | 25 +- doc/Theming.md | 1 + doc/Troubleshooting.html | 11 +- doc/Troubleshooting.md | 3 +- doc/Unit-tests.html | 110 ++++---- doc/Upgrade-and-migration.html | 242 +++++++++++++++++ doc/Upgrade-and-migration.md | 161 +++++++++++ doc/Upgrade-from-original-sebsauvage-Shaarli.html | 74 ----- doc/Upgrade-from-original-sebsauvage-Shaarli.md | 4 - doc/Usage.html | 8 +- doc/_Footer.html | 12 +- doc/_Footer.md | 2 +- doc/_Sidebar.html | 16 +- doc/_Sidebar.md | 8 +- doc/sidebar.html | 8 +- 59 files changed, 1534 insertions(+), 1096 deletions(-) create mode 100644 doc/Download-and-Installation.html create mode 100644 doc/Download-and-Installation.md delete mode 100644 doc/Download.html delete mode 100644 doc/Download.md delete mode 100644 doc/Shaarli-installation.html delete mode 100644 doc/Shaarli-installation.md delete mode 100644 doc/TODO.html delete mode 100644 doc/TODO.md create mode 100644 doc/Upgrade-and-migration.html create mode 100644 doc/Upgrade-and-migration.md delete mode 100644 doc/Upgrade-from-original-sebsauvage-Shaarli.html delete mode 100644 doc/Upgrade-from-original-sebsauvage-Shaarli.md (limited to 'doc') diff --git a/doc/3rd-party-libraries.html b/doc/3rd-party-libraries.html index f6ff4763..946ca037 100644 --- a/doc/3rd-party-libraries.html +++ b/doc/3rd-party-libraries.html @@ -15,13 +15,13 @@ @@ -81,6 +79,7 @@

PHP

diff --git a/doc/3rd-party-libraries.md b/doc/3rd-party-libraries.md index 3101c90a..e6370549 100644 --- a/doc/3rd-party-libraries.md +++ b/doc/3rd-party-libraries.md @@ -10,4 +10,5 @@ - [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation[](.html) ## PHP +- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser[](.html) - [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP[](.html) diff --git a/doc/Backup,-restore,-import-and-export.html b/doc/Backup,-restore,-import-and-export.html index 4d72728e..a4a48ad7 100644 --- a/doc/Backup,-restore,-import-and-export.html +++ b/doc/Backup,-restore,-import-and-export.html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

Backup, restore, import and export

+ +

Backup and restore the datastore file

Backup the file data/datastore.php (by FTP or SSH). Restore by putting the file back in place.

Example command:

-
rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php
+
rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php

To export links as an HTML file, under Tools > Export, choose:

Example command:

-
./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all
+
./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all

Diigo

If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)

@@ -126,5 +131,20 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

See this issue for import tweaks.

SemanticScuttle

To correctly import the tags from a SemanticScuttle HTML export, edit the HTML file before importing and replace all occurences of tags= (lowercase) to TAGS= (uppercase).

+

Scuttle

+

Shaarli cannot import data directly from Scuttle. However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.

+ + +

Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.

+

You may be interested in these Firefox addons to manage links imported from Shaarli

+ diff --git a/doc/Backup,-restore,-import-and-export.md b/doc/Backup,-restore,-import-and-export.md index cf6b9f48..9f5598ef 100644 --- a/doc/Backup,-restore,-import-and-export.md +++ b/doc/Backup,-restore,-import-and-export.md @@ -1,4 +1,12 @@ #Backup, restore, import and export + * [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)[](.html) + * [Export links as...](#export-links-as)[](.html) + * [Import links from...](#import-links-from)[](.html) + * [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)[](.html) + + +---------------------- + ## Backup and restore the datastore file Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place. @@ -9,6 +17,7 @@ rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date + ``` ## Export links as... + To export links as an HTML file, under _Tools > Export_, choose: - _Export all_ to export both public and private links - _Export public_ to export public links only @@ -23,13 +32,35 @@ Example command: ``` ## Import links from... + + ### Diigo If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.) + ### Mister Wong + See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.[](.html) ### SemanticScuttle To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).[](.html) + +### Scuttle + +Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.[](.html) + +## Import Shaarli links to Firefox + + * Export your Shaarli links as described above. + * For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)` + * In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`) + * Select `Import and Backup > Import bookmarks in HTML format` + +Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time. + +You may be interested in these Firefox addons to manage links imported from Shaarli + + * [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks[](.html) + * [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags[](.html) diff --git a/doc/Browsing-and-searching.html b/doc/Browsing-and-searching.html index 39806128..23001bcb 100644 --- a/doc/Browsing-and-searching.html +++ b/doc/Browsing-and-searching.html @@ -15,13 +15,13 @@ diff --git a/doc/Coding-guidelines.html b/doc/Coding-guidelines.html index add69631..1a2a9351 100644 --- a/doc/Coding-guidelines.html +++ b/doc/Coding-guidelines.html @@ -15,13 +15,13 @@ diff --git a/doc/Community-&-Related-software.html b/doc/Community-&-Related-software.html index 77b9793f..accbacdc 100644 --- a/doc/Community-&-Related-software.html +++ b/doc/Community-&-Related-software.html @@ -15,13 +15,13 @@ @@ -84,8 +82,9 @@
  • autosave by @kalvn: Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
  • Code Coloration by @ArthurHoaro: client side code syntax highlighter.
  • social by @alexisju: share links to social networks.
    • -
  • emojione by @NerosTie: Add colorful emojis to your Shaarli.
    • +
  • emojione by @NerosTie: Add colorful emojis to your Shaarli.
  • launch - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
    • +
  • Disqus by @kalvn: Adds Disqus comment system to your Shaarli.

    • Themes

    See Theming for the list of community-contributed themes, and an installation guide.

    diff --git a/doc/Community-&-Related-software.md b/doc/Community-&-Related-software.md index 03a3dea9..3945d005 100644 --- a/doc/Community-&-Related-software.md +++ b/doc/Community-&-Related-software.md @@ -21,8 +21,9 @@ _TODO: contact repos owners to see if they'd like to standardize their work with * [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.[](.html) * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.[](.html) * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.[](.html) - * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie/emojione): Add colorful emojis to your Shaarli.[](.html) + * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.[](.html) * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.[](.html) + * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.[](.html) ### Themes diff --git a/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html b/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html index edb1555f..9efb1ad6 100644 --- a/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html +++ b/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf @@ -111,55 +109,55 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf #Usage: ./local-shaarli.sh #Author: nodiscc (nodiscc@gmail.com) #License: MIT (http://opensource.org/licenses/MIT) -set -o errexit -set -o nounset +set -o errexit +set -o nounset ##### CONFIG ################# #The port used by php's local server -php_local_port=7431 +php_local_port=7431 #Name of the SSH server and path where Shaarli is installed #TODO: pass these as command-line arguments -remotehost="my.ssh.server" -remote_shaarli_dir="/var/www/shaarli" +remotehost="my.ssh.server" +remote_shaarli_dir="/var/www/shaarli" ###### FUNCTIONS ############# _main() { - _CBSyncShaarli - _CBServeShaarli + _CBSyncShaarli + _CBServeShaarli } _CBSyncShaarli() { - remote_temp_dir=$(ssh $remotehost mktemp -d) - remote_ssh_user=$(ssh $remotehost whoami) - ssh -t "$remotehost" sudo cp -r "$remote_shaarli_dir" "$remote_temp_dir" - ssh -t "$remotehost" sudo chown -R "$remote_ssh_user":"$remote_ssh_user" "$remote_temp_dir" - scp -rq "$remotehost":"$remote_temp_dir" local-shaarli - ssh "$remotehost" rm -r "$remote_temp_dir" + remote_temp_dir=$(ssh $remotehost mktemp -d) + remote_ssh_user=$(ssh $remotehost whoami) + ssh -t "$remotehost" sudo cp -r "$remote_shaarli_dir" "$remote_temp_dir" + ssh -t "$remotehost" sudo chown -R "$remote_ssh_user":"$remote_ssh_user" "$remote_temp_dir" + scp -rq "$remotehost":"$remote_temp_dir" local-shaarli + ssh "$remotehost" rm -r "$remote_temp_dir" } _CBServeShaarli() { #TODO: allow serving a previously downloaded Shaarli #TODO: ask before overwriting local copy, if it exists - cd local-shaarli/ - php -S localhost:${php_local_port} - echo "Please go to http://localhost:${php_local_port}" + cd local-shaarli/ + php -S localhost:${php_local_port} + echo "Please go to http://localhost:${php_local_port}" } ##### MAIN ################# -_main +_main

    This outputs:

    -
    $ ./local-shaarli.sh
-PHP 5.6.0RC4 Development Server started at Mon Sep  1 21:56:19 2014
-Listening on http://localhost:7431
-Document root is /home/user/local-shaarli/shaarli
-Press Ctrl-C to quit.
+
    $ ./local-shaarli.sh
+PHP 5.6.0RC4 Development Server started at Mon Sep  1 21:56:19 2014
+Listening on http://localhost:7431
+Document root is /home/user/local-shaarli/shaarli
+Press Ctrl-C to quit.
 
-[Mon Sep  1 21:56:27 2014] ::1:57868 [200]: /[](.html)
-[Mon Sep  1 21:56:27 2014] ::1:57869 [200]: /index.html[](.html)
-[Mon Sep  1 21:56:37 2014] ::1:57881 [200]: /...[](.html)
    
+[Mon Sep  1 21:56:27 2014] ::1:57868 [200]: /[](.html)
+[Mon Sep  1 21:56:27 2014] ::1:57869 [200]: /index.html[](.html)
+[Mon Sep  1 21:56:37 2014] ::1:57881 [200]: /...[](.html)
    diff --git a/doc/Create-and-serve-multiple-Shaarlis-(farm).html b/doc/Create-and-serve-multiple-Shaarlis-(farm).html index 933144e4..672e4bf3 100644 --- a/doc/Create-and-serve-multiple-Shaarlis-(farm).html +++ b/doc/Create-and-serve-multiple-Shaarlis-(farm).html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

    Create and serve multiple Shaarlis (farm)

    Example bash script (creates multiple shaarli instances and generates an HTML index of them)

    #!/bin/bash
-set -o errexit
-set -o nounset
+set -o errexit
+set -o nounset
 
 #config
-shaarli_base_dir='/var/www/shaarli'
-accounts='bob john whatever username'
-shaarli_repo_url='https://github.com/shaarli/Shaarli'
-ref="master"
+shaarli_base_dir='/var/www/shaarli'
+accounts='bob john whatever username'
+shaarli_repo_url='https://github.com/shaarli/Shaarli'
+ref="master"
 
 #clone multiple shaarli instances
-if [ ! -d "$shaarli_base_dir" ]; then mkdir "$shaarli_base_dir"; fi[](.html)
+if [ ! -d "$shaarli_base_dir" ]; then mkdir "$shaarli_base_dir"; fi[](.html)
    
-for account in $accounts; do
-    if [ -d "$shaarli_base_dir/$account" ];[](.html)
-    then echo "[info] account $account already exists, skipping";[](.html)
-    else echo "[info] creating new account $account ..."; git clone --quiet "$shaarli_repo_url" -b "$ref" "$shaarli_base_dir/$account"; fi[](.html)
+for account in $accounts; do
+    if [ -d "$shaarli_base_dir/$account" ];[](.html)
+    then echo "[info] account $account already exists, skipping";[](.html)
+    else echo "[info] creating new account $account ..."; git clone --quiet "$shaarli_repo_url" -b "$ref" "$shaarli_base_dir/$account"; fi[](.html)
 done
 
 #generate html index of shaarlis
-htmlhead='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+htmlhead='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
 <!-- Minimal html template thanks to http://www.sitepoint.com/a-minimal-html-document/ -->
 <html lang="en">
     <head>
@@ -136,9 +134,9 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
     <h1>My Shaarli farm</h1>
     <ul style="list-style-type: none;">'
 
-accountlinks=''
+accountlinks=''
     
-htmlfooter='
+htmlfooter='
     </ul>
     </div>
     </body>
@@ -146,14 +144,14 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
     
 
 
-for account in $accounts; do accountlinks="$accountlinks\n<li><a href=\"$account\">$account</a></li>"; done
-if [ -d "$shaarli_base_dir/index.html" ]; then echo "[removing old index.html]"; rm "$shaarli_base_dir/index.html" ]; fi[](.html)
-echo "[info] generating new index of shaarlis"[](.html)
-echo -e "$htmlhead $accountlinks $htmlfooter" > "$shaarli_base_dir/index.html"
-echo '[info] done.'[](.html)
-echo "[info] list of accounts: $accounts"[](.html)
-echo "[info] contents of $shaarli_base_dir:"[](.html)
-tree -a -L 1 "$shaarli_base_dir"
    +for account in $accounts; do accountlinks="$accountlinks\n<li><a href=\"$account\">$account</a></li>"; done +if [ -d "$shaarli_base_dir/index.html" ]; then echo "[removing old index.html]"; rm "$shaarli_base_dir/index.html" ]; fi[](.html) +echo "[info] generating new index of shaarlis"[](.html) +echo -e "$htmlhead $accountlinks $htmlfooter" > "$shaarli_base_dir/index.html" +echo '[info] done.'[](.html) +echo "[info] list of accounts: $accounts"[](.html) +echo "[info] contents of $shaarli_base_dir:"[](.html) +tree -a -L 1 "$shaarli_base_dir"

    This script just serves as an example. More precise or complex (applying custom configuration, etc) automation is possible using configuration management software like Ansible

    diff --git a/doc/Datastore-hacks.html b/doc/Datastore-hacks.html index 88639402..15da09d4 100644 --- a/doc/Datastore-hacks.html +++ b/doc/Datastore-hacks.html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf diff --git a/doc/Development.html b/doc/Development.html index 2eacff94..c5776413 100644 --- a/doc/Development.html +++ b/doc/Development.html @@ -15,13 +15,13 @@ diff --git a/doc/Directory-structure.html b/doc/Directory-structure.html index 003d4d94..404ff7c8 100644 --- a/doc/Directory-structure.html +++ b/doc/Directory-structure.html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

    Directory structure

    Here is the directory structure of Shaarli and the purpose of the different files:

    -
        index.php        # Main program
-    application/     # Shaarli classes
-        ├── LinkDB.php
-        └── Utils.php
-    tests/       # Shaarli unitary & functional tests
-        ├── LinkDBTest.php
-        ├── utils  # utilities to ease testing
-        │   └── ReferenceLinkDB.php
-        └── UtilsTest.php
-    COPYING          # Shaarli license
-    inc/             # static assets and 3rd party libraries
-        ├── awesomplete.*          # tags autocompletion library
-        ├── blazy.*                # picture wall lazy image loading library
-        ├── shaarli.css, reset.css # Shaarli stylesheet.
-        ├── qr.*                   # qr code generation library
-        └──rain.tpl.class.php      # RainTPL templating library
-    tpl/             # RainTPL templates for Shaarli. They are used to build the pages.
-    images/          # Images and icons used in Shaarli
-    data/            # data storage: bookmark database, configuration, logs, banlist…
-        ├── config.php             # Shaarli configuration (login, password, timezone, title…)
-        ├── datastore.php          # Your link database (compressed).
-        ├── ipban.php              # IP address ban system data
-        ├── lastupdatecheck.txt    # Update check timestamp file
-        └──log.txt                 # login/IPban log.
-    cache/           # thumbnails cache
+
        index.php        # Main program
+    application/     # Shaarli classes
+        ├── LinkDB.php
+        └── Utils.php
+    tests/       # Shaarli unitary & functional tests
+        ├── LinkDBTest.php
+        ├── utils  # utilities to ease testing
+        │   └── ReferenceLinkDB.php
+        └── UtilsTest.php
+    COPYING          # Shaarli license
+    inc/             # static assets and 3rd party libraries
+        ├── awesomplete.*          # tags autocompletion library
+        ├── blazy.*                # picture wall lazy image loading library
+        ├── shaarli.css, reset.css # Shaarli stylesheet.
+        ├── qr.*                   # qr code generation library
+        └──rain.tpl.class.php      # RainTPL templating library
+    tpl/             # RainTPL templates for Shaarli. They are used to build the pages.
+    images/          # Images and icons used in Shaarli
+    data/            # data storage: bookmark database, configuration, logs, banlist…
+        ├── config.php             # Shaarli configuration (login, password, timezone, title…)
+        ├── datastore.php          # Your link database (compressed).
+        ├── ipban.php              # IP address ban system data
+        ├── lastupdatecheck.txt    # Update check timestamp file
+        └──log.txt                 # login/IPban log.
+    cache/           # thumbnails cache
                      # This directory is automatically created. You can erase it anytime you want.
-    tmp/             # Temporary directory for compiled RainTPL templates.
+    tmp/             # Temporary directory for compiled RainTPL templates.
                      # This directory is automatically created. You can erase it anytime you want.
    
 
 
diff --git a/doc/Docker.html b/doc/Docker.html
index a443d100..e89c90fb 100644
--- a/doc/Docker.html
+++ b/doc/Docker.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -112,18 +110,18 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
    Install Docker, by following the instructions relevant
    
 to your OS / distribution, and start the service.
    
 
    Search an image on DockerHub
    
-
    $ docker search debian
+
    $ docker search debian
 
-NAME            DESCRIPTION                                     STARS   OFFICIAL   AUTOMATED
-ubuntu          Ubuntu is a Debian-based Linux operating s...   2065    [OK][](.html)
-debian          Debian is a Linux distribution that's comp...   603     [OK][](.html)
+NAME            DESCRIPTION                                     STARS   OFFICIAL   AUTOMATED
+ubuntu          Ubuntu is a Debian-based Linux operating s...   2065    [OK][](.html)
+debian          Debian is a Linux distribution that's comp...   603     [OK][](.html)
 google/debian                                                   47                 [OK][](.html)
    
 
    Show available tags for a repository
    
-
    $ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
+
    $ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
 
-% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
-Dload  Upload   Total   Spent    Left  Speed
-100  1283    0  1283    0     0    433      0 --:--:--  0:00:02 --:--:--   433
    
+% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+Dload  Upload   Total   Spent    Left  Speed
+100  1283    0  1283    0     0    433      0 --:--:--  0:00:02 --:--:--   433
    
 
    Sample output:
    
 
    [[](.html)
     {
@@ -148,14 +146,14 @@ to your OS / distribution, and start the service.
    
     }
 ]
    
 
    Pull an image from DockerHub
    
-
    $ docker pull repository[:tag][](.html)
+
    $ docker pull repository[:tag][](.html)
 
-$ docker pull debian:wheezy
-wheezy: Pulling from debian
-4c8cbfd2973e: Pull complete
-60c52dbe9d91: Pull complete
-Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
-Status: Downloaded newer image for debian:wheezy
    
+$ docker pull debian:wheezy
+wheezy: Pulling from debian
+4c8cbfd2973e: Pull complete
+60c52dbe9d91: Pull complete
+Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
+Status: Downloaded newer image for debian:wheezy
    
 
    Get and run a Shaarli image
    
 
    DockerHub repository
    
 
    The images can be found in the shaarli/shaarli
    
@@ -173,53 +171,53 @@ repository.
    
 
  • Nginx
    • 
 
 
    Download from DockerHub
    
-
    $ docker pull shaarli/shaarli
-latest: Pulling from shaarli/shaarli
-32716d9fcddb: Pull complete
-84899d045435: Pull complete
-4b6ad7444763: Pull complete
-e0345ef7a3e0: Pull complete
-5c1dd344094f: Pull complete
-6422305a200b: Pull complete
-7d63f861dbef: Pull complete
-3eb97210645c: Pull complete
-869319d746ff: Already exists
-869319d746ff: Pulling fs layer
-902b87aaaec9: Already exists
-Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98
-Status: Downloaded newer image for shaarli/shaarli:latest
    
+
    $ docker pull shaarli/shaarli
+latest: Pulling from shaarli/shaarli
+32716d9fcddb: Pull complete
+84899d045435: Pull complete
+4b6ad7444763: Pull complete
+e0345ef7a3e0: Pull complete
+5c1dd344094f: Pull complete
+6422305a200b: Pull complete
+7d63f861dbef: Pull complete
+3eb97210645c: Pull complete
+869319d746ff: Already exists
+869319d746ff: Pulling fs layer
+902b87aaaec9: Already exists
+Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98
+Status: Downloaded newer image for shaarli/shaarli:latest
    
 
    Create and start a new container from the image
    
 
    # map the host's :8000 port to the container's :80 port
-$ docker create -p 8000:80 shaarli/shaarli
-d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+$ docker create -p 8000:80 shaarli/shaarli
+d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
 
 # launch the container in the background
-$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
-d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
 
 # list active containers
-$ docker ps
-CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
-d40b7af693d6  shaarli/shaarli  /usr/bin/supervisor  15 seconds ago  Up 4 seconds  0.0.0.0:8000->80/tcp  backstabbing_galileo
    
+$ docker ps
+CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
+d40b7af693d6  shaarli/shaarli  /usr/bin/supervisor  15 seconds ago  Up 4 seconds  0.0.0.0:8000->80/tcp  backstabbing_galileo
    
 
    Stop and destroy a container
    
-
    $ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!
-backstabbing_galileo
+
    $ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!
+backstabbing_galileo
 
 # check the container is stopped
-$ docker ps
-CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
+$ docker ps
+CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
 
 # list ALL containers
-$ docker ps -a
-CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                      PORTS               NAMES
-d40b7af693d6        shaarli/shaarli     /usr/bin/supervisor   5 minutes ago       Exited (0) 48 seconds ago                       backstabbing_galileo
+$ docker ps -a
+CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                      PORTS               NAMES
+d40b7af693d6        shaarli/shaarli     /usr/bin/supervisor   5 minutes ago       Exited (0) 48 seconds ago                       backstabbing_galileo
 
 # destroy the container
-$ docker rm backstabbing_galileo  # let's put an end to these barbarian practices
-backstabbing_galileo
+$ docker rm backstabbing_galileo  # let's put an end to these barbarian practices
+backstabbing_galileo
 
-$ docker ps -a
-CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
    
+$ docker ps -a
+CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
    
 
    Resources
    
 
    Docker
    
 
      
diff --git a/doc/Download-CSS-styles-from-an-OPML-list.html b/doc/Download-CSS-styles-from-an-OPML-list.html
index 22771502..a4f68ac6 100644
--- a/doc/Download-CSS-styles-from-an-OPML-list.html
+++ b/doc/Download-CSS-styles-from-an-OPML-list.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -209,8 +207,8 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
 /**
  * Reading directory list, courtesy of http://www.laughing-buddha.net/php/dirlist/
- * @param directory the directory we want to list files of
- * @return a simple array containing the list of absolute file paths. Notice that current file (".") and parent one("..")
+ * @param directory the directory we want to list files of
+ * @return a simple array containing the list of absolute file paths. Notice that current file (".") and parent one("..")
  * are not listed here
  */
 function getDirectoryList ($directory)  {
diff --git a/doc/Download-and-Installation.html b/doc/Download-and-Installation.html
new file mode 100644
index 00000000..17c7b69e
--- /dev/null
+++ b/doc/Download-and-Installation.html
@@ -0,0 +1,165 @@
+
+
+
+  
+  
+  
+  Shaarli – Download and Installation
+  
+  
+  
+  
+
+
+
+
      Download and Installation
      
+
      Get Shaarli!
      
+
      To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your server is properly configured.
      
+
      Several releases are available:
      
+
      
+
+
      Get the latest released version from the releases page.
      
+
      The current latest released version is v0.7.0.
      
+
      Download as an archive
      
+
      As a .zip archive:
      
+
      $ wget https://github.com/shaarli/Shaarli/archive/v0.7.0.zip
+$ unzip Shaarli-v0.7.0.zip
+$ mv Shaarli-v0.7.0 /path/to/shaarli/
      
+
++++
+
+
+
+
+
+
+
+
+
      



      !In most cases, download Shaarli from the releases page. Cloning using git or downloading Github branches as zip files requires additional steps (see below).
      
+
      
+
      Stable version
      
+
      The stable version has been experienced by Shaarli users, and will receive security updates.
      
+
      Download as an archive
      
+
      As a .zip archive:
      
+
      $ wget https://github.com/shaarli/Shaarli/archive/stable.zip
+$ unzip stable.zip
+$ mv Shaarli-stable /path/to/shaarli/
      
+
      As a .tar.gz archive :
      
+
      $ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
+$ tar xvf stable.tar.gz
+$ mv Shaarli-stable /path/to/shaarli/
      
+
      Clone with Git
      
+
      Composer is required to build a functional Shaarli installation when pulling from git.
      
+
      $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
+# install/update third-party dependencies
+$ cd /path/to/shaarli/
+$ composer update --no-dev
      
+
      
+
      Development version (mainline)
      
+
      Use at your own risk!
      
+
      To get the latest changes from the master branch:
      
+
      # clone the repository  
+$ git clone https://github.com/shaarli/Shaarli.git master /path/to/shaarli/
+# install/update third-party dependencies
+$ cd /path/to/shaarli
+$ composer update --no-dev
      
+
      
+
      Finish Installation
      
+
      Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
      
+
      install screenshot
      
+
      Setup your Shaarli installation, and it's ready to use!
      
+
      
+
      Updating Shaarli
      
+
      See Upgrade and Migration
      
+
+
diff --git a/doc/Download-and-Installation.md b/doc/Download-and-Installation.md
new file mode 100644
index 00000000..77af25eb
--- /dev/null
+++ b/doc/Download-and-Installation.md
@@ -0,0 +1,97 @@
+#Download and Installation
+# Get Shaarli!
+
+To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your [server](Server-requirements) is properly [configured](Server-configuration).[](.html)
+
+Several releases are available:
+
+--------------------------------------------------------
+
+## Latest release (recommended)
+
+Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
+
+The current latest released version is `v0.7.0`.
+
+### Download as an archive
+
+As a .zip archive:
+
+```bash
+$ wget https://github.com/shaarli/Shaarli/archive/v0.7.0.zip
+$ unzip Shaarli-v0.7.0.zip
+$ mv Shaarli-v0.7.0 /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).|[](.html)
+|-----|--------------------------|
+
+
+
+--------------------------------------------------------
+
+## Stable version
+
+The stable version has been experienced by Shaarli users, and will receive security updates.
+
+### Download as an archive
+
+As a .zip archive:
+
+```bash
+$ wget https://github.com/shaarli/Shaarli/archive/stable.zip
+$ unzip stable.zip
+$ mv Shaarli-stable /path/to/shaarli/
+```
+
+As a .tar.gz archive :
+
+```bash
+$ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
+$ tar xvf stable.tar.gz
+$ mv Shaarli-stable /path/to/shaarli/
+```
+
+### Clone with Git 
+
+[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.[](.html)
+
+```bash
+$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
+# install/update third-party dependencies
+$ cd /path/to/shaarli/
+$ composer update --no-dev
+```
+
+--------------------------------------------------------
+
+## Development version (mainline)
+
+_Use at your own risk!_
+
+To get the latest changes from the `master` branch:
+
+```bash
+# clone the repository  
+$ git clone https://github.com/shaarli/Shaarli.git master /path/to/shaarli/
+# install/update third-party dependencies
+$ cd /path/to/shaarli
+$ composer update --no-dev
+```
+
+--------------------------------------------------------
+
+## 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)[](.html)
+
+Setup your Shaarli installation, and it's ready to use!
+
+--------------------------------------------------------
+
+## Updating Shaarli
+
+See [Upgrade and Migration](Upgrade-and-migration)[](.html)
diff --git a/doc/Download.html b/doc/Download.html
deleted file mode 100644
index 9f9f5117..00000000
--- a/doc/Download.html
+++ /dev/null
@@ -1,123 +0,0 @@
-
-
-
-  
-  
-  
-  Shaarli – Download
-  
-  
-  
-  
-
-
-
-
      Download
      
-
      Get Shaarli!
      
-
      Latest stable revision
      
-
      This revision has been released and tested.
      
-
-
      $ git clone https://github.com/shaarli/Shaarli.git -b stable shaarli
      
-
      Download as an archive
      
-
      $ wget https://github.com/shaarli/Shaarli/archive/stable.zip
-$ unzip stable.zip
-$ mv Shaarli-stable shaarli
      
-
      Tarballs are also available:
      
-
      $ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
-$ tar xvf stable.tar.gz
-$ mv Shaarli-stable shaarli
      
-
      Development (mainline)
      
-
      Use at your own risk!
      
-
      To get the latest changes:
      
-
      $ git clone https://github.com/shaarli/Shaarli.git shaarli
      
-
-
diff --git a/doc/Download.md b/doc/Download.md
deleted file mode 100644
index 7930f541..00000000
--- a/doc/Download.md
+++ /dev/null
@@ -1,31 +0,0 @@
-#Download
-## Get Shaarli!
-### Latest stable revision
-This revision has been [released](https://github.com/shaarli/Shaarli/releases) and tested.[](.html)
-
-#### Clone with Git (recommended)
-```bash
-$ git clone https://github.com/shaarli/Shaarli.git -b stable shaarli
-```
-
-#### Download as an archive
-```bash
-$ wget https://github.com/shaarli/Shaarli/archive/stable.zip
-$ unzip stable.zip
-$ mv Shaarli-stable shaarli
-```
-
-Tarballs are also available:
-```bash
-$ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
-$ tar xvf stable.tar.gz
-$ mv Shaarli-stable shaarli
-```
-
-### Development (mainline)
-_Use at your own risk!_
-
-To get the latest changes:
-```bash
-$ git clone https://github.com/shaarli/Shaarli.git shaarli
-```
diff --git a/doc/Example-patch---add-new-via-field-for-links.html b/doc/Example-patch---add-new-via-field-for-links.html
index 7db43107..133224e2 100644
--- a/doc/Example-patch---add-new-via-field-for-links.html
+++ b/doc/Example-patch---add-new-via-field-for-links.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/FAQ.html b/doc/FAQ.html
index 3b6b956d..61f3475f 100644
--- a/doc/FAQ.html
+++ b/doc/FAQ.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/Firefox-share.html b/doc/Firefox-share.html
index add6d4e8..d7dcc282 100644
--- a/doc/Firefox-share.html
+++ b/doc/Firefox-share.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/GnuPG-signature.html b/doc/GnuPG-signature.html
index c431f9ad..50b904d5 100644
--- a/doc/GnuPG-signature.html
+++ b/doc/GnuPG-signature.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -129,26 +127,26 @@ Keys
 
    • Generating a GPG key (GitHub)
      • 
 
    
 
    gpg - provide identity information
    
-
    $ gpg --gen-key
+
    $ gpg --gen-key
 
-gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
+gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
 
-Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
+Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
 
-GnuPG needs to construct a user ID to identify your key.
+GnuPG needs to construct a user ID to identify your key.
 
-Real name: Marvin the Paranoid Android
-Email address: marvin@h2g2.net
-You selected this USER-ID:
+Real name: Marvin the Paranoid Android
+Email address: marvin@h2g2.net
+You selected this USER-ID:
     "Marvin the Paranoid Android <marvin@h2g2.net>"
 
-Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation; this gives the random number
-generator a better chance to gain enough entropy.
    
+Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
    
 
    gpg - entropy interlude
    
 
    At this point, you will:
    
 
      
@@ -156,19 +154,19 @@ Keys
 
    • be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step may take some time
      • 
 
    
 
    gpg - key creation confirmation
    
-
    gpg: key A9D53A3E marked as ultimately trusted
-public and secret key created and signed.
+
    gpg: key A9D53A3E marked as ultimately trusted
+public and secret key created and signed.
 
-gpg: checking the trustdb
-gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
-gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
-pub   rsa2048/A9D53A3E 2015-07-31
-      Key fingerprint = AF2A 5381 E54B 2FD2 14C4  A9A3 0E35 ACA4 A9D5 3A3E
-uid       [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>[](.html)
-sub   rsa2048/8C0EACF1 2015-07-31
    
+gpg: checking the trustdb
+gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
+gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
+pub   rsa2048/A9D53A3E 2015-07-31
+      Key fingerprint = AF2A 5381 E54B 2FD2 14C4  A9A3 0E35 ACA4 A9D5 3A3E
+uid       [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>[](.html)
+sub   rsa2048/8C0EACF1 2015-07-31
    
 
    gpg - submit your public key to a PGP server (Optional)
    
-
    $ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
-gpg: sending key A9D53A3E to hkp server pgp.mit.edu
    
+
    $ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
+gpg: sending key A9D53A3E to hkp server pgp.mit.edu
    
 
    Create and push a GPG-signed tag
    
 
    See Release Shaarli.
    
 
diff --git a/doc/Home.html b/doc/Home.html
index 442503c5..970f547e 100644
--- a/doc/Home.html
+++ b/doc/Home.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/Plugin-System.html b/doc/Plugin-System.html
index 37b26152..655536c6 100644
--- a/doc/Plugin-System.html
+++ b/doc/Plugin-System.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
diff --git a/doc/Plugins.html b/doc/Plugins.html
index e7df6aed..435a836f 100644
--- a/doc/Plugins.html
+++ b/doc/Plugins.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
diff --git a/doc/RSS-feeds.html b/doc/RSS-feeds.html
index 1b38e4e8..0f332b3d 100644
--- a/doc/RSS-feeds.html
+++ b/doc/RSS-feeds.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/Release-Shaarli.html b/doc/Release-Shaarli.html
index cfaa663b..cdefd3d6 100644
--- a/doc/Release-Shaarli.html
+++ b/doc/Release-Shaarli.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
 
    Release Shaarli
    
 
    See Git - Maintaining a project - Tagging your [](.html)
    
 releases    .
    
-
    Prerequisites
    
+
    Prerequisites
    
 
    This guide assumes that you have:
    
 
      
 
    • a GPG key matching your GitHub authentication credentials
@@ -118,53 +116,70 @@ releases.
      
 
    • upstream pointing to the main Shaarli repository
      • 
 
    
 
  • maintainer permissions on the main Shaarli repository (to push the signed tag)
    • 
-
  • Pandoc needs to be installed.
    • 
+
  • Composer and Pandoc need to be installed
    • 
 
+
    Increment the version code, create and push a signed tag
    
 
    Bump Shaarli's version
    
-
    $ cd /path/to/shaarli
+
    $ cd /path/to/shaarli
 
 # create a new branch
-$ git fetch upstream
-$ git checkout upstream/master -b v0.5.0
+$ git fetch upstream
+$ git checkout upstream/master -b v0.5.0
 
 # bump the version number
-$ vim index.php shaarli_version.php
+$ vim index.php shaarli_version.php
 
 # rebuild the documentation from the wiki
-$ make htmldoc
+$ make htmldoc
 
 # commit the changes
-$ git add index.php shaarli_version.php doc
-$ git commit -s -m "Bump version to v0.5.0"
+$ git add index.php shaarli_version.php doc
+$ git commit -s -m "Bump version to v0.5.0"
 
 # push the commit on your GitHub fork
-$ git push origin v0.5.0
    
+$ git push origin v0.5.0
    
 
    Create and merge a Pull Request
    
 
    This one is pretty straightforward ;-)
    
 
    Create and push a signed tag
    
 
    # update your local copy
-$ git checkout master
-$ git fetch upstream
-$ git pull upstream master
+$ git checkout master
+$ git fetch upstream
+$ git pull upstream master
 
 # create a signed tag
-$ git tag -s -m "Release v0.5.0" v0.5.0
+$ git tag -s -m "Release v0.5.0" v0.5.0
 
 # push it to "upstream"
-$ git push --tags upstream
    
+$ git push --tags upstream

    Verify a signed tag

    v0.5.0 is the first GPG-signed tag pushed on the Community Shaarli.

    Let's have a look at its signature!

    -
    $ cd /path/to/shaarli
-$ git fetch upstream
+
    $ cd /path/to/shaarli
+$ git fetch upstream
 
 # get the SHA1 reference of the tag
-$ git show-ref tags/v0.5.0
-f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
+$ git show-ref tags/v0.5.0
+f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
 
 # verify the tag signature information
-$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
-gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
-gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)
    
+$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
+gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
+gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)
    +

    Generate and upload all-in-one release archives

    +

    Users with a shared hosting may have:

    + +

    To ease Shaarli installations, it is possible to generate and upload additional release archives,
    +that will contain Shaarli code plus all required third-party libraries:

    +
    $ make release_archive
    +

    This will create the following archives:

    + +

    The archives need to be manually uploaded on the previously created GitHub release.

    diff --git a/doc/Release-Shaarli.md b/doc/Release-Shaarli.md index d5044fe9..5cbcd79a 100644 --- a/doc/Release-Shaarli.md +++ b/doc/Release-Shaarli.md @@ -2,7 +2,7 @@ See [Git - Maintaining a project - Tagging your [](.html) releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases). -### Prerequisites +## Prerequisites This guide assumes that you have: - a GPG key matching your GitHub authentication credentials - i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig` @@ -11,8 +11,9 @@ This guide assumes that you have: - `origin` pointing to your GitHub fork - `upstream` pointing to the main Shaarli repository - maintainer permissions on the main Shaarli repository (to push the signed tag) -- [Pandoc](http://pandoc.org/) needs to be installed.[](.html) +- [Composer](https://getcomposer.org/) and [Pandoc](http://pandoc.org/) need to be installed[](.html) +## Increment the version code, create and push a signed tag ### Bump Shaarli's version ```bash $ cd /path/to/shaarli @@ -70,3 +71,22 @@ $ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1 gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F gpg: Good signature from "VirtualTam " [ultimate][](.html) ``` + +## Generate and upload all-in-one release archives +Users with a shared hosting may have: +- no SSH access +- no possibility to install PHP packages or server extensions +- no possibility to run scripts + +To ease Shaarli installations, it is possible to generate and upload additional release archives, +that will contain Shaarli code plus all required third-party libraries: + +```bash +$ make release_archive +``` + +This will create the following archives: +- `shaarli-vX.Y.Z-full.tar` +- `shaarli-vX.Y.Z-full.zip` + +The archives need to be manually uploaded on the previously created GitHub release. diff --git a/doc/Security.html b/doc/Security.html index b1969a4c..cec20590 100644 --- a/doc/Security.html +++ b/doc/Security.html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf diff --git a/doc/Server-configuration.html b/doc/Server-configuration.html index 1d2276df..068900b8 100644 --- a/doc/Server-configuration.html +++ b/doc/Server-configuration.html @@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf @@ -133,7 +131,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

    See also proxy-related issues.

    Apache

    Minimal

    -
    <VirtualHost *:80>
+
    <VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 </VirtualHost>
    
@@ -144,11 +142,11 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
  • Apache/PHP - error log per VirtualHost (StackOverflow)
    • 
 
  • PHP: php_value vs php_admin_value and the use of php_flag explained
    • 
 
-
    <VirtualHost *:80>
+
    <VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 
-    LogLevel  warn
+    LogLevel  warn
     ErrorLog  /var/log/apache2/shaarli-error.log
     CustomLog /var/log/apache2/shaarli-access.log combined
 
@@ -158,40 +156,40 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
     php_value error_log /var/log/apache2/shaarli-php-error.log
 </VirtualHost>
    
 
    Standard - Keep access and error logs
    
-
    <VirtualHost *:80>
+
    <VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 
-    LogLevel  warn
+    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 (Mozilla).
    
-
    <VirtualHost *:443>
+
    <VirtualHost *:443>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 
-    SSLEngine             on
+    SSLEngine             on
     SSLCertificateFile    /absolute/path/to/the/website/certificate.pem
     SSLCertificateKeyFile /absolute/path/to/the/website/key.key
 
-    <Directory /absolute/path/to/shaarli/>
-        AllowOverride All
-        Options Indexes FollowSymLinks MultiViews
-        Order allow,deny
+    <Directory /absolute/path/to/shaarli/>
+        AllowOverride All
+        Options Indexes FollowSymLinks MultiViews
+        Order allow,deny
         allow from all
     </Directory>
 
-    LogLevel  warn
+    LogLevel  warn
     ErrorLog  /var/log/apache2/shaarli-error.log
     CustomLog /var/log/apache2/shaarli-access.log combined
 </VirtualHost>
-<VirtualHost *:80>
+<VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     Redirect 301 / https://shaarli.my-domain.org
 
-    LogLevel  warn
+    LogLevel  warn
     ErrorLog  /var/log/apache2/shaarli-error.log
     CustomLog /var/log/apache2/shaarli-access.log combined
 </VirtualHost>
    
@@ -410,10 +408,5 @@ http {
         include php.conf;
     }
 }
    
-
    Restricting search engines and web crawler traffic
    
-
    Creating a robots.txt witht he following contents at the root of your Shaarli installation will prevent "honest" web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
    
-
    User-agent: *
-Disallow: /
    
-
    See: http://www.robotstxt.org/, http://www.robotstxt.org/robotstxt.html, http://www.robotstxt.org/meta.html
    
 
 
diff --git a/doc/Server-configuration.md b/doc/Server-configuration.md
index fd98a608..1ab57a0a 100644
--- a/doc/Server-configuration.md
+++ b/doc/Server-configuration.md
@@ -334,15 +334,3 @@ http {
     }
 }
 ```
-
-## Restricting search engines and web crawler traffic
-
-Creating a `robots.txt` witht he following contents at the root of your Shaarli installation will prevent "honest" web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
-
-```
-User-agent: *
-Disallow: /
-```
-
-See: http://www.robotstxt.org/, http://www.robotstxt.org/robotstxt.html, http://www.robotstxt.org/meta.html
-
diff --git a/doc/Server-requirements.html b/doc/Server-requirements.html
index 8e4deeb8..2c2545bb 100644
--- a/doc/Server-requirements.html
+++ b/doc/Server-requirements.html
@@ -15,13 +15,13 @@
 
@@ -96,18 +94,18 @@
 
 
 5.5
-Supported
+EOL: 2016-07-10
 ✅
 
 
 5.4
 EOL: 2015-09-14
-✅
+✅ (up to Shaarli 0.8.x)
 
 
 5.3
 EOL: 2014-08-14
-✅
+✅ (up to Shaarli 0.8.x)
 
 
 
@@ -115,6 +113,25 @@
 
+
    Dependency management
    
+
    Starting with Shaarli v0.8.x, Composer is used to resolve,
    
+download and install third-party PHP dependencies.
    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
    LibraryRequired?Usage
    shaarli/netscape-bookmark-parserAllImport bookmarks from Netscape files
    
 
    Extensions
    
 @@ -142,13 +159,18 @@
 
-
+
-
-
-
+
+
+
+
+
+
+
+
    
 

 
    
 php-gd-optional
 thumbnail resizing
 
    
 
    php-intlOptionalTag cloud intelligent sorting (eg. e->è->f)php-intloptionallocalized text sorting (e.g. e->è->f)
    php-curloptionalusing cURL for fetching webpages and thumbnails in a more robust way
 
    
     
 
    
diff --git a/doc/Server-requirements.md b/doc/Server-requirements.md
index 7955fddf..4962193e 100644
--- a/doc/Server-requirements.md
+++ b/doc/Server-requirements.md
@@ -12,17 +12,26 @@ Version | Status | Shaarli compatibility
 :---:|:---:|:---:
 7.0 | Supported | :white_check_mark:
 5.6 | Supported | :white_check_mark:
-5.5 | Supported | :white_check_mark:
-5.4 | EOL: 2015-09-14 | :white_check_mark:
-5.3 | EOL: 2014-08-14 | :white_check_mark:
+5.5 | EOL: 2016-07-10 | :white_check_mark:
+5.4 | EOL: 2015-09-14 | :white_check_mark: (up to Shaarli 0.8.x)
+5.3 | EOL: 2014-08-14 | :white_check_mark: (up to Shaarli 0.8.x)
 
 See also:
 - [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)[](.html)
 
+### Dependency management
+Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,[](.html)
+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[](.html)
+
 ### Extensions
 Extension | Required? | Usage
 ---|:---:|---
 [`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS[](.html)
 [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows | multibyte (Unicode) string support[](.html)
-[`php-gd`](http://php.net/manual/en/book.image.php) | - | thumbnail resizing[](.html)
-[`php-intl`](http://php.net/manual/fr/book.intl.php) | Optional | Tag cloud intelligent sorting (eg. `e->è->f`)[](.html)
+[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing[](.html)
+[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)[](.html)
+[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way[](.html)
diff --git a/doc/Server-security.html b/doc/Server-security.html
index 6b44a133..3551deff 100644
--- a/doc/Server-security.html
+++ b/doc/Server-security.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -118,11 +116,11 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
 
    Locate .ini files
    
 
    Console environment
    
-
    $ php --ini
-Configuration File (php.ini) Path: /etc/php
-Loaded Configuration File:         /etc/php/php.ini
-Scan for additional .ini files in: /etc/php/conf.d
-Additional .ini files parsed:      /etc/php/conf.d/xdebug.ini
    
+
    $ php --ini
+Configuration File (php.ini) Path: /etc/php
+Loaded Configuration File:         /etc/php/php.ini
+Scan for additional .ini files in: /etc/php/conf.d
+Additional .ini files parsed:      /etc/php/conf.d/xdebug.ini
    
 
    Server environment
    
 
      
 
    • create a phpinfo.php script located in a path supported by the web server, e.g.
@@ -161,5 +159,15 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 [Definition][](.html)
 failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
 ignoreregex = 
    
+
    Robots - Restricting search engines and web crawler traffic
    
+
    Creating a robots.txt with the following contents at the root of your Shaarli installation will prevent honest web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
    
+
    User-agent: *
+Disallow: /
    
+
    See:
    
+
 
 
diff --git a/doc/Server-security.md b/doc/Server-security.md
index 0d16e284..50549a21 100644
--- a/doc/Server-security.md
+++ b/doc/Server-security.md
@@ -58,3 +58,17 @@ before = common.conf
 failregex = \s-\s\s-\sLogin failed for user.*$
 ignoreregex = 
 ```
+
+## Robots - Restricting search engines and web crawler traffic
+
+Creating a `robots.txt` with the following contents at the root of your Shaarli installation will prevent _honest_ web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
+
+```
+User-agent: *
+Disallow: /
+```
+
+See:
+- http://www.robotstxt.org/
+- http://www.robotstxt.org/robotstxt.html
+- http://www.robotstxt.org/meta.html
diff --git a/doc/Shaarli-configuration.html b/doc/Shaarli-configuration.html
index 74947578..6d717c65 100644
--- a/doc/Shaarli-configuration.html
+++ b/doc/Shaarli-configuration.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
 
    Shaarli configuration
    
+
    Shaarli configuration
    
 
    Foreword
    
 
    Do not edit configuration options in index.php! Your changes would be lost.
    
-
    Once your Shaarli instance is installed, the file data/config.php is generated:
    
+
    Once your Shaarli instance is installed, the file data/config.json.php is generated:
    
 
      
-
    • it contains all settings, and can be edited to customize values
      • 
-
    • it defines which plugins are enabled
      • 
+
    • it contains all settings in JSON format, and can be edited to customize values
      • 
+
    • it defines which plugins are enabled(.html)
      • 
 
    • its values override those defined in index.php
      • 
+
    • it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
      • 
 
    
 
    File and directory permissions
    
 
    The server process running Shaarli must have:
    
@@ -141,120 +141,155 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
  • unzip Shaarli in the default web server location (usually /var/www/) and set the web server user as the owner
    • 
 
  • put users in the same group as the web server, and set the appropriate access rights
    • 
 
-
  • if you have a domain / subdomain to serve Shaarli, configure the server accordingly
    • 
+
  • if you have a domain / subdomain to serve Shaarli, configure the server accordingly(.html)
    • 
 
-
    Example data/config.php
    
-
    See also Plugin System.
    
-
    <?php 
-// User login
-$GLOBALS['login'] = '<login>';[](.html)
-
-// User password hash
-$GLOBALS['hash'] = '200c452da46c2f889e5e48c49ef044bcacdcb095';[](.html)
-
-// Password salt
-$GLOBALS['salt'] = '13b654102321576033d8473b63a275a1bf94c0f0'; [](.html)
-
-// Local timezone
-$GLOBALS['timezone'] = 'Africa/Abidjan';[](.html)
-date_default_timezone_set('Africa/Abidjan');
-
-// Shaarli title
-$GLOBALS['title'] = 'My Little Shaarly';[](.html)
-
-// Link the Shaarli title points to
-$GLOBALS['titleLink'] = '?';[](.html)
-
-// HTTP referer redirector
-$GLOBALS['redirector'] = '';[](.html)
-
-// Disable session hijacking
-$GLOBALS['disablesessionprotection'] = false; [](.html)
-
-// Whether new links are private by default
-$GLOBALS['privateLinkByDefault'] = false;[](.html)
-
-// Enabled plugins
-// Note: each plugin may provide further settings through its own "config.php"
-$GLOBALS['config'['ENABLED_PLUGINS'] = array('addlink_toolbar', 'qrcode');]('ENABLED_PLUGINS']-=-array('addlink_toolbar',-'qrcode');.html)
-
-// Subdirectory where Shaarli stores its data files.
-// You can change it for better security.
-$GLOBALS['config'['DATADIR'] = 'data';]('DATADIR']-=-'data';.html)
-
-// File used to store settings
-$GLOBALS['config'['CONFIG_FILE'] = 'data/config.php';]('CONFIG_FILE']-=-'data/config.php';.html)
-
-// File containing the link database
-$GLOBALS['config'['DATASTORE'] = 'data/datastore.php';]('DATASTORE']-=-'data/datastore.php';.html)
-
-// Number of links displayed per page
-$GLOBALS['config'['LINKS_PER_PAGE'] = 20;]('LINKS_PER_PAGE']-=-20;.html)
-
-// File recording failed login attempts and IP bans
-$GLOBALS['config'['IPBANS_FILENAME'] = 'data/ipbans.php';]('IPBANS_FILENAME']-=-'data/ipbans.php';.html)
-
-// Failed login attempts before being banned
-$GLOBALS['config'['BAN_AFTER'] = 4;]('BAN_AFTER']-=-4;.html)
-
-// Duration of an IP ban, in seconds (30 minutes)
-$GLOBALS['config'['BAN_DURATION'] = 1800;]('BAN_DURATION']-=-1800;.html)
-
-// If set to true, everyone will be able to add, edit and remove links,
-// as well as change configuration
-$GLOBALS['config'['OPEN_SHAARLI'] = false;]('OPEN_SHAARLI']-=-false;.html)
-
-// Do not show link timestamps
-$GLOBALS['config'['HIDE_TIMESTAMPS'] = false;]('HIDE_TIMESTAMPS']-=-false;.html)
-
-// Set to false to disable local thumbnail cache, e.g. due to limited disk quotas
-$GLOBALS['config'['ENABLE_THUMBNAILS'] = true;]('ENABLE_THUMBNAILS']-=-true;.html)
-
-// Thumbnail cache directory
-$GLOBALS['config'['CACHEDIR'] = 'cache';]('CACHEDIR']-=-'cache';.html)
-
-// Enable feed (rss, atom, dailyrss) cache
-$GLOBALS['config'['ENABLE_LOCALCACHE'] = true;]('ENABLE_LOCALCACHE']-=-true;.html)
-
-// Feed cache directory
-$GLOBALS['config'['PAGECACHE'] = 'pagecache';]('PAGECACHE']-=-'pagecache';.html)
-
-// RainTPL cache directory (keep the trailing slash!)
-$GLOBALS['config'['RAINTPL_TMP'] = 'tmp/';]('RAINTPL_TMP']-=-'tmp/';.html)
-
-// RainTPL template directory (keep the trailing slash!)
-$GLOBALS['config'['RAINTPL_TPL'] = 'tpl/';]('RAINTPL_TPL']-=-'tpl/';.html)
-
-// Whether Shaarli checks for new releases at https://github.com/shaarli/Shaarli
-$GLOBALS['config'['ENABLE_UPDATECHECK'] = true;]('ENABLE_UPDATECHECK']-=-true;.html)
-
-// File to store the latest Shaarli version
-$GLOBALS['config'['UPDATECHECK_FILENAME'] = 'data/lastupdatecheck.txt';]('UPDATECHECK_FILENAME']-=-'data/lastupdatecheck.txt';.html)
-
-// Delay between version checks (requires to be logged in) (24 hours)
-$GLOBALS['config'['UPDATECHECK_INTERVAL'] = 86400;]('UPDATECHECK_INTERVAL']-=-86400;.html)
-
-// For each link, display a link to an archived version on archive.org
-$GLOBALS['config'['ARCHIVE_ORG'] = false;]('ARCHIVE_ORG']-=-false;.html)
-
-// The RSS item links point:
-// true   =>  directly to the link
-// false  =>  to the entry on Shaarli (permalink)
-$GLOBALS['config'['ENABLE_RSS_PERMALINKS'] = true;]('ENABLE_RSS_PERMALINKS']-=-true;.html)
-
-// Hide all links to non-logged users
-$GLOBALS['config'['HIDE_PUBLIC_LINKS'] = false;]('HIDE_PUBLIC_LINKS']-=-false;.html)
-
-$GLOBALS['config'['PUBSUBHUB_URL'] = '';]('PUBSUBHUB_URL']-=-'';.html)
-
-// Show an ATOM Feed button next to the Subscribe (RSS) button.
-// ATOM feeds are available at the address ?do=atom regardless of this option.
-$GLOBALS['config'['SHOW_ATOM'] = false;]('SHOW_ATOM']-=-false;.html)
-
-// Set this to true if the redirector requires encoded URL, false otherwise.
-$GLOBALS['config'['REDIRECTOR_URLENCODE'] = true;]('REDIRECTOR_URLENCODE']-=-true;.html)
-?>
    
+
    Configuration
    
+
    In data/config.json.php.
    
+
    See also Plugin System.
    
+
    Credentials
    
+
    
+
    You shouldn't edit those.
    
+
    
+
    login: Login username.
    
+hash: Generated password hash.
    
+salt: Password salt.
    
+
    General
    
+
    title: Shaarli's instance title.
    
+header_link: Link to the homepage.
    
+links_per_page: Number of shaares displayed per page.
    
+timezone: See the list of supported timezones. 
    
+enabled_plugins: List of enabled plugins.
    
+
    Security
    
+
    session_protection_disabled: Disable session cookie hijacking protection (not recommended).
    
+It might be useful if your IP adress often changes.
    
+ban_after: Failed login attempts before being IP banned.
    
+ban_duration: IP ban duration in seconds.
    
+open_shaarli: Anyone can add a new link while logged out if enabled.
    
+trusted_proxies: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
    
+
    Resources
    
+
    data_dir: Data directory.
    
+datastore: Shaarli's links database file path.
    
+updates: File path for the ran updates file.
    
+log: Log file path.
    
+update_check: Last update check file path.
    
+raintpl_tpl: Templates directory.
    
+raintpl_tmp: Template engine cache directory.
    
+thumbnails_cache: Thumbnails cache directory.
    
+page_cache: Shaarli's internal cache directory.
    
+ban_file: Banned IP file path.
    
+
    Updates
    
+
    check_updates: Enable or disable update check to the git repository.
    
+check_updates_branch: Git branch used to check updates (e.g. stable or master).
    
+check_updates_interval: Look for new version every N seconds (default: every day).
    
+
    Privacy
    
+
    default_private_links: Check the private checkbox by default for every new link.
    
+hide_public_links: All links are hidden while logged out.
    
+hide_timestamps: Timestamps are hidden.
    
+
    Feed
    
+
    rss_permalinks: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
    
+show_atom: Display ATOM feed button.
    
+
    Thumbnail
    
+
    enable_thumbnails: Enable or disable thumbnail display.
    
+enable_localcache: Enable or disable local cache.
    
+
    Redirector
    
+
    url: Redirector URL, such as anonym.to.
    
+encode_url: Enable this if the redirector needs encoded URL to work properly.
    
+
    Configuration file example
    
+
    <?php /*
+{
+    "credentials": {
+        "login": "<login>",
+        "hash": "<password hash>",
+        "salt": "<password salt>"
+    },
+    "security": {
+        "ban_after": 4,
+        "session_protection_disabled": false,
+        "ban_duration": 1800,
+        "trusted_proxies": [[](.html)
+            "1.2.3.4",
+            "5.6.7.8"
+        ]
+    },
+    "resources": {
+        "data_dir": "data",
+        "config": "data\/config.php",
+        "datastore": "data\/datastore.php",
+        "ban_file": "data\/ipbans.php",
+        "updates": "data\/updates.txt",
+        "log": "data\/log.txt",
+        "update_check": "data\/lastupdatecheck.txt",
+        "raintpl_tmp": "tmp\/",
+        "raintpl_tpl": "tpl\/",
+        "thumbnails_cache": "cache",
+        "page_cache": "pagecache"
+    },
+    "general": {
+        "check_updates": true,
+        "rss_permalinks": true,
+        "links_per_page": 20,
+        "default_private_links": true,
+        "enable_thumbnails": true,
+        "enable_localcache": true,
+        "check_updates_branch": "stable",
+        "check_updates_interval": 86400,
+        "enabled_plugins": [[](.html)
+            "markdown",
+            "wallabag",
+            "archiveorg"
+        ],
+        "timezone": "Europe\/Paris",
+        "title": "My Shaarli",
+        "header_link": "?"
+    },
+    "extras": {
+        "show_atom": false,
+        "hide_public_links": false,
+        "hide_timestamps": false,
+        "open_shaarli": false,
+        "redirector": "http://anonym.to/?",
+        "redirector_encode_url": false
+    },
+    "general": {
+        "header_link": "?",
+        "links_per_page": 20,
+        "enabled_plugins": [[](.html)
+            "markdown",
+            "wallabag"
+        ],
+        "timezone": "Europe\/Paris",
+        "title": "My Shaarli"
+    },
+    "updates": {
+        "check_updates": true,
+        "check_updates_branch": "stable",
+        "check_updates_interval": 86400
+    },
+    "feed": {
+        "rss_permalinks": true,
+        "show_atom": false
+    },
+    "privacy": {
+        "default_private_links": true,
+        "hide_public_links": false,
+        "hide_timestamps": false
+    },
+    "thumbnail": {
+        "enable_thumbnails": true,
+        "enable_localcache": true
+    },
+    "redirector": {
+        "url": "http://anonym.to/?",
+        "encode_url": false
+    },
+    "plugins": {
+        "WALLABAG_URL": "http://demo.wallabag.org",
+        "WALLABAG_VERSION": "1"
+    }
+} ?>
    
 
    Additional configuration
    
-
    The playvideos plugin may require that you adapt your server's Content Security Policy configuration to work properly.
    
+
    The playvideos plugin may require that you adapt your server's
    
+Content Security Policy 
    
+configuration to work properly.(.html)
    
 
 
diff --git a/doc/Shaarli-configuration.md b/doc/Shaarli-configuration.md
index d0560d79..4a783c0e 100644
--- a/doc/Shaarli-configuration.md
+++ b/doc/Shaarli-configuration.md
@@ -1,14 +1,18 @@
 #Shaarli configuration
+# Shaarli configuration
+
 ## Foreword
 
 **Do not edit configuration options in index.php! Your changes would be lost.** 
 
-Once your Shaarli instance is installed, the file `data/config.php` is generated:
-* it contains all settings, and can be edited to customize values
-* it defines which [plugins](Plugin-System) are enabled[](.html)
+Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
+* it contains all settings in JSON format, and can be edited to customize values
+* it defines which [plugins](Plugin-System) are enabled[(.html)]((.html).html)
 * its values override those defined in `index.php`
+* it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
 
 ## File and directory permissions
+
 The server process running Shaarli must have:
 - `read` access to the following resources:
     - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
@@ -29,123 +33,179 @@ On a Linux distribution:
 - to give it access to Shaarli, either:
     - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
     - put users in the same group as the web server, and set the appropriate access rights
-- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html)
-
-## Example `data/config.php`
-See also [Plugin System](Plugin-System.html).
-
-```php
-';[](.html)
-
-// User password hash
-$GLOBALS['hash'] = '200c452da46c2f889e5e48c49ef044bcacdcb095';[](.html)
-
-// Password salt
-$GLOBALS['salt'] = '13b654102321576033d8473b63a275a1bf94c0f0'; [](.html)
-
-// Local timezone
-$GLOBALS['timezone'] = 'Africa/Abidjan';[](.html)
-date_default_timezone_set('Africa/Abidjan');
-
-// Shaarli title
-$GLOBALS['title'] = 'My Little Shaarly';[](.html)
-
-// Link the Shaarli title points to
-$GLOBALS['titleLink'] = '?';[](.html)
-
-// HTTP referer redirector
-$GLOBALS['redirector'] = '';[](.html)
-
-// Disable session hijacking
-$GLOBALS['disablesessionprotection'] = false; [](.html)
-
-// Whether new links are private by default
-$GLOBALS['privateLinkByDefault'] = false;[](.html)
-
-// Enabled plugins
-// Note: each plugin may provide further settings through its own "config.php"
-$GLOBALS['config'['ENABLED_PLUGINS'] = array('addlink_toolbar', 'qrcode');]('ENABLED_PLUGINS']-=-array('addlink_toolbar',-'qrcode');.html)
-
-// Subdirectory where Shaarli stores its data files.
-// You can change it for better security.
-$GLOBALS['config'['DATADIR'] = 'data';]('DATADIR']-=-'data';.html)
-
-// File used to store settings
-$GLOBALS['config'['CONFIG_FILE'] = 'data/config.php';]('CONFIG_FILE']-=-'data/config.php';.html)
-
-// File containing the link database
-$GLOBALS['config'['DATASTORE'] = 'data/datastore.php';]('DATASTORE']-=-'data/datastore.php';.html)
-
-// Number of links displayed per page
-$GLOBALS['config'['LINKS_PER_PAGE'] = 20;]('LINKS_PER_PAGE']-=-20;.html)
-
-// File recording failed login attempts and IP bans
-$GLOBALS['config'['IPBANS_FILENAME'] = 'data/ipbans.php';]('IPBANS_FILENAME']-=-'data/ipbans.php';.html)
-
-// Failed login attempts before being banned
-$GLOBALS['config'['BAN_AFTER'] = 4;]('BAN_AFTER']-=-4;.html)
-
-// Duration of an IP ban, in seconds (30 minutes)
-$GLOBALS['config'['BAN_DURATION'] = 1800;]('BAN_DURATION']-=-1800;.html)
-
-// If set to true, everyone will be able to add, edit and remove links,
-// as well as change configuration
-$GLOBALS['config'['OPEN_SHAARLI'] = false;]('OPEN_SHAARLI']-=-false;.html)
-
-// Do not show link timestamps
-$GLOBALS['config'['HIDE_TIMESTAMPS'] = false;]('HIDE_TIMESTAMPS']-=-false;.html)
-
-// Set to false to disable local thumbnail cache, e.g. due to limited disk quotas
-$GLOBALS['config'['ENABLE_THUMBNAILS'] = true;]('ENABLE_THUMBNAILS']-=-true;.html)
-
-// Thumbnail cache directory
-$GLOBALS['config'['CACHEDIR'] = 'cache';]('CACHEDIR']-=-'cache';.html)
-
-// Enable feed (rss, atom, dailyrss) cache
-$GLOBALS['config'['ENABLE_LOCALCACHE'] = true;]('ENABLE_LOCALCACHE']-=-true;.html)
-
-// Feed cache directory
-$GLOBALS['config'['PAGECACHE'] = 'pagecache';]('PAGECACHE']-=-'pagecache';.html)
-
-// RainTPL cache directory (keep the trailing slash!)
-$GLOBALS['config'['RAINTPL_TMP'] = 'tmp/';]('RAINTPL_TMP']-=-'tmp/';.html)
-
-// RainTPL template directory (keep the trailing slash!)
-$GLOBALS['config'['RAINTPL_TPL'] = 'tpl/';]('RAINTPL_TPL']-=-'tpl/';.html)
-
-// Whether Shaarli checks for new releases at https://github.com/shaarli/Shaarli
-$GLOBALS['config'['ENABLE_UPDATECHECK'] = true;]('ENABLE_UPDATECHECK']-=-true;.html)
-
-// File to store the latest Shaarli version
-$GLOBALS['config'['UPDATECHECK_FILENAME'] = 'data/lastupdatecheck.txt';]('UPDATECHECK_FILENAME']-=-'data/lastupdatecheck.txt';.html)
-
-// Delay between version checks (requires to be logged in) (24 hours)
-$GLOBALS['config'['UPDATECHECK_INTERVAL'] = 86400;]('UPDATECHECK_INTERVAL']-=-86400;.html)
-
-// For each link, display a link to an archived version on archive.org
-$GLOBALS['config'['ARCHIVE_ORG'] = false;]('ARCHIVE_ORG']-=-false;.html)
-
-// The RSS item links point:
-// true   =>  directly to the link
-// false  =>  to the entry on Shaarli (permalink)
-$GLOBALS['config'['ENABLE_RSS_PERMALINKS'] = true;]('ENABLE_RSS_PERMALINKS']-=-true;.html)
-
-// Hide all links to non-logged users
-$GLOBALS['config'['HIDE_PUBLIC_LINKS'] = false;]('HIDE_PUBLIC_LINKS']-=-false;.html)
-
-$GLOBALS['config'['PUBSUBHUB_URL'] = '';]('PUBSUBHUB_URL']-=-'';.html)
-
-// Show an ATOM Feed button next to the Subscribe (RSS) button.
-// ATOM feeds are available at the address ?do=atom regardless of this option.
-$GLOBALS['config'['SHOW_ATOM'] = false;]('SHOW_ATOM']-=-false;.html)
-
-// Set this to true if the redirector requires encoded URL, false otherwise.
-$GLOBALS['config'['REDIRECTOR_URLENCODE'] = true;]('REDIRECTOR_URLENCODE']-=-true;.html)
-?>
+- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[(.html)]((.html).html)
+
+## Configuration
+
+In `data/config.json.php`.
+
+See also [Plugin System](Plugin-System.html).[](.html)
+
+### Credentials
+ 
+> You shouldn't edit those.
+
+**login**: Login username.  
+**hash**: Generated password hash.  
+**salt**: Password salt.
+
+### General
+
+**title**: Shaarli's instance title.  
+**header_link**: Link to the homepage.  
+**links_per_page**: Number of shaares displayed per page.  
+**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).  [](.html)
+**enabled_plugins**: List of enabled plugins.
+
+### Security
+
+**session_protection_disabled**: Disable session cookie hijacking protection (not recommended). 
+It might be useful if your IP adress often changes.  
+**ban_after**: Failed login attempts before being IP banned.  
+**ban_duration**: IP ban duration in seconds.  
+**open_shaarli**: Anyone can add a new link while logged out if enabled.  
+**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. 
+
+### Resources
+
+**data_dir**: Data directory.  
+**datastore**: Shaarli's links database file path.  
+**updates**: File path for the ran updates file.  
+**log**: Log file path.  
+**update_check**: Last update check file path.  
+**raintpl_tpl**: Templates directory.  
+**raintpl_tmp**: Template engine cache directory.  
+**thumbnails_cache**: Thumbnails cache directory.  
+**page_cache**: Shaarli's internal cache directory.  
+**ban_file**: Banned IP file path.
+
+### Updates
+
+**check_updates**: Enable or disable update check to the git repository.  
+**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).  
+**check_updates_interval**: Look for new version every N seconds (default: every day).
+
+### Privacy
+
+**default_private_links**: Check the private checkbox by default for every new link.  
+**hide_public_links**: All links are hidden while logged out.  
+**hide_timestamps**: Timestamps are hidden.
+
+### Feed
+
+**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.  
+**show_atom**: Display ATOM feed button.
+
+### Thumbnail
+
+**enable_thumbnails**: Enable or disable thumbnail display.  
+**enable_localcache**: Enable or disable local cache.
+
+### Redirector
+
+**url**: Redirector URL, such as `anonym.to`.  
+**encode_url**: Enable this if the redirector needs encoded URL to work properly.
+
+## Configuration file example
+
+```json
+",
+        "hash": "",
+        "salt": ""
+    },
+    "security": {
+        "ban_after": 4,
+        "session_protection_disabled": false,
+        "ban_duration": 1800,
+        "trusted_proxies": [[](.html)
+            "1.2.3.4",
+            "5.6.7.8"
+        ]
+    },
+    "resources": {
+        "data_dir": "data",
+        "config": "data\/config.php",
+        "datastore": "data\/datastore.php",
+        "ban_file": "data\/ipbans.php",
+        "updates": "data\/updates.txt",
+        "log": "data\/log.txt",
+        "update_check": "data\/lastupdatecheck.txt",
+        "raintpl_tmp": "tmp\/",
+        "raintpl_tpl": "tpl\/",
+        "thumbnails_cache": "cache",
+        "page_cache": "pagecache"
+    },
+    "general": {
+        "check_updates": true,
+        "rss_permalinks": true,
+        "links_per_page": 20,
+        "default_private_links": true,
+        "enable_thumbnails": true,
+        "enable_localcache": true,
+        "check_updates_branch": "stable",
+        "check_updates_interval": 86400,
+        "enabled_plugins": [[](.html)
+            "markdown",
+            "wallabag",
+            "archiveorg"
+        ],
+        "timezone": "Europe\/Paris",
+        "title": "My Shaarli",
+        "header_link": "?"
+    },
+    "extras": {
+        "show_atom": false,
+        "hide_public_links": false,
+        "hide_timestamps": false,
+        "open_shaarli": false,
+        "redirector": "http://anonym.to/?",
+        "redirector_encode_url": false
+    },
+    "general": {
+        "header_link": "?",
+        "links_per_page": 20,
+        "enabled_plugins": [[](.html)
+            "markdown",
+            "wallabag"
+        ],
+        "timezone": "Europe\/Paris",
+        "title": "My Shaarli"
+    },
+    "updates": {
+        "check_updates": true,
+        "check_updates_branch": "stable",
+        "check_updates_interval": 86400
+    },
+    "feed": {
+        "rss_permalinks": true,
+        "show_atom": false
+    },
+    "privacy": {
+        "default_private_links": true,
+        "hide_public_links": false,
+        "hide_timestamps": false
+    },
+    "thumbnail": {
+        "enable_thumbnails": true,
+        "enable_localcache": true
+    },
+    "redirector": {
+        "url": "http://anonym.to/?",
+        "encode_url": false
+    },
+    "plugins": {
+        "WALLABAG_URL": "http://demo.wallabag.org",
+        "WALLABAG_VERSION": "1"
+    }
+} ?>
 ```
 
 ## Additional configuration
 
-The playvideos plugin may require that you adapt your server's [Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) configuration to work properly.[](.html)
+The playvideos plugin may require that you adapt your server's 
+[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) [](.html)
+configuration to work properly.[(.html)]((.html).html)
+
diff --git a/doc/Shaarli-installation.html b/doc/Shaarli-installation.html
deleted file mode 100644
index 487ec1db..00000000
--- a/doc/Shaarli-installation.html
+++ /dev/null
@@ -1,72 +0,0 @@
-
-
-
-  
-  
-  
-  Shaarli – Shaarli installation
-  
-  
-  
-
-
-
-
    Shaarli installation
    
-
    Once Shaarli is downloaded and installed behind a web server, open it in your favorite browser.
    
-
    install screenshot
    
-
    Setup your Shaarli installation, and it's ready to use!
    
-
-
diff --git a/doc/Shaarli-installation.md b/doc/Shaarli-installation.md
deleted file mode 100644
index be9726e0..00000000
--- a/doc/Shaarli-installation.md
+++ /dev/null
@@ -1,6 +0,0 @@
-#Shaarli installation
-Once Shaarli is downloaded and installed behind a web server, open it in your favorite browser.
-
-![install screenshot](http://i.imgur.com/wuMpDSN.png)[](.html)
-
-Setup your Shaarli installation, and it's ready to use!
diff --git a/doc/Sharing-button.html b/doc/Sharing-button.html
index 3770d8ad..93710efe 100644
--- a/doc/Sharing-button.html
+++ b/doc/Sharing-button.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/Static-analysis.html b/doc/Static-analysis.html
index 86cb4696..d964e917 100644
--- a/doc/Static-analysis.html
+++ b/doc/Static-analysis.html
@@ -15,13 +15,13 @@
 
diff --git a/doc/TODO.html b/doc/TODO.html
deleted file mode 100644
index 04224dbf..00000000
--- a/doc/TODO.html
+++ /dev/null
@@ -1,74 +0,0 @@
-
-
-
-  
-  
-  
-  Shaarli – TODO
-  
-  
-  
-
-
-
-
    TODO
    
-
      
-
    • add more screenshots
      • 
-
    • improve developer documentation: storage architecture, classes and functions, security handling...
      • 
-
    • add server configuration examples: lighthttpd
      • 
-
    
-
-
diff --git a/doc/TODO.md b/doc/TODO.md
deleted file mode 100644
index fb72fd57..00000000
--- a/doc/TODO.md
+++ /dev/null
@@ -1,4 +0,0 @@
-#TODO
-* add more screenshots
-* improve developer documentation: storage architecture, classes and functions, security handling...
-* add server configuration examples: lighthttpd
diff --git a/doc/Theming.html b/doc/Theming.html
index 27c5d863..13e6acf0 100644
--- a/doc/Theming.html
+++ b/doc/Theming.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -132,6 +130,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
  • kalvn/shaarli-blocks - A template/theme for Shaarli
    • 
 
  • kalvn/Shaarli-Material - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.
    • 
 
  • misterair/Limonade - A fork of (legacy) Shaarli with a new template
    • 
+
  • mrjovanovic/serious-theme-shaarli - A serious theme for SHaarli.
    • 
 
  • Vinm/Blue-theme-for Shaarli - A template/theme for Shaarli (unmaintained, compatibility unknown)
    • 
 
  • vivienhaese/shaarlitheme - A Shaarli fork meant to be run in an openshift instance
    • 
 
@@ -142,17 +141,17 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
  • user sites are enabled, e.g. /home/user/public_html/somedir is served as http://localhost/~user/somedir
    • 
 
  • http is the name of the Apache user
    • 
 
-
    $ cd ~/public_html
+
    $ cd ~/public_html
 
 # clone repositories
-$ git clone https://github.com/shaarli/Shaarli.git shaarli
-$ pushd shaarli/tpl
-$ git clone https://github.com/alexisju/albinomouse-template.git
-$ popd
+$ git clone https://github.com/shaarli/Shaarli.git shaarli
+$ pushd shaarli/tpl
+$ git clone https://github.com/alexisju/albinomouse-template.git
+$ popd
 
 # set access rights for Apache
-$ chgrp -R http shaarli
-$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
    
+$ chgrp -R http shaarli
+$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
    
 
    Get config written:
    
 
      
 
    • go to the freshly installed site
      • 
@@ -161,6 +160,6 @@ $ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli
 
    
 
    Edit Shaarli's configuration|Shaarli configuration:
    
 
    # the file should be owned by Apache, thus not writeable => sudo
-$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
    
+$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
    
 
 
diff --git a/doc/Theming.md b/doc/Theming.md
index 9dfdcf9f..7fb8d927 100644
--- a/doc/Theming.md
+++ b/doc/Theming.md
@@ -28,6 +28,7 @@ $GLOBALS['config'['RAINTPL_TPL'] = 'tpl/my-template/';]('RAINTPL_TPL']-=-'tpl/my
 - [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli[](.html)
 - [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.[](.html)
 - [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template[](.html)
+- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for SHaarli.[](.html)
 - [Vinm/Blue-theme-for Shaarli](https://github.com/Vinm/Blue-theme-for-Shaarli) - A template/theme for Shaarli ([unmaintained](https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2), compatibility unknown)[](.html)
 - [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance[](.html)
 
diff --git a/doc/Troubleshooting.html b/doc/Troubleshooting.html
index 3de8ad1e..ed1c6f09 100644
--- a/doc/Troubleshooting.html
+++ b/doc/Troubleshooting.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -132,6 +130,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
      
 
    • false (default): real referer
      • 
 
    • true: spoof referer (use target URI as referer)
      • 
+
    • known to break some functionality in Shaarli
      • 
 
    
 
    network.http.referer.trimmingPolicy - trim the URI not to send a full Referer
    
 
      
@@ -140,7 +139,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
    • 2: scheme+host+port
      • 
 
    
 
    Firefox, localhost and redirections
    
-
    localhost is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or anly accept requests from the same base domain/host, Shaarli redirections will not work properly.
    
+
    localhost is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
    
 
    To solve this, assign a local domain to your host, e.g.
    
 
    127.0.0.1 localhost desktop localhost.lan
 ::1       localhost desktop localhost.lan
    
diff --git a/doc/Troubleshooting.md b/doc/Troubleshooting.md
index e91fe846..8e30fce5 100644
--- a/doc/Troubleshooting.md
+++ b/doc/Troubleshooting.md
@@ -25,6 +25,7 @@ HTTP settings are available by browsing `about:config`, here are the available s
 `network.http.referer.spoofSource` - Referer spoofing (~faking)
 - false (default): real referer
 - true: spoof referer (use target URI as referer)
+  - known to break some functionality in Shaarli
 
 `network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
 - 0 (default): send full URI
@@ -32,7 +33,7 @@ HTTP settings are available by browsing `about:config`, here are the available s
 - 2: scheme+host+port
 
 ### Firefox, localhost and redirections
-`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or anly accept requests from the same base domain/host, Shaarli redirections will not work properly.
+`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
 
 To solve this, assign a local domain to your host, e.g.
 ```
diff --git a/doc/Unit-tests.html b/doc/Unit-tests.html
index 7934e346..266fd33a 100644
--- a/doc/Unit-tests.html
+++ b/doc/Unit-tests.html
@@ -52,13 +52,13 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
@@ -111,87 +109,87 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
 
    Sample usage
    
 
    # system-wide version
-$ composer install
-$ composer update
+$ composer install
+$ composer update
 
 # local version
-$ php composer.phar self-update
-$ php composer.phar install
-$ php composer.phar update
    
+$ php composer.phar self-update
+$ php composer.phar install
+$ php composer.phar update

    Install Shaarli dev dependencies

    -
    $ cd /path/to/shaarli
-$ composer update
    +
    $ cd /path/to/shaarli
+$ composer update

    Install and enable Xdebug to generate PHPUnit coverage reports

    For Debian-based distros:

    -
    $ aptitude install php5-xdebug
    +
    $ aptitude install php5-xdebug

    For ArchLinux:

    -
    $ pacman -S xdebug
    +
    $ pacman -S xdebug

    Then add the following line to /etc/php/php.ini:

    zend_extension=xdebug.so

    Run unit tests

    Successful test suite:

    -
    $ make test
+
    $ make test
 
--------
-PHPUNIT
--------
-PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
+-------
+PHPUNIT
+-------
+PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
 
-Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
+Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
 
-....................................
+....................................
 
-Time: 759 ms, Memory: 8.25Mb
+Time: 759 ms, Memory: 8.25Mb
 
-OK (36 tests, 65 assertions)
    
+OK (36 tests, 65 assertions)

    Test suite with failures and errors:

    -
    $ make test
--------
-PHPUNIT
--------
-PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
+
    $ make test
+-------
+PHPUNIT
+-------
+PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
 
-Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
+Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
 
-E..FF...............................
+E..FF...............................
 
-Time: 802 ms, Memory: 8.25Mb
+Time: 802 ms, Memory: 8.25Mb
 
-There was 1 error:
+There was 1 error:
 
-1) LinkDBTest::testConstructLoggedIn
-Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
+1) LinkDBTest::testConstructLoggedIn
+Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
 DBTest.php on line 79 and defined
 
-/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
-/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
+/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
+/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
 
---
+--
 
-There were 2 failures:
+There were 2 failures:
 
-1) LinkDBTest::testCheckDBNew
-Failed asserting that two strings are equal.
---- Expected
-+++ Actual
-@@ @@
--'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
-+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
+1) LinkDBTest::testCheckDBNew
+Failed asserting that two strings are equal.
+--- Expected
++++ Actual
+@@ @@
+-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
++'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
 
-/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
+/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
 
-2) LinkDBTest::testCheckDBLoad
-Failed asserting that two strings are equal.
---- Expected
-+++ Actual
-@@ @@
--'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
-+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
+2) LinkDBTest::testCheckDBLoad
+Failed asserting that two strings are equal.
+--- Expected
++++ Actual
+@@ @@
+-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
++'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
 
-/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
+/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
 
-FAILURES!
-Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
    
+FAILURES!
+Tests: 36, Assertions: 63, Errors: 1, Failures: 2.

    Test results and coverage

    By default, PHPUnit will run all suitable tests found under the tests directory.

    Each test has 3 possible outcomes:

    diff --git a/doc/Upgrade-and-migration.html b/doc/Upgrade-and-migration.html new file mode 100644 index 00000000..a5b041d5 --- /dev/null +++ b/doc/Upgrade-and-migration.html @@ -0,0 +1,242 @@ + + + + + + + Shaarli – Upgrade and migration + + + + + + + +

    Upgrade and migration

    +

    Preparation

    +

    Backup your data

    +

    Shaarli stores all user data under the data directory:

    +
      +
    • data/config.php - main configuration file
      • +
    • data/datastore.php - bookmarked links
      • +
    • data/ipbans.php - banned IP addresses
      • +
    +

    See Shaarli configuration for more information about Shaarli resources.

    +

    It is recommended to backup this repository before starting updating/upgrading Shaarli:

    +
      +
    • users with SSH access: copy or archive the directory to a temporary location
      • +
    • users with FTP access: download a local copy of your Shaarli installation using your favourite client
      • +
    +

    Migrating data from a previous installation

    +

    As all user data is kept under data, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:

    +
      +
    • backup the data directory
      • +
    • install or update Shaarli: +
      • +
    • check or restore the data directory
      • +
    +

    Upgrading from release archives

    +

    All tagged revisions can be downloaded as tarballs or ZIP archives from the releases page.

    +

    We recommend using the releases from the stable branch, which are available as:

    + +

    Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the data directory!

    +

    After upgrading, 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 for more details).

    +

    Upgrading with Git

    +

    Updating a community Shaarli

    +

    If you have installed Shaarli from the community Git repository, simply pull new changes from your local clone:

    +
    $ cd /path/to/shaarli
+$ git pull
+
+From github.com:shaarli/Shaarli
+ * branch            master     -> FETCH_HEAD
+Updating ebd67c6..521f0e6
+Fast-forward
+ application/Url.php   | 1 +
+ shaarli_version.php   | 2 +-
+ tests/Url/UrlTest.php | 1 +
+ 3 files changed, 3 insertions(+), 1 deletion(-)
    +

    Shaarli >= v0.8.x: install/update third-party PHP dependencies using Composer:

    +
    $ composer update --no-dev
+
+Loading composer repositories with package information
+Updating dependencies
+  - Installing shaarli/netscape-bookmark-parser (v1.0.1)
+    Downloading: 100%
    +

    Migrating and upgrading from Sebsauvage's repository

    +

    If you have installed Shaarli from Sebsauvage's original Git repository, you can use Git remotes to update your working copy.

    +

    The following guide assumes that:

    +
      +
    • you have a basic knowledge of Git branching and remote repositories
      • +
    • the default remote is named origin and points to Sebsauvage's repository
      • +
    • the current branch is master +
        +
      • if you have personal branches containing customizations, you will need to rebase them after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break
        • +
      • +
    • the working copy is clean: +
        +
      • no versioned file has been locally modified
        • +
      • no untracked files are present
        • +
      • +
    +

    Step 0: show repository information

    +
    $ cd /path/to/shaarli
+
+$ git remote -v
+origin  https://github.com/sebsauvage/Shaarli (fetch)
+origin  https://github.com/sebsauvage/Shaarli (push)
+
+$ git branch -vv
+* master 029f75f [origin/master] Update README.md[](.html)
+
+$ git status
+On branch master
+Your branch is up-to-date with 'origin/master'.
+nothing to commit, working directory clean
    +

    Step 1: update Git remotes

    +
    $ git remote rename origin sebsauvage
+$ git remote -v
+sebsauvage  https://github.com/sebsauvage/Shaarli (fetch)
+sebsauvage  https://github.com/sebsauvage/Shaarli (push)
+
+$ git remote add origin https://github.com/shaarli/Shaarli
+$ git fetch origin
+
+remote: Counting objects: 3015, done.
+remote: Compressing objects: 100% (19/19), done.
+remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
+Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
+Resolving deltas: 100% (1899/1899), completed with 48 local objects.
+From https://github.com/shaarli/Shaarli
+ * [new branch]      master     -> origin/master[](.html)
+ * [new branch]      stable     -> origin/stable[](.html)
+[...][](.html)
+ * [new tag]         v0.6.4     -> v0.6.4[](.html)
+ * [new tag]         v0.7.0     -> v0.7.0[](.html)
    +

    Step 2: use the stable community branch

    +
    $ git checkout origin/stable -b stable
+Branch stable set up to track remote branch stable from origin.
+Switched to a new branch 'stable'
+
+$ git branch -vv
+  master 029f75f [sebsauvage/master] Update README.md[](.html)
+* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html)
    +

    Shaarli >= v0.8.x: install/update third-party PHP dependencies using Composer:

    +
    $ composer update --no-dev
+
+Loading composer repositories with package information
+Updating dependencies
+  - Installing shaarli/netscape-bookmark-parser (v1.0.1)
+    Downloading: 100%
    +

    Optionally, you can delete information related to the legacy version:

    +
    $ git branch -D master
+Deleted branch master (was 029f75f).
+
+$ git remote remove sebsauvage
+
+$ git remote -v
+origin  https://github.com/shaarli/Shaarli (fetch)
+origin  https://github.com/shaarli/Shaarli (push)
+
+$ git gc
+Counting objects: 3317, done.
+Delta compression using up to 8 threads.
+Compressing objects: 100% (1237/1237), done.
+Writing objects: 100% (3317/3317), done.
+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 for more details).

    + + diff --git a/doc/Upgrade-and-migration.md b/doc/Upgrade-and-migration.md new file mode 100644 index 00000000..0bc33824 --- /dev/null +++ b/doc/Upgrade-and-migration.md @@ -0,0 +1,161 @@ +#Upgrade and migration +## Preparation +### Backup your data + +Shaarli stores all user data under the `data` directory: +- `data/config.php` - main configuration file +- `data/datastore.php` - bookmarked links +- `data/ipbans.php` - banned IP addresses + +See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources. + +It is recommended to backup this repository _before_ starting updating/upgrading Shaarli: +- users with SSH access: copy or archive the directory to a temporary location +- users with FTP access: download a local copy of your Shaarli installation using your favourite client + +### Migrating data from a previous installation +As all user data is kept under `data`, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps: + +- backup the `data` directory +- install or update Shaarli: + - fresh installation - see [Download and installation](Download-and-installation.html) + - update - see the following sections +- check or restore the `data` directory + +## Upgrading from release archives +All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html) + +We _recommend_ using the releases from the `stable` branch, which are available as: +- gzipped tarball - https://github.com/shaarli/Shaarli/archive/stable.tar.gz +- ZIP archive - https://github.com/shaarli/Shaarli/archive/stable.zip + +Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the `data` directory! + +After upgrading, 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.html) for more details). + +## Upgrading with Git +### Updating a community Shaarli +If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:[](.html) + +```bash +$ cd /path/to/shaarli +$ git pull + +From github.com:shaarli/Shaarli + * branch master -> FETCH_HEAD +Updating ebd67c6..521f0e6 +Fast-forward + application/Url.php | 1 + + shaarli_version.php | 2 +- + tests/Url/UrlTest.php | 1 + + 3 files changed, 3 insertions(+), 1 deletion(-) +``` + +Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html) + +```bash +$ composer update --no-dev + +Loading composer repositories with package information +Updating dependencies + - Installing shaarli/netscape-bookmark-parser (v1.0.1) + Downloading: 100% +``` + +### 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.[](.html) + +The following guide assumes that: +- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)[](.html) +- the default remote is named `origin` and points to Sebsauvage's repository +- the current branch is `master` + - if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break![](.html) +- the working copy is clean: + - no versioned file has been locally modified + - no untracked files are present + +#### Step 0: show repository information +```bash +$ cd /path/to/shaarli + +$ git remote -v +origin https://github.com/sebsauvage/Shaarli (fetch) +origin https://github.com/sebsauvage/Shaarli (push) + +$ git branch -vv +* master 029f75f [origin/master] Update README.md[](.html) + +$ git status +On branch master +Your branch is up-to-date with 'origin/master'. +nothing to commit, working directory clean +``` + +#### Step 1: update Git remotes +``` +$ git remote rename origin sebsauvage +$ git remote -v +sebsauvage https://github.com/sebsauvage/Shaarli (fetch) +sebsauvage https://github.com/sebsauvage/Shaarli (push) + +$ git remote add origin https://github.com/shaarli/Shaarli +$ git fetch origin + +remote: Counting objects: 3015, done. +remote: Compressing objects: 100% (19/19), done. +remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550 +Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done. +Resolving deltas: 100% (1899/1899), completed with 48 local objects. +From https://github.com/shaarli/Shaarli + * [new branch] master -> origin/master[](.html) + * [new branch] stable -> origin/stable[](.html) +[...][](.html) + * [new tag] v0.6.4 -> v0.6.4[](.html) + * [new tag] v0.7.0 -> v0.7.0[](.html) +``` + +#### Step 2: use the stable community branch + +```bash +$ git checkout origin/stable -b stable +Branch stable set up to track remote branch stable from origin. +Switched to a new branch 'stable' + +$ git branch -vv + master 029f75f [sebsauvage/master] Update README.md[](.html) +* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html) +``` + +Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html) + +```bash +$ composer update --no-dev + +Loading composer repositories with package information +Updating dependencies + - Installing shaarli/netscape-bookmark-parser (v1.0.1) + Downloading: 100% +``` + +Optionally, you can delete information related to the legacy version: + +```bash +$ git branch -D master +Deleted branch master (was 029f75f). + +$ git remote remove sebsauvage + +$ git remote -v +origin https://github.com/shaarli/Shaarli (fetch) +origin https://github.com/shaarli/Shaarli (push) + +$ git gc +Counting objects: 3317, done. +Delta compression using up to 8 threads. +Compressing objects: 100% (1237/1237), done. +Writing objects: 100% (3317/3317), done. +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.html) for more details). diff --git a/doc/Upgrade-from-original-sebsauvage-Shaarli.html b/doc/Upgrade-from-original-sebsauvage-Shaarli.html deleted file mode 100644 index db69a0ed..00000000 --- a/doc/Upgrade-from-original-sebsauvage-Shaarli.html +++ /dev/null @@ -1,74 +0,0 @@ - - - - - - - Shaarli – Upgrade from original sebsauvage Shaarli - - - - - - -

    Upgrade from original sebsauvage Shaarli

    -
      -
    • Backup your original data/ directory.
      • -
    • Install and setup the Shaarli community fork.
      • -
    • Copy your original data directory over the new installation.
      • -
    - - diff --git a/doc/Upgrade-from-original-sebsauvage-Shaarli.md b/doc/Upgrade-from-original-sebsauvage-Shaarli.md deleted file mode 100644 index 6ae0c67b..00000000 --- a/doc/Upgrade-from-original-sebsauvage-Shaarli.md +++ /dev/null @@ -1,4 +0,0 @@ -#Upgrade from original sebsauvage Shaarli - * Backup your original `data/` directory. - * [Install](https://github.com/shaarli/Shaarli#installation--upgrade) and setup the Shaarli community fork.[](.html) - * Copy your original `data` directory over the new installation. diff --git a/doc/Usage.html b/doc/Usage.html index 2befaa02..63f21d93 100644 --- a/doc/Usage.html +++ b/doc/Usage.html @@ -15,13 +15,13 @@ diff --git a/doc/_Footer.html b/doc/_Footer.html index a054cc53..e8a62d2a 100644 --- a/doc/_Footer.html +++ b/doc/_Footer.html @@ -15,13 +15,13 @@ -

    _Footer
    -Shaarli, the personal, minimalist, super-fast, no-database delicious clone

    +

    _Footer
    +Shaarli, the personal, minimalist, super-fast, database-free bookmarking service

    diff --git a/doc/_Footer.md b/doc/_Footer.md index 29c39bb6..50fa4f56 100644 --- a/doc/_Footer.md +++ b/doc/_Footer.md @@ -1,2 +1,2 @@ #_Footer -_Shaarli, the personal, minimalist, super-fast, no-database delicious clone_ +_Shaarli, the personal, minimalist, super-fast, database-free bookmarking service_ diff --git a/doc/_Sidebar.html b/doc/_Sidebar.html index 89c2cf8a..bb6dad93 100644 --- a/doc/_Sidebar.html +++ b/doc/_Sidebar.html @@ -15,13 +15,13 @@

    _Sidebar

    Mobile Apps

      @@ -107,6 +108,7 @@

      Alternatives to Shaarli

        diff --git a/doc/Community-&-Related-software.md b/doc/Community-&-Related-software.md index 3945d005..291bf643 100644 --- a/doc/Community-&-Related-software.md +++ b/doc/Community-&-Related-software.md @@ -20,10 +20,11 @@ _TODO: contact repos owners to see if they'd like to standardize their work with * [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.[](.html) * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.[](.html) - * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.[](.html) + * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.[](.html) * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.[](.html) * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.[](.html) - * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.[](.html) + * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.[](.html) + * [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli[](.html) ### Themes @@ -35,7 +36,7 @@ See [Theming](Theming.html) for the list of community-contributed themes, and an - [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: [shaarli.fr](http://shaarli.fr/))[](.html) - [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis[](.html) - [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli[](.html) -- [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. An [another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for others shaarli (but use most ressources).[](.html) +- [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).[](.html) ### Mobile Apps - [Shaarli💫](http://app.mro.name/Shaarli💫) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes,[](.html) @@ -45,6 +46,7 @@ See [Theming](Theming.html) for the list of community-contributed themes, and an ## Integration with other platforms - [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [TinyTiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli[](.html) - [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar[](.html) +- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle[](.html) ## Alternatives to Shaarli - [Shaarli alternatives](http://alternativeto.net/software/shaarli/) (alternativeto.net)[](.html) diff --git a/doc/Download-and-Installation.html b/doc/Download-and-Installation.html index 17c7b69e..b9cac360 100644 --- a/doc/Download-and-Installation.html +++ b/doc/Download-and-Installation.html @@ -105,13 +105,14 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

        Several releases are available:

        -

        Get the latest released version from the releases page.

        -

        The current latest released version is v0.7.0.

        Download as an archive

        -

        As a .zip archive:

        -
        $ wget https://github.com/shaarli/Shaarli/archive/v0.7.0.zip
-$ unzip Shaarli-v0.7.0.zip
-$ mv Shaarli-v0.7.0 /path/to/shaarli/
        +

        Get the latest released version from the releases page.

        +

        Download our shaarli-full archive to include dependencies.

        +

        The current latest released version is v0.8.0

        +

        Or in command lines:

        +
        $ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.0/shaarli-v0.8.0-full.zip
+$ unzip shaarli-v0.8.0-full.zip
+$ mv Shaarli /path/to/shaarli/
        @@ -126,6 +127,10 @@ $ mv Shaarli-v0.7.0 /path/to/shaarli/
        +

        Using git

        +
        mkdir -p /path/to/shaarli && cd /path/to/shaarli/
+git clone -b v0.8.0 https://github.com/shaarli/Shaarli.git .
+composer update --no-dev

        Stable version

        The stable version has been experienced by Shaarli users, and will receive security updates.

        diff --git a/doc/Download-and-Installation.md b/doc/Download-and-Installation.md index 77af25eb..32df8984 100644 --- a/doc/Download-and-Installation.md +++ b/doc/Download-and-Installation.md @@ -8,26 +8,31 @@ Several releases are available: -------------------------------------------------------- ## Latest release (recommended) - +### Download as an archive Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html) -The current latest released version is `v0.7.0`. +**Download our *shaarli-full* archive** to include dependencies. -### Download as an archive +The current latest released version is `v0.8.0` -As a .zip archive: +Or in command lines: ```bash -$ wget https://github.com/shaarli/Shaarli/archive/v0.7.0.zip -$ unzip Shaarli-v0.7.0.zip -$ mv Shaarli-v0.7.0 /path/to/shaarli/ +$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.0/shaarli-v0.8.0-full.zip +$ unzip shaarli-v0.8.0-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).|[](.html) |-----|--------------------------| +### Using git +``` +mkdir -p /path/to/shaarli && cd /path/to/shaarli/ +git clone -b v0.8.0 https://github.com/shaarli/Shaarli.git . +composer update --no-dev +``` -------------------------------------------------------- diff --git a/doc/Release-Shaarli.html b/doc/Release-Shaarli.html index cdefd3d6..0d9fa3e1 100644 --- a/doc/Release-Shaarli.html +++ b/doc/Release-Shaarli.html @@ -115,9 +115,35 @@ releases.

      • origin pointing to your GitHub fork
      • upstream pointing to the main Shaarli repository
      -
    • maintainer permissions on the main Shaarli repository (to push the signed tag)
      • +
    • maintainer permissions on the main Shaarli repository, to: +
        +
      • push the signed tag
        • +
      • create a new release
        • +
    • Composer and Pandoc need to be installed
    +

    GitHub release draft and CHANGELOG.md

    +

    See http://keepachangelog.com/en/0.3.0/ for changelog formatting.

    +

    GitHub release draft

    +

    GitHub allows drafting the release note for the upcoming release, from the Releases page. This way, the release note can be drafted while contributions are merged to master.

    +

    CHANGELOG.md

    +

    This file should contain the same information as the release note draft for the upcoming version.

    +

    Update it to:

    +
      +
    • add new entries (additions, fixes, etc.)
      • +
    • mark the current version as released by setting its date and link
      • +
    • add a new section for the future unreleased version
      • +
    +
    $ cd /path/to/shaarli
+
+$ nano CHANGELOG.md
+
+[...][](.html)
+## vA.B.C - UNRELEASED
+TBA
+
+## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD[](.html)
+[...][](.html)

    Increment the version code, create and push a signed tag

    Bump Shaarli's version

    $ cd /path/to/shaarli
@@ -165,7 +191,16 @@ $ git show-ref tags/v0.5.0
 $ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
 gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
 gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)
    -

    Generate and upload all-in-one release archives

    +

    Publish the GitHub release

    +

    Create a GitHub release from a Git tag

    +

    From the previously drafted release:

    +
      +
    • edit the release notes (if needed)
      • +
    • specify the appropriate Git tag
      • +
    • publish the release
      • +
    • profit!
      • +
    +

    Generate and upload all-in-one release archives

    Users with a shared hosting may have:

    • no SSH access
      • diff --git a/doc/Release-Shaarli.md b/doc/Release-Shaarli.md index 5cbcd79a..556a96ee 100644 --- a/doc/Release-Shaarli.md +++ b/doc/Release-Shaarli.md @@ -10,9 +10,39 @@ This guide assumes that you have: - a local clone of your Shaarli fork, with the following remotes: - `origin` pointing to your GitHub fork - `upstream` pointing to the main Shaarli repository -- maintainer permissions on the main Shaarli repository (to push the signed tag) +- maintainer permissions on the main Shaarli repository, to: + - push the signed tag + - create a new release - [Composer](https://getcomposer.org/) and [Pandoc](http://pandoc.org/) need to be installed[](.html) +## GitHub release draft and `CHANGELOG.md` +See http://keepachangelog.com/en/0.3.0/ for changelog formatting. + +### GitHub release draft +GitHub allows drafting the release note for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`.[](.html) + +### `CHANGELOG.md` +This file should contain the same information as the release note draft for the upcoming version. + +Update it to: +- add new entries (additions, fixes, etc.) +- mark the current version as released by setting its date and link +- add a new section for the future unreleased version + +```bash +$ cd /path/to/shaarli + +$ nano CHANGELOG.md + +[...][](.html) +## vA.B.C - UNRELEASED +TBA + +## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD[](.html) +[...][](.html) +``` + + ## Increment the version code, create and push a signed tag ### Bump Shaarli's version ```bash @@ -72,7 +102,15 @@ gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F gpg: Good signature from "VirtualTam " [ultimate][](.html) ``` -## Generate and upload all-in-one release archives +## Publish the GitHub release +### Create a GitHub release from a Git tag +From the previously drafted release: +- edit the release notes (if needed) +- specify the appropriate Git tag +- publish the release +- profit! + +### Generate and upload all-in-one release archives Users with a shared hosting may have: - no SSH access - no possibility to install PHP packages or server extensions diff --git a/doc/Server-configuration.html b/doc/Server-configuration.html index 068900b8..2f1c25b5 100644 --- a/doc/Server-configuration.html +++ b/doc/Server-configuration.html @@ -193,6 +193,9 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf ErrorLog /var/log/apache2/shaarli-error.log CustomLog /var/log/apache2/shaarli-access.log combined </VirtualHost> +

      .htaccess

      +

      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.

      +

      Warning: If you use Apache 2.2 or lower, you need mod_version to be installed and enabled.

      LightHttpd

      Nginx

      Foreword

      @@ -233,7 +236,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • files may be located in a user's home directory
    • in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
    -

    For all following examples, a development configuration will be used:

    +

    For all following configuration examples, this user/group pair will be used:

    • user:group = john:users,
    @@ -251,6 +254,24 @@ user john users; http { [...][](.html) } +

    (Optional) Increase the maximum file upload size

    +

    Some bookmark dumps generated by web browsers can be huge due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.

    +

    To increase upload size, you will need to modify both nginx and PHP configuration:

    +
    # /etc/nginx/nginx.conf
+
+http {
+    [...][](.html)
+
+    client_max_body_size 10m;
+
+    [...][](.html)
+}
    +
    # /etc/php5/fpm/php.ini
+
+[...][](.html)
+post_max_size = 10M
+[...][](.html)
+upload_max_filesize = 10M

    Minimal

    WARNING: Use for development only!

    user john users;
@@ -350,6 +371,11 @@ http {
             error_log   /var/log/nginx/shaarli.error.log;
         }
 
+        location = /shaarli/favicon.ico {
+            # serve the Shaarli favicon from its custom location
+            alias /var/www/shaarli/images/favicon.ico;
+        }
+
         include deny.conf;
         include static_assets.conf;
         include php.conf;
@@ -403,6 +429,11 @@ http {
             error_log   /var/log/nginx/shaarli.error.log;
         }
 
+        location = /shaarli/favicon.ico {
+            # serve the Shaarli favicon from its custom location
+            alias /var/www/shaarli/images/favicon.ico;
+        }
+
         include deny.conf;
         include static_assets.conf;
         include php.conf;
diff --git a/doc/Server-configuration.md b/doc/Server-configuration.md
index 1ab57a0a..df10feb2 100644
--- a/doc/Server-configuration.md
+++ b/doc/Server-configuration.md
@@ -102,6 +102,12 @@ See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
 
 ```
 
+### .htaccess
+
+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.
+
+**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.[](.html)
+
 ## LightHttpd
 
 ## Nginx
@@ -136,7 +142,7 @@ On a development server:
 - files may be located in a user's home directory
 - in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
 
-For all following examples, a development configuration will be used:
+For all following configuration examples, this user/group pair will be used:
 - `user:group = john:users`,
 
 which corresponds to the following service configuration:
@@ -160,6 +166,32 @@ http {
 }
 ```
 
+### (Optional) Increase the maximum file upload size
+Some bookmark dumps generated by web browsers can be _huge_ due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
+
+To increase upload size, you will need to modify both nginx and PHP configuration:
+
+```nginx
+# /etc/nginx/nginx.conf
+
+http {
+    [...][](.html)
+
+    client_max_body_size 10m;
+
+    [...][](.html)
+}
+```
+
+```ini
+# /etc/php5/fpm/php.ini
+
+[...][](.html)
+post_max_size = 10M
+[...][](.html)
+upload_max_filesize = 10M
+```
+
 ### Minimal
 _WARNING: Use for development only!_ 
 
@@ -271,6 +303,11 @@ http {
             error_log   /var/log/nginx/shaarli.error.log;
         }
 
+        location = /shaarli/favicon.ico {
+            # serve the Shaarli favicon from its custom location
+            alias /var/www/shaarli/images/favicon.ico;
+        }
+
         include deny.conf;
         include static_assets.conf;
         include php.conf;
@@ -328,6 +365,11 @@ http {
             error_log   /var/log/nginx/shaarli.error.log;
         }
 
+        location = /shaarli/favicon.ico {
+            # serve the Shaarli favicon from its custom location
+            alias /var/www/shaarli/images/favicon.ico;
+        }
+
         include deny.conf;
         include static_assets.conf;
         include php.conf;
diff --git a/doc/Theming.html b/doc/Theming.html
index 13e6acf0..7cbf7aef 100644
--- a/doc/Theming.html
+++ b/doc/Theming.html
@@ -119,19 +119,20 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
      
 
    • There should now be a my-template/ directory under the tpl/ dir, containing directly all the template files.
      • 
 
    
-
  • Edit data/config.php to have Shaarli use this template, e.g.
    
-
    $GLOBALS['config'['RAINTPL_TPL'] = 'tpl/my-template/';]('RAINTPL_TPL']-=-'tpl/my-template/';.html)
    • 
+
  • Edit data/config.json.php to have Shaarli use this template, in "resource" e.g.
    
+
    "raintpl_tpl": "tpl\/my-template\/",
    • 
 
 
    Community themes & templates
    
 
 
    Example installation: AlbinoMouse template
    
diff --git a/doc/Theming.md b/doc/Theming.md
index 7fb8d927..a21899c2 100644
--- a/doc/Theming.md
+++ b/doc/Theming.md
@@ -16,20 +16,21 @@ _WARNING - This feature is currently being worked on and will be improved in the
 - Find it's git clone URL or download the zip archive for the template.
 - In your Shaarli `tpl/` directory, run `git clone https://url/of/my-template/` or unpack the zip archive.
     - There should now be a `my-template/` directory under the `tpl/` dir, containing directly all the template files.
-- Edit `data/config.php` to have Shaarli use this template, e.g.
-```php
-$GLOBALS['config'['RAINTPL_TPL'] = 'tpl/my-template/';]('RAINTPL_TPL']-=-'tpl/my-template/';.html)
+- Edit `data/config.json.php` to have Shaarli use this template, in `"resource"` e.g.
+```json
+"raintpl_tpl": "tpl\/my-template\/",
 ```
 
 ## Community themes & templates
 - [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli[](.html)
 - [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli[](.html)
+- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme.[](.html)
 - [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli[](.html)
 - [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli[](.html)
 - [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.[](.html)
+- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site.[](.html)
 - [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template[](.html)
 - [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for SHaarli.[](.html)
-- [Vinm/Blue-theme-for Shaarli](https://github.com/Vinm/Blue-theme-for-Shaarli) - A template/theme for Shaarli ([unmaintained](https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2), compatibility unknown)[](.html)
 - [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance[](.html)
 
 ### Example installation: AlbinoMouse template
-- 
cgit v1.2.3