From 5409ade28c5f0acf99dbadd4d95e6f8efda5d395 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 14 Apr 2016 14:20:23 +0200 Subject: Update docs from Wiki --- doc/3rd-party-libraries.html | 15 +- doc/Backup,-restore,-import-and-export.html | 63 ++- doc/Browsing-and-searching.html | 84 ++++ doc/Browsing-and-searching.md | 28 ++ doc/Coding-guidelines.html | 15 +- doc/Community-&-Related-software.html | 21 +- doc/Community-&-Related-software.md | 6 +- ...installation-over-SSH-and-serve-it-locally.html | 67 ++- doc/Create-and-serve-multiple-Shaarlis-(farm).html | 160 +++++++ doc/Create-and-serve-multiple-Shaarlis-(farm).md | 58 +++ doc/Datastore-hacks.html | 67 ++- doc/Datastore-hacks.md | 7 +- doc/Development.html | 17 +- doc/Directory-structure.html | 63 ++- doc/Docker.html | 245 ++++++++++ doc/Docker.md | 157 +++++++ doc/Download-CSS-styles-from-an-OPML-list.html | 63 ++- doc/Download.html | 71 ++- ...xample-patch---add-new-via-field-for-links.html | 15 +- doc/FAQ.html | 15 +- doc/Firefox-share.html | 30 +- doc/GnuPG-signature.html | 143 +++--- doc/GnuPG-signature.md | 70 +-- doc/Home.html | 17 +- doc/Home.md | 2 +- doc/Plugin-System.html | 222 +++++---- doc/Plugin-System.md | 78 +-- doc/Plugin-installation-&-configuration.html | 154 ++++++ doc/Plugin-installation-&-configuration.md | 69 +++ doc/Plugin-list.html | 87 ++++ doc/Plugin-list.md | 18 + doc/RSS-feeds.html | 29 +- doc/RSS-feeds.md | 12 + doc/Release-Shaarli.html | 171 +++++++ doc/Release-Shaarli.md | 72 +++ doc/Security.html | 63 ++- doc/Server-configuration.html | 100 ++-- doc/Server-configuration.md | 28 +- doc/Server-requirements.html | 68 ++- doc/Server-requirements.md | 11 +- doc/Server-security.html | 166 +++++++ doc/Server-security.md | 60 +++ doc/Shaarli-configuration.html | 84 +++- doc/Shaarli-configuration.md | 24 +- doc/Shaarli-installation.html | 73 +++ doc/Shaarli-installation.md | 6 + doc/Sharing-button.html | 23 +- doc/Sharing-button.md | 12 + doc/Static-analysis.html | 15 +- doc/TODO.html | 15 +- doc/Theming.html | 73 ++- doc/Troubleshooting.html | 70 ++- doc/Unit-tests.html | 81 ++-- doc/Upgrade-from-original-sebsauvage-Shaarli.html | 75 +++ doc/Upgrade-from-original-sebsauvage-Shaarli.md | 4 + doc/Usage.html | 15 +- doc/_Footer.html | 18 +- doc/_Sidebar.html | 24 +- doc/_Sidebar.md | 9 + doc/images/doc-logo.svg | 522 +++++++++++++++++++++ doc/sidebar.html | 9 + 61 files changed, 3433 insertions(+), 626 deletions(-) create mode 100644 doc/Browsing-and-searching.html create mode 100644 doc/Browsing-and-searching.md create mode 100644 doc/Create-and-serve-multiple-Shaarlis-(farm).html create mode 100644 doc/Create-and-serve-multiple-Shaarlis-(farm).md create mode 100644 doc/Docker.html create mode 100644 doc/Docker.md create mode 100644 doc/Plugin-installation-&-configuration.html create mode 100644 doc/Plugin-installation-&-configuration.md create mode 100644 doc/Plugin-list.html create mode 100644 doc/Plugin-list.md create mode 100644 doc/Release-Shaarli.html create mode 100644 doc/Release-Shaarli.md create mode 100644 doc/Server-security.html create mode 100644 doc/Server-security.md create mode 100644 doc/Shaarli-installation.html create mode 100644 doc/Shaarli-installation.md create mode 100644 doc/Upgrade-from-original-sebsauvage-Shaarli.html create mode 100644 doc/Upgrade-from-original-sebsauvage-Shaarli.md create mode 100644 doc/images/doc-logo.svg diff --git a/doc/3rd-party-libraries.html b/doc/3rd-party-libraries.html index 21fa20aa..0da63f22 100644 --- a/doc/3rd-party-libraries.html +++ b/doc/3rd-party-libraries.html @@ -4,12 +4,12 @@ - Shaarli - 3rd party libraries + Shaarli – 3rd party libraries + -
@@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/Backup,-restore,-import-and-export.html b/doc/Backup,-restore,-import-and-export.html index 5724b689..f5414efb 100644 --- a/doc/Backup,-restore,-import-and-export.html +++ b/doc/Backup,-restore,-import-and-export.html @@ -4,31 +4,49 @@ - Shaarli - Backup, restore, import and export + Shaarli – Backup, restore, import and export - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -79,7 +106,7 @@ code > span.er { color: #ff0000; font-weight: bold; }

    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:

      @@ -92,7 +119,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
    • This can be done using the shaarchiver tool.

    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.)

    diff --git a/doc/Browsing-and-searching.html b/doc/Browsing-and-searching.html new file mode 100644 index 00000000..a0887850 --- /dev/null +++ b/doc/Browsing-and-searching.html @@ -0,0 +1,84 @@ + + + + + + + Shaarli – Browsing and searching + + + + + + +

    Browsing and searching

    +

    Browsing and Searching

    +

    Status: DRAFT

    +

    +

    Plain text search

    +

    Use the Search text field to search in any of the fields of all links (Title, URL, Description...)

    +

    Exclude text/tags: Use the - operator before a word or tag (example -uninteresting) to prevent entries containing (or tagged) uninteresting from showing up in the search results.

    +

    Exact text search: Use double-quotes (example "exact search") to search for the exact expression.

    +

    Both exclude patterns and exact searches can be combined with normal searches (example "exact search" term otherterm -notthis "very exact" stuff -notagain)

    + +

    Use the Filter by tags field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).

    +

    Hidden tags: Tags starting with a dot . (example .secret) are private. They can only be seen and searched when logged in.

    +

    Alternatively you can use the Tag cloud to discover all tags and click on any of them to display related links.

    +

    Filtering RSS feeds/Picture wall

    +

    RSS feeds can also be restricted to only return items matching a text/tag search: see RSS feeds.

    + + diff --git a/doc/Browsing-and-searching.md b/doc/Browsing-and-searching.md new file mode 100644 index 00000000..187fe447 --- /dev/null +++ b/doc/Browsing-and-searching.md @@ -0,0 +1,28 @@ +#Browsing and searching +# Browsing and Searching + +Status: DRAFT + +![(http://pix.toile-libre.org/upload/original/1455571378.png)]((http://pix.toile-libre.org/upload/original/1455571378.png).html) + +## Plain text search + +Use the `Search text` field to search in _any_ of the fields of all links (Title, URL, Description...) + +**Exclude text/tags:** Use the `-` operator before a word or tag (example `-uninteresting`) to prevent entries containing (or tagged) `uninteresting` from showing up in the search results. + +**Exact text search:** Use double-quotes (example `"exact search"`) to search for the exact expression. + +Both exclude patterns and exact searches can be combined with normal searches (example `"exact search" term otherterm -notthis "very exact" stuff -notagain`) + +## Tags search + +Use the `Filter by tags` field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags). + +**Hidden tags:** Tags starting with a dot `.` (example `.secret`) are private. They can only be seen and searched when logged in. + +Alternatively you can use the `Tag cloud` to discover all tags and click on any of them to display related links. + +## Filtering RSS feeds/Picture wall + +RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS-feeds.html). diff --git a/doc/Coding-guidelines.html b/doc/Coding-guidelines.html index 40d17912..8dbf3bce 100644 --- a/doc/Coding-guidelines.html +++ b/doc/Coding-guidelines.html @@ -4,12 +4,12 @@ - Shaarli - Coding guidelines + Shaarli – Coding guidelines + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/Community-&-Related-software.html b/doc/Community-&-Related-software.html index 34bc6157..8dd0e430 100644 --- a/doc/Community-&-Related-software.html +++ b/doc/Community-&-Related-software.html @@ -4,12 +4,12 @@ - Shaarli - Community & Related software + Shaarli – Community & Related software + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -72,6 +81,10 @@
  • Shaarli.fr/my - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of DMeloni
  • Shaarli Community - Unknown Shaarli hoster (unsupported, old fork)
    • +

    Third party plugins

    +
      +
    • autosave - periodically saves contents of the Edit link/Save link dialog to your browser's LocalStorage to avoid data loss when typing a long entry.
      • +

    Themes

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

    Server apps

    @@ -85,7 +98,7 @@

    Mobile Apps

    diff --git a/doc/Community-&-Related-software.md b/doc/Community-&-Related-software.md index 77ea2420..27da45d8 100644 --- a/doc/Community-&-Related-software.md +++ b/doc/Community-&-Related-software.md @@ -15,6 +15,10 @@ _TODO: contact repos owners to see if they'd like to standardize their work with - [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)[](.html) - [Shaarli Community](http://shaarferme.etudiant-libre.fr.nf/index.php) - Unknown Shaarli hoster (unsupported, old fork)[](.html) +### Third party plugins + + * [autosave](https://github.com/kalvn/shaarli-plugin-autosave) - periodically saves contents of the _Edit link/Save link_ dialog to your browser's LocalStorage to avoid data loss when typing a long entry.[](.html) + ### Themes See [Theming](Theming.html) for the list of community-contributed themes, and an installation guide. @@ -27,7 +31,7 @@ See [Theming](Theming.html) for the list of community-contributed themes, and an - [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) ### Mobile Apps -- [github.com/mro/ShaarliOS](https://github.com/mro/ShaarliOS#the-missing-ios-8-share-extension-to-shaarli) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-132303709) for some promo codes,[](.html) +- [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) - [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider[](.html) - [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli[](.html) 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 e27b1134..067c6828 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 @@ -4,31 +4,49 @@ - Shaarli - Copy an existing installation over SSH and serve it locally + Shaarli – Copy an existing installation over SSH and serve it locally - +

    Copy an existing installation over SSH and serve it locally

    Example bash script:

    -
    #!/bin/bash
+
    #!/bin/bash
 #Description: Copy a Shaarli installation over SSH/SCP, serve it locally with php-cli
 #Will create a local-shaarli/ directory when you run it, backup your Shaarli there, and serve it locally.
 #Will NOT download linked pages. It's just a directly usable backup/copy/mirror of your Shaarli
@@ -124,9 +151,9 @@ code > span.er { color: #ff0000; font-weight: bold; }
 
 ##### MAIN #################
 
-_main
    
+_main

    This outputs:

    -
    $ ./local-shaarli.sh
+
    $ ./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
@@ -134,6 +161,6 @@ code > span.er { color: #ff0000; font-weight: bold; }
 
 [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: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 new file mode 100644 index 00000000..d3da1a2e --- /dev/null +++ b/doc/Create-and-serve-multiple-Shaarlis-(farm).html @@ -0,0 +1,160 @@ + + + + + + + Shaarli – Create and serve multiple Shaarlis (farm) + + + + + + + +

    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
+
+#config
+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)
+   
+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">
+<!-- Minimal html template thanks to http://www.sitepoint.com/a-minimal-html-document/ -->
+<html lang="en">
+    <head>
+        <meta http-equiv="content-type" content="text/html; charset=utf-8">
+        <title>My Shaarli farm</title>
+        <style>body {font-family: "Open Sans"}</style>
+    </head>
+    <body>
+    <div>
+    <h1>My Shaarli farm</h1>
+    <ul style="list-style-type: none;">'
+
+accountlinks=''
+    
+htmlfooter='
+    </ul>
+    </div>
+    </body>
+</html>'    
+    
+
+
+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/Create-and-serve-multiple-Shaarlis-(farm).md b/doc/Create-and-serve-multiple-Shaarlis-(farm).md new file mode 100644 index 00000000..a71f6520 --- /dev/null +++ b/doc/Create-and-serve-multiple-Shaarlis-(farm).md @@ -0,0 +1,58 @@ +#Create and serve multiple Shaarlis (farm) +Example bash script (creates multiple shaarli instances and generates an HTML index of them) + +```bash +#!/bin/bash +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" + +#clone multiple shaarli instances +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) +done + +#generate html index of shaarlis +htmlhead=' + + + + + My Shaarli farm + + + +
    +

    My Shaarli farm

    +
      ' + +accountlinks='' + +htmlfooter=' +
    +
    + +' + + + +for account in $accounts; do accountlinks="$accountlinks\n
  • $account
    • "; 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](https://www.ansible.com/)[](.html) diff --git a/doc/Datastore-hacks.html b/doc/Datastore-hacks.html index 0bf2a493..6273fae0 100644 --- a/doc/Datastore-hacks.html +++ b/doc/Datastore-hacks.html @@ -4,31 +4,49 @@ - Shaarli - Datastore hacks + Shaarli – Datastore hacks - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -78,17 +105,19 @@ code > span.er { color: #ff0000; font-weight: bold; }

    Datastore hacks

    Decode datastore content

    To display the array representing the data saved in data/datastore.php, use the following snippet:

    -
    $data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
+
    $data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
 $out = unserialize(gzinflate(base64_decode($data)));
 echo "<pre>"; // Pretty printing is love, pretty printing is life
 print_r($out);
 echo "</pre>";
-exit;
    
+exit;

    This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation).

    +

    Alternatively, you can transform to JSON format (and pretty-print if you have jq installed):

    +
    php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/\* (.+) \*/.*!", "$1", file_get_contents("data/datastore.php")))))));' | jq .
    • Look for <input type="hidden" name="lf_linkdate" value="{$link.linkdate}"> in tpl/editlink.tpl (line 14)
      • -
    • Remove type="hidden" from this line
      • +
    • Replace type="hidden" with type="text" from this line
    • A new date/time field becomes available in the edit/new link dialog.
    • You can set the timestamp manually by entering it in the format YYYMMDD_HHMMS.
    diff --git a/doc/Datastore-hacks.md b/doc/Datastore-hacks.md index 33aa2223..ef6f6d50 100644 --- a/doc/Datastore-hacks.md +++ b/doc/Datastore-hacks.md @@ -12,8 +12,13 @@ exit; ``` This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation). +Alternatively, you can transform to JSON format (and pretty-print if you have `jq` installed): +``` +php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/\* (.+) \*/.*!", "$1", file_get_contents("data/datastore.php")))))));' | jq . +``` + ### Changing the timestamp for a link * Look for `` in `tpl/editlink.tpl` (line 14) -* Remove `type="hidden"` from this line +* Replace `type="hidden"` with `type="text"` from this line * A new date/time field becomes available in the edit/new link dialog. * You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`. diff --git a/doc/Development.html b/doc/Development.html index 88cf5854..f7ada07f 100644 --- a/doc/Development.html +++ b/doc/Development.html @@ -4,12 +4,12 @@ - Shaarli - Development + Shaarli – Development + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -92,7 +101,7 @@

    After all jobs have finished, Travis returns the results to GitHub:

      -
    • a status icon represents the result for the master branch: (https://api.travis-ci.org/shaarli/Shaarli.svg)
      • +
    • a status icon represents the result for the master branch: (https://api.travis-ci.org/shaarli/Shaarli.svg)
    • Pull Requests are updated with the Travis result
      • Green: all tests have passed
        • diff --git a/doc/Directory-structure.html b/doc/Directory-structure.html index 7015923c..2369950a 100644 --- a/doc/Directory-structure.html +++ b/doc/Directory-structure.html @@ -4,31 +4,49 @@ - Shaarli - Directory structure + Shaarli – Directory structure - +
      • +
    • Docker
      • +
    • Plugin list
    • Usage
    • How To
      • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
    • Directory structure
    • 3rd party libraries
    • Plugin System
      • +
    • Release Shaarli
    • Security
    • Static analysis
    • Theming
      • @@ -77,7 +104,7 @@ code > span.er { color: #ff0000; font-weight: bold; }

    Directory structure

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

    -
        index.php        # Main program
+
        index.php        # Main program
     application/     # Shaarli classes
         ├── LinkDB.php
         └── Utils.php
@@ -104,6 +131,6 @@ code > span.er { color: #ff0000; font-weight: bold; }
     cache/           # thumbnails cache
                      # This directory is automatically created. You can erase it anytime you want.
     tmp/             # Temporary directory for compiled RainTPL templates.
-                     # This directory is automatically created. You can erase it anytime you want.
    
+                     # This directory is automatically created. You can erase it anytime you want.
    diff --git a/doc/Docker.html b/doc/Docker.html new file mode 100644 index 00000000..ab95da39 --- /dev/null +++ b/doc/Docker.html @@ -0,0 +1,245 @@ + + + + + + + Shaarli – Docker + + + + + + + +

    Docker

    + +

    Docker usage

    +

    Basics

    +

    Install Docker, by following the instructions relevant
    +to your OS / distribution, and start the service.

    +

    Search an image on DockerHub

    +
    $ 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)
+google/debian                                                   47                 [OK][](.html)
    +

    Show available tags for a repository

    +
    $ 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
    +

    Sample output:

    +
    [[](.html)
+    {
+        "layer": "85a02782",
+        "name": "stretch"
+    },
+    {
+        "layer": "59abecbc",
+        "name": "testing"
+    },
+    {
+        "layer": "bf0fd686",
+        "name": "unstable"
+    },
+    {
+        "layer": "60c52dbe",
+        "name": "wheezy"
+    },
+    {
+        "layer": "c5b806fe",
+        "name": "wheezy-backports"
+    }
+]
    +

    Pull an image from DockerHub

    +
    $ 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
    +

    Get and run a Shaarli image

    +

    DockerHub repository

    +

    The images can be found in the shaarli/shaarli
    +repository.

    +

    Available image tags

    + +

    All images rely on:

    + +

    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
    +

    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
+
+# launch the container in the background
+$ 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
    +

    Stop and destroy a container

    +
    $ 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
+
+# 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
+
+# destroy the container
+$ 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
    +

    Resources

    +

    Docker

    + +

    DockerHub

    + +

    Service management

    + + + diff --git a/doc/Docker.md b/doc/Docker.md new file mode 100644 index 00000000..1faa7904 --- /dev/null +++ b/doc/Docker.md @@ -0,0 +1,157 @@ +#Docker +- [Docker usage](#docker-usage)[](.html) +- [Get and run a Shaarli image](#get-and-run-a-shaarli-image)[](.html) +- [Resources](#resources)[](.html) + +## Docker usage +### Basics +Install [Docker](https://www.docker.com/), by following the instructions relevant[](.html) +to your OS / distribution, and start the service. + +#### Search an image on [DockerHub](https://hub.docker.com/)[](.html) + +```bash +$ 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) +google/debian 47 [OK][](.html) +``` + +#### Show available tags for a repository +```bash +$ 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 +``` + +Sample output: +```json +[[](.html) + { + "layer": "85a02782", + "name": "stretch" + }, + { + "layer": "59abecbc", + "name": "testing" + }, + { + "layer": "bf0fd686", + "name": "unstable" + }, + { + "layer": "60c52dbe", + "name": "wheezy" + }, + { + "layer": "c5b806fe", + "name": "wheezy-backports" + } +] + +``` + +#### Pull an image from DockerHub +```bash +$ 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 +``` + +## Get and run a Shaarli image +### DockerHub repository +The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/)[](.html) +repository. + +### Available image tags +- `latest`: master branch (tarball release) +- `stable`: stable branch (tarball release) +- `dev`: master branch (Git clone) + +All images rely on: +- [Debian 8 Jessie](https://hub.docker.com/_/debian/)[](.html) +- [PHP5-FPM](http://php-fpm.org/)[](.html) +- [Nginx](http://nginx.org/)[](.html) + +### Download from DockerHub +```bash +$ 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 +```bash +# map the host's :8000 port to the container's :80 port +$ docker create -p 8000:80 shaarli/shaarli +d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 + +# launch the container in the background +$ 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 +``` + +### Stop and destroy a container +```bash +$ 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 + +# 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 + +# destroy the container +$ 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 +``` + +## Resources +### Docker +- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)[](.html) +- [Dockerfile reference](https://docs.docker.com/reference/builder/)[](.html) +- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)[](.html) +- [Volumes](https://docs.docker.com/userguide/dockervolumes/)[](.html) + +### DockerHub +- [Repositories](https://docs.docker.com/userguide/dockerrepos/)[](.html) +- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/)[](.html) +- [GitHub automated build](https://docs.docker.com/docker-hub/github/)[](.html) + +### Service management +- [Using supervisord](https://docs.docker.com/articles/using_supervisord/)[](.html) +- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)[](.html) +- [supervisord](http://supervisord.org/)[](.html) diff --git a/doc/Download-CSS-styles-from-an-OPML-list.html b/doc/Download-CSS-styles-from-an-OPML-list.html index 7d7fe968..aaafbfeb 100644 --- a/doc/Download-CSS-styles-from-an-OPML-list.html +++ b/doc/Download-CSS-styles-from-an-OPML-list.html @@ -4,31 +4,49 @@ - Shaarli - Download CSS styles from an OPML list + Shaarli – Download CSS styles from an OPML list - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -78,7 +105,7 @@ code > span.er { color: #ff0000; font-weight: bold; }

    Download CSS styles from an OPML list

    Download CSS styles for shaarlis listed in an opml file

    Example php script:

    -
    <!---- ?php -->
+
    <!---- ?php -->
 <!---- Copyright (c) 2014 Nicolas Delsaux (https://github.com/Riduidel) -->
 <!---- License: zlib (http://www.gzip.org/zlib/zlib_license.html) -->
 
@@ -226,6 +253,6 @@ code > span.er { color: #ff0000; font-weight: bold; }
 $knownStyles = findKnownStyles();
 copyUserStylesFrom(createShaarliHashFromOPMLL(SHAARLI_RSS_OPML), $knownStyles);
 
-<!--- ? ---->
    
+<!--- ? ---->
    diff --git a/doc/Download.html b/doc/Download.html index 5f39c70f..6d668e8e 100644 --- a/doc/Download.html +++ b/doc/Download.html @@ -4,31 +4,49 @@ - Shaarli - Download + Shaarli – Download - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -80,18 +107,18 @@ code > span.er { color: #ff0000; font-weight: bold; }

    Latest stable revision

    This revision has been released and tested.

    -
    $ git clone https://github.com/shaarli/Shaarli.git -b stable shaarli
    +
    $ git clone https://github.com/shaarli/Shaarli.git -b stable shaarli

    Download as an archive

    -
    $ wget https://github.com/shaarli/Shaarli/archive/stable.zip
+
    $ wget https://github.com/shaarli/Shaarli/archive/stable.zip
 $ unzip stable.zip
-$ mv Shaarli-stable shaarli
    
+$ mv Shaarli-stable shaarli

    Tarballs are also available:

    -
    $ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
+
    $ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
 $ tar xvf stable.tar.gz
-$ mv Shaarli-stable shaarli
    
+$ 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
    +
    $ 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 388ff963..d6f9a92e 100644 --- a/doc/Example-patch---add-new-via-field-for-links.html +++ b/doc/Example-patch---add-new-via-field-for-links.html @@ -4,12 +4,12 @@ - Shaarli - Example patch add new via field for links + Shaarli – Example patch add new via field for links + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/FAQ.html b/doc/FAQ.html index 33eb7c60..72343b3f 100644 --- a/doc/FAQ.html +++ b/doc/FAQ.html @@ -4,12 +4,12 @@ - Shaarli - FAQ + Shaarli – FAQ + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/Firefox-share.html b/doc/Firefox-share.html index 2943a86d..0ae70605 100644 --- a/doc/Firefox-share.html +++ b/doc/Firefox-share.html @@ -4,12 +4,12 @@ - Shaarli - Firefox share + Shaarli – Firefox share + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -69,6 +78,19 @@
  • When you are visiting a webpage you would like to share with Shaarli, click the Firefox Share button images/firefoxshare.png
  • You can edit your link before and after saving, just like the bookmarklet above.
    • -

    |  | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections. |
    |------|-------------------------------------------------------------------------------|

    + ++++ + + + + + + + + +
    Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections.
    diff --git a/doc/GnuPG-signature.html b/doc/GnuPG-signature.html index a1210b75..c187c996 100644 --- a/doc/GnuPG-signature.html +++ b/doc/GnuPG-signature.html @@ -4,31 +4,49 @@ - Shaarli - GnuPG signature + Shaarli – GnuPG signature - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -78,10 +105,13 @@ code > span.er { color: #ff0000; font-weight: bold; }

    GnuPG signature

    Introduction

    PGP and GPG

    -

    Gnu Privacy Guard (GnuPG) is an Open Source implementation of the Pretty Good [](.html)
    Privacy     (OpenPGP) specification. Its main purposes are digital authentication,
    signature and encryption.

    +

    Gnu Privacy Guard (GnuPG) is an Open Source implementation of the Pretty Good [](.html)
    +Privacy     (OpenPGP) specification. Its main purposes are digital authentication,
    +signature and encryption.

    It is often used by the FLOSS community to verify:

    Trust

    @@ -95,9 +125,12 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Web of trust

    • Generate a GPG key

    -

    See Generating a GPG key for Git tagging.

    +

    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.
@@ -116,7 +149,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
 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.
    
+generator a better chance to gain enough entropy.

    gpg - entropy interlude

    At this point, you will:

      @@ -124,7 +157,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
    • 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
+
    gpg: key A9D53A3E marked as ultimately trusted
 public and secret key created and signed.
 
 gpg: checking the trustdb
@@ -133,69 +166,11 @@ code > span.er { color: #ff0000; font-weight: bold; }
 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
    
+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 Git - Maintaining a project - Tagging your [](.html)
    releases    .

    -

    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
        • -
      • -
    • a GitHub fork of Shaarli
      • -
    • 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)
      • -
    -

    Bump Shaarli's version

    -
    $ cd /path/to/shaarli
-
-# create a new branch
-$ git fetch upstream
-$ git checkout upstream/master -b v0.5.0
-
-# bump the version number
-$ vim index.php shaarli_version.php
-
-# commit the changes
-$ git add index.php shaarli_version.php
-$ git commit -s -m "Bump version to v0.5.0"
-
-# push the commit on your GitHub fork
-$ 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
-
-# create a signed tag
-$ git tag -s -m "Release v0.5.0" v0.5.0
-
-# push it to "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
-
-# get the SHA1 reference of the tag
-$ 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)
    +

    See Release Shaarli.

    diff --git a/doc/GnuPG-signature.md b/doc/GnuPG-signature.md index e8dbdb11..b0028d55 100644 --- a/doc/GnuPG-signature.md +++ b/doc/GnuPG-signature.md @@ -20,7 +20,8 @@ Trust can be gained by having your key signed by other people (and signing their - [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)[](.html) ## Generate a GPG key -See [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717).[](.html) +- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)[](.html) +- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)[](.html) ### gpg - provide identity information ```bash @@ -72,70 +73,5 @@ gpg: sending key A9D53A3E to hkp server pgp.mit.edu ``` ## Create and push a GPG-signed tag -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 -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` -- a GitHub fork of Shaarli -- 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) - -### Bump Shaarli's version -```bash -$ cd /path/to/shaarli - -# create a new branch -$ git fetch upstream -$ git checkout upstream/master -b v0.5.0 - -# bump the version number -$ vim index.php shaarli_version.php - -# commit the changes -$ git add index.php shaarli_version.php -$ git commit -s -m "Bump version to v0.5.0" - -# push the commit on your GitHub fork -$ git push origin v0.5.0 -``` - -### Create and merge a Pull Request -This one is pretty straightforward ;-) - -### Create and push a signed tag -```bash -# update your local copy -$ 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 - -# push it to "upstream" -$ git push --tags upstream -``` - -### Verify a signed tag -[`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.[](.html) - -Let's have a look at its signature! - -```bash -$ 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 - -# 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 " [ultimate][](.html) -``` +See [Release Shaarli](Release-Shaarli.html). diff --git a/doc/Home.html b/doc/Home.html index 39d951c8..827d256f 100644 --- a/doc/Home.html +++ b/doc/Home.html @@ -4,12 +4,12 @@ - Shaarli - Home + Shaarli – Home + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -61,7 +70,7 @@

    Welcome to the Shaarli wiki

    Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.

    For general info, read the README.

    -

    If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion or read the current issues. If you've found a bug, please create a new issue.

    +

    If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion (archive) or read the current issues. If you've found a bug, please create a new issue.

    If you would like a feature added to Shaarli, check the issues labeled feature, enhancement, and plugin.

    Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the doc/ directory of your Shaarli installation.

    diff --git a/doc/Home.md b/doc/Home.md index a824d983..38413f24 100644 --- a/doc/Home.md +++ b/doc/Home.md @@ -7,7 +7,7 @@ Here you can find some info on how to use, configure, tweak and solve problems w For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).[](.html) -If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/44) or read the current [issues](https://github.com/shaarli/Shaarli/issues). If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).[](.html) +If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) ([archive](https://github.com/shaarli/Shaarli/issues/44)) or read the current [issues](https://github.com/shaarli/Shaarli/issues). If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).[](.html) If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).[](.html) diff --git a/doc/Plugin-System.html b/doc/Plugin-System.html index cb1cb746..2a660c49 100644 --- a/doc/Plugin-System.html +++ b/doc/Plugin-System.html @@ -4,31 +4,49 @@ - Shaarli - Plugin System + Shaarli – Plugin System - +

    Plugin System

    -

    Note: Plugin current status - in developpement (not merged into master).

    +

    Note: Plugin current status - in development (not merged into master).

    -

    I am a user. Plugin User Guide.

    -

    I am a developper. Developper API.

    +

    I am a developer. Developer API.

    I am a template designer. Guide for template designer.

    -

    Plugin User Guide

    -

    Manage plugins

    -

    In config.php, change $GLOBALS'config'['ENABLED_PLUGINS'] array:

    -
    $GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html)
    -

    Full list:

    -
    $GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html)
-    'qrcode', 'archiveorg', 'readityourself', 'playvideos',
-    'wallabag', 'markdown', 'addlink_toolbar',
-);
    -

    List of plugins

    -

    Plugin maintained by the community:

    -
      -
    • Archive.org - add a clickable icon to every link to archive.org.
      • -
    • Addlink in toolbar - add a field to paste new links URL in toolbar.
      • -
    • Markdown - write and display Shaare in Markdown.
      • -
    • Play videos - popup to play all videos displayed in linklist.
      • -
    • QRCode - add a clickable icon generating a QRCode for every link.
      • -
    • ReadItYourself - add a clickable icon for ReadItYourself.
      • -
    • Wallabag - add a clickable icon for Wallabag.
      • -
    -

    Developper API

    +

    Developer API

    What can I do with plugins?

    The plugin system let you:

      @@ -134,72 +140,86 @@ code > span.er { color: #ff0000; font-weight: bold; }

      Template placeholders are displayed in template in specific places.

      RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.

      For example, let's add a value in the placeholder top_placeholder which is displayed at the top of my page:

      -
      $data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
+
      $data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
 # OR
 array_push($data['top_placeholder'], 'My', 'content');[](.html)
 
-return $data;
      
+return $data;

    Data manipulation

    When a page is displayed, every variable send to the template engine is passed to plugins before that in $data.

    The data contained by this array can be altered before template rendering.

    For exemple, in linklist, it is possible to alter every title:

    -
    // mind the reference if you want $data to be altered
+
    // mind the reference if you want $data to be altered
 foreach ($data['links'] as &$value) {[](.html)
     // String reverse every title.
     $value['title'] = strrev($value['title']);[](.html)
 }
 
-return $data;
    
+return $data;
    +

    Metadata

    +

    Every plugin needs a <plugin_name>.meta file, which is in fact an .ini file (KEY="VALUE"), to be listed in plugin administration.

    +

    Each file contain two keys:

    + +
    +

    Note: In PHP, parse_ini_file() seems to want strings to be between by quotes " in the ini file.

    +

    It's not working!

    Use demo_plugin as a functional example. It covers most of the plugin system features.

    If it's still not working, please open an issue.

    Hooks

    - +
    ++++ - + - + - + - + - + - + - + - + - + - + - + @@ -393,6 +413,20 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • tags

    • Guide for template designer

    +

    Plugin administration

    +

    Your theme must include a plugin administration page: pluginsadmin.html.

    +
    +

    Note: repo's template link needs to be added when the PR is merged.

    +
    +

    Use the default one as an example.

    +

    Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include plugin_admin.js, only if:

    + +

    Otherwise, you can use your own JS as long as this field is send by the form:

    +

    Placeholder system

    In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.

    It's a RainTPL loop like this:

    @@ -406,96 +440,104 @@ code > span.er { color: #ff0000; font-weight: bold; } 
    {loop="$plugins_header.buttons_toolbar"}
     {$value}
 {/loop}
    +

    At the end of file, before clearing floating blocks:

    +
    {if="!empty($plugin_errors) && isLoggedIn()"}
+    <ul class="errors">
+        {loop="plugin_errors"}
+            <li>{$value}</li>
+        {/loop}
+    </ul>
+{/if}

    includes.html

    At the end of the file:

    -
    {loop="$plugins_includes.css_files"}
+
    {loop="$plugins_includes.css_files"}
 <link type="text/css" rel="stylesheet" href="{$value}#"/>
-{/loop}
    
+{/loop}

    page.footer.html

    At the end of your footer notes:

    -
    {loop="$plugins_footer.text"}
+
    {loop="$plugins_footer.text"}
      {$value}
-{/loop}
    
+{/loop}

    At the end of file:

    -
    {loop="$plugins_footer.js_files"}
+
    {loop="$plugins_footer.js_files"}
      <script src="{$value}#"></script>
-{/loop}
    
+{/loop}

    linklist.html

    After search fields:

    -
    {loop="$plugins_header.fields_toolbar"}
+
    {loop="$plugins_header.fields_toolbar"}
      {$value}
-{/loop}
    
+{/loop}

    Before displaying the link list (after paging):

    -
    {loop="$plugin_start_zone"}
+
    {loop="$plugin_start_zone"}
      {$value}
-{/loop}
    
+{/loop}

    For every links (icons):

    -
    {loop="$value.link_plugin"}
+
    {loop="$value.link_plugin"}
     <span>{$value}</span>
-{/loop}
    
+{/loop}

    Before end paging:

    -
    {loop="$plugin_end_zone"}
+
    {loop="$plugin_end_zone"}
      {$value}
-{/loop}
    
+{/loop}

    linklist.paging.html

    After the "private only" icon:

    -
    {loop="$action_plugin"}
+
    {loop="$action_plugin"}
      {$value}
-{/loop}
    
+{/loop}

    editlink.html

    After tags field:

    -
    {loop="$edit_link_plugin"}
+
    {loop="$edit_link_plugin"}
      {$value}
-{/loop}
    
+{/loop}

    tools.html

    After the last tool:

    -
    {loop="$tools_plugin"}
+
    {loop="$tools_plugin"}
      {$value}
-{/loop}
    
+{/loop}

    picwall.html

    Top:

    -
    <div id="plugin_zone_start_picwall" class="plugin_zone">
+
    <div id="plugin_zone_start_picwall" class="plugin_zone">
     {loop="$plugin_start_zone"}
         {$value}
     {/loop}
-</div>
    
+</div>

    Bottom:

    -
    <div id="plugin_zone_end_picwall" class="plugin_zone">
+
    <div id="plugin_zone_end_picwall" class="plugin_zone">
     {loop="$plugin_end_zone"}
         {$value}
     {/loop}
-</div>
    
+</div>

    tagcloud.html

    Top:

    -
       <div id="plugin_zone_start_tagcloud" class="plugin_zone">
+
       <div id="plugin_zone_start_tagcloud" class="plugin_zone">
         {loop="$plugin_start_zone"}
             {$value}
         {/loop}
-    </div>
    
+    </div>

    Bottom:

    -
        <div id="plugin_zone_end_tagcloud" class="plugin_zone">
+
        <div id="plugin_zone_end_tagcloud" class="plugin_zone">
         {loop="$plugin_end_zone"}
             {$value}
         {/loop}
-    </div>
    
+    </div>

    daily.html

    Top:

    -
    <div id="plugin_zone_start_picwall" class="plugin_zone">
+
    <div id="plugin_zone_start_picwall" class="plugin_zone">
      {loop="$plugin_start_zone"}
          {$value}
      {/loop}
-</div>
    
+</div>

    After every link:

    -
    <div class="dailyEntryFooter">
+
    <div class="dailyEntryFooter">
      {loop="$link.link_plugin"}
           {$value}
      {/loop}
-</div>
    
+</div>

    Bottom:

    -
    <div id="plugin_zone_end_picwall" class="plugin_zone">
+
    <div id="plugin_zone_end_picwall" class="plugin_zone">
     {loop="$plugin_end_zone"}
         {$value}
     {/loop}
-</div>
    
+</div>
    diff --git a/doc/Plugin-System.md b/doc/Plugin-System.md index 8cba6664..8281e61d 100644 --- a/doc/Plugin-System.md +++ b/doc/Plugin-System.md @@ -1,44 +1,11 @@ #Plugin System -> Note: Plugin current status - in developpement (not merged into master). +> Note: Plugin current status - in development (not merged into master). -[**I am a user.** Plugin User Guide.](#plugin-user-guide)[](.html) - -[**I am a developper.** Developper API.](#developper-api)[](.html) +[**I am a developer.** Developer API.](#developer-api)[](.html) [**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html) -## Plugin User Guide - -### Manage plugins - -In `config.php`, change $GLOBALS['config'['ENABLED_PLUGINS'] array:]('ENABLED_PLUGINS']-array:.html) - -```php -$GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html) -``` - -Full list: - -```php -$GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html) - 'qrcode', 'archiveorg', 'readityourself', 'playvideos', - 'wallabag', 'markdown', 'addlink_toolbar', -); -``` - -### List of plugins - -Plugin maintained by the community: - - * Archive.org - add a clickable icon to every link to archive.org. - * Addlink in toolbar - add a field to paste new links URL in toolbar. - * Markdown - write and display Shaare in Markdown. - * Play videos - popup to play all videos displayed in linklist. - * QRCode - add a clickable icon generating a QRCode for every link. - * ReadItYourself - add a clickable icon for ReadItYourself. - * Wallabag - add a clickable icon for Wallabag. - -## Developper API +## Developer API ### What can I do with plugins? @@ -123,6 +90,17 @@ foreach ($data['links'] as &$value) {[](.html) return $data; ``` +### Metadata + +Every plugin needs a `.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration. + +Each file contain two keys: + + * `description`: plugin description + * `parameters`: user parameter names, separated by a `;`. + +> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. + ### It's not working! Use `demo_plugin` as a functional example. It covers most of the plugin system features. @@ -399,6 +377,24 @@ Allow to alter the link being saved in the datastore. ## Guide for template designer +### Plugin administration + +Your theme must include a plugin administration page: `pluginsadmin.html`. + +> Note: repo's template link needs to be added when the PR is merged. + +Use the default one as an example. + +Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if: + + * you're using a table. + * you call orderUp() and orderUp() onclick on arrows. + * you add data-line and data-order to your rows. + +Otherwise, you can use your own JS as long as this field is send by the form: + + + ### Placeholder system In order to make plugins work with every custom themes, you need to add variable placeholder in your templates. @@ -421,6 +417,16 @@ At the end of the menu: {$value} {/loop} +At the end of file, before clearing floating blocks: + + {if="!empty($plugin_errors) && isLoggedIn()"} +
      + {loop="plugin_errors"} +
    • {$value}
      • + {/loop} +
    + {/if} + **includes.html** At the end of the file: diff --git a/doc/Plugin-installation-&-configuration.html b/doc/Plugin-installation-&-configuration.html new file mode 100644 index 00000000..3d2f9704 --- /dev/null +++ b/doc/Plugin-installation-&-configuration.html @@ -0,0 +1,154 @@ + + + + + + + Shaarli – Plugin installation & configuration + + + + + + + +

    Plugin installation & configuration

    +

    Plugin installation

    +

    There is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them.

    +

    If you want to install a third party plugin:

    +
      +
    • Download it.
      • +
    • Put it in the plugins directory in Shaarli's installation folder.
      • +
    • Make sure you put it correctly:
      • +
    +
    | index.php
+| plugins/
+|---| custom_plugin/
+|   |---| custom_plugin.php
+|   |---| ...
+
    +
      +
    • Make sure your webserver can read and write the files in your plugin folder.
      • +
    +

    Plugin configuration

    +

    In Shaarli's administration page (Tools link), go to Plugin administration.

    +

    Here you can enable and disable all plugins available, and configure them.

    +

    administration screenshot

    +

    Plugin order

    +

    In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.

    +

    This is important in case plugins are depending on each other. Read plugins README details for more information.

    +

    Use case: The (non existent) plugin shaares_footer adds a footer to every shaare in Markdown syntax. It needs to be processed before (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.

    +

    File mode

    +

    Enabled plugin are stored in your config.php parameters file, under the array:

    +
    $GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html)
    +

    You can edit them manually here.
    +Example:

    +
    $GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html)
+    'qrcode', 
+    'archiveorg',
+    'wallabag',
+    'markdown',
+);
    +

    Plugin usage

    +

    Usage of each plugin is documented in it's README file:

    +
      +
    • addlink-toolbar: Adds the addlink input on the linklist page
      • +
    • archiveorg: For each link, add an Archive.org icon
      • +
    • markdown: Render shaare description with Markdown syntax.
      • +
    • playvideos: Add a button in the toolbar allowing to watch all videos.
      • +
    • qrcode: For each link, add a QRCode icon.
      • +
    • readityourself: For each link, add a ReadItYourself icon to save the shaared URL
      • +
    • wallabag: For each link, add a Wallabag icon to save it in your instance.
      • +
    + + diff --git a/doc/Plugin-installation-&-configuration.md b/doc/Plugin-installation-&-configuration.md new file mode 100644 index 00000000..c260aa1a --- /dev/null +++ b/doc/Plugin-installation-&-configuration.md @@ -0,0 +1,69 @@ +#Plugin installation & configuration +## Plugin installation + +There is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them. + +If you want to install a third party plugin: + + * Download it. + * Put it in the `plugins` directory in Shaarli's installation folder. + * Make sure you put it correctly: + +``` +| index.php +| plugins/ +|---| custom_plugin/ +| |---| custom_plugin.php +| |---| ... + +``` + + * Make sure your webserver can read and write the files in your plugin folder. + +## Plugin configuration + +In Shaarli's administration page (`Tools` link), go to `Plugin administration`. + +Here you can enable and disable all plugins available, and configure them. + +![administration screenshot](https://camo.githubusercontent.com/5da68e191969007492ca0fbeb25f3b2357b748cc/687474703a2f2f692e696d6775722e636f6d2f766837544643712e706e67)[](.html) + +## Plugin order + +In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first. + +This is important in case plugins are depending on each other. Read plugins README details for more information. + +**Use case**: The (non existent) plugin `shaares_footer` adds a footer to every shaare in Markdown syntax. It needs to be processed *before* (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML. + +## File mode + +Enabled plugin are stored in your `config.php` parameters file, under the `array`: + +```php +$GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html) +``` + +You can edit them manually here. +Example: + +```php +$GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html) + 'qrcode', + 'archiveorg', + 'wallabag', + 'markdown', +); +``` + +### Plugin usage + +Usage of each plugin is documented in it's README file: + + * `addlink-toolbar`: Adds the addlink input on the linklist page + * `archiveorg`: For each link, add an Archive.org icon + * [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.[](.html) + * [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.[](.html) + * `qrcode`: For each link, add a QRCode icon. + * `readityourself`: For each link, add a ReadItYourself icon to save the shaared URL + * [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.[](.html) diff --git a/doc/Plugin-list.html b/doc/Plugin-list.html new file mode 100644 index 00000000..16eca046 --- /dev/null +++ b/doc/Plugin-list.html @@ -0,0 +1,87 @@ + + + + + + + Shaarli – Plugin list + + + + + + +

    Plugin list

    +

    Community plugins

    +

    These plugins are maintained by the community:

    +
      +
    • Archive.org - add a clickable icon to every link to archive.org.
      • +
    • Addlink in toolbar - add a field to paste new links URL in toolbar.
      • +
    • Markdown - write and display Shaare in Markdown.
      • +
    • Play videos - popup to play all videos displayed in linklist.
      • +
    • QRCode - add a clickable icon generating a QRCode for every link.
      • +
    • ReadItYourself - add a clickable icon for ReadItYourself.
      • +
    • Wallabag - add a clickable icon for Wallabag.
      • +
    +

    Third party plugins

    + + + diff --git a/doc/Plugin-list.md b/doc/Plugin-list.md new file mode 100644 index 00000000..bb4f553b --- /dev/null +++ b/doc/Plugin-list.md @@ -0,0 +1,18 @@ +#Plugin list +## Community plugins + +These plugins are maintained by the community: + + * Archive.org - add a clickable icon to every link to archive.org. + * Addlink in toolbar - add a field to paste new links URL in toolbar. + * Markdown - write and display Shaare in Markdown. + * Play videos - popup to play all videos displayed in linklist. + * QRCode - add a clickable icon generating a QRCode for every link. + * ReadItYourself - add a clickable icon for ReadItYourself. + * Wallabag - add a clickable icon for Wallabag. + +## Third party plugins + + * [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) diff --git a/doc/RSS-feeds.html b/doc/RSS-feeds.html index 859869bf..9b1447ac 100644 --- a/doc/RSS-feeds.html +++ b/doc/RSS-feeds.html @@ -4,12 +4,12 @@ - Shaarli - RSS feeds + Shaarli – RSS feeds + -

    RSS feeds

    +

    Feeds options

    +

    Feeds are available in ATOM with ?do=atom and RSS with do=RSS.

    +

    Options:

    +
      +
    • You can use permalinks in the feed URL to get permalink to Shaares instead of direct link to shaared URL. +
        +
      • E.G. https://my.shaarli.domain/?do=atom&permalinks.
        • +
      • +
    • You can use nb parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: 50). The keyword all is available if you want everything. +
        +
      • https://my.shaarli.domain/?do=atom&permalinks&nb=42
        • +
      • https://my.shaarli.domain/?do=atom&permalinks&nb=all
        • +
      • +

    RSS Feeds or Picture Wall for a specific search/tag

    It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to only display results of a specific search, or for a specific tag.

    For example, if you want to subscribe only to links tagged photography:

    diff --git a/doc/RSS-feeds.md b/doc/RSS-feeds.md index 764b3a49..757bed9a 100644 --- a/doc/RSS-feeds.md +++ b/doc/RSS-feeds.md @@ -1,5 +1,17 @@ #RSS feeds +### Feeds options + +Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`. + +Options: +- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL. + - E.G. `https://my.shaarli.domain/?do=atom&permalinks`. +- You can use `nb` parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything. + - `https://my.shaarli.domain/?do=atom&permalinks&nb=42` + - `https://my.shaarli.domain/?do=atom&permalinks&nb=all` + ### RSS Feeds or Picture Wall for a specific search/tag + It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**. For example, if you want to subscribe only to links tagged `photography`: diff --git a/doc/Release-Shaarli.html b/doc/Release-Shaarli.html new file mode 100644 index 00000000..69b49478 --- /dev/null +++ b/doc/Release-Shaarli.html @@ -0,0 +1,171 @@ + + + + + + + Shaarli – Release Shaarli + + + + + + + +

    Release Shaarli

    +

    See Git - Maintaining a project - Tagging your [](.html)
    +releases    .

    +

    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
        • +
      • +
    • a GitHub fork of Shaarli
      • +
    • 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)
      • +
    • Pandoc needs to be installed.
      • +
    +

    Bump Shaarli's version

    +
    $ cd /path/to/shaarli
+
+# create a new branch
+$ git fetch upstream
+$ git checkout upstream/master -b v0.5.0
+
+# bump the version number
+$ vim index.php shaarli_version.php
+
+# rebuild the documentation from the wiki
+$ make htmldoc
+
+# commit the changes
+$ 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
    +

    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
+
+# create a signed tag
+$ git tag -s -m "Release v0.5.0" v0.5.0
+
+# push it to "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
+
+# get the SHA1 reference of the tag
+$ 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)
    + + diff --git a/doc/Release-Shaarli.md b/doc/Release-Shaarli.md new file mode 100644 index 00000000..d5044fe9 --- /dev/null +++ b/doc/Release-Shaarli.md @@ -0,0 +1,72 @@ +#Release Shaarli +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 +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` +- a GitHub fork of Shaarli +- 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) +- [Pandoc](http://pandoc.org/) needs to be installed.[](.html) + +### Bump Shaarli's version +```bash +$ cd /path/to/shaarli + +# create a new branch +$ git fetch upstream +$ git checkout upstream/master -b v0.5.0 + +# bump the version number +$ vim index.php shaarli_version.php + +# rebuild the documentation from the wiki +$ make htmldoc + +# commit the changes +$ 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 +``` + +### Create and merge a Pull Request +This one is pretty straightforward ;-) + +### Create and push a signed tag +```bash +# update your local copy +$ 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 + +# push it to "upstream" +$ git push --tags upstream +``` + +### Verify a signed tag +[`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.[](.html) + +Let's have a look at its signature! + +```bash +$ 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 + +# 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 " [ultimate][](.html) +``` diff --git a/doc/Security.html b/doc/Security.html index 914fa507..87a4ee4b 100644 --- a/doc/Security.html +++ b/doc/Security.html @@ -4,31 +4,49 @@ - Shaarli - Security + Shaarli – Security - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -101,8 +128,8 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a .php file.
  • Even if the server does not support .htaccess files, the data file will still not be readable by URL.

  • The database looks like this:

    -
    <?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
-...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
    • +
    <?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
+...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>

  • Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg. 20110923_150523) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only A-Z a-z 0-9 - _ and @.

    • diff --git a/doc/Server-configuration.html b/doc/Server-configuration.html index 3aa89722..e1edf557 100644 --- a/doc/Server-configuration.html +++ b/doc/Server-configuration.html @@ -4,31 +4,49 @@ - Shaarli - Server configuration + Shaarli – Server configuration - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -79,10 +106,10 @@ code > span.er { color: #ff0000; font-weight: bold; }

    Example virtual host configurations for popular web servers

    Prerequisites

    +

    Shaarli

    • Shaarli is installed in a directory readable/writeable by the user
    • the correct read/write permissions have been granted to the web server user and/or group
      • @@ -90,25 +117,35 @@ code > span.er { color: #ff0000; font-weight: bold; }
    • a key pair (public, private) and a certificate have been generated
    • the appropriate server SSL extension is installed and active
    +

    HTTPS, TLS and self-signed certificates

    Related guides:

    +

    Proxies

    +

    If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:

    +
      +
    • X-Forwarded-Proto;
      • +
    • X-Forwarded-Host;
      • +
    • X-Forwarded-For.
    +

    See also proxy-related issues.

    Apache

    Minimal

    -
    <VirtualHost *:80>
+
    <VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
-</VirtualHost>
    
+</VirtualHost>

    Debug - Log all the things!

    This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.

    See:

    -
    <VirtualHost *:80>
+
    <VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 
@@ -120,24 +157,24 @@ code > span.er { color: #ff0000; font-weight: bold; }
     php_flag  display_errors on
     php_value error_reporting 2147483647
     php_value error_log /var/log/apache2/shaarli-php-error.log
-</VirtualHost>
    
+</VirtualHost>

    Standard - Keep access and error logs

    -
    <VirtualHost *:80>
+
    <VirtualHost *:80>
     ServerName   shaarli.my-domain.org
     DocumentRoot /absolute/path/to/shaarli/
 
     LogLevel  warn
     ErrorLog  /var/log/apache2/shaarli-error.log
     CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
    
+</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
-    SSLCertificateFile    /absolute/path/to/the/website/certificate.crt
+    SSLCertificateFile    /absolute/path/to/the/website/certificate.pem
     SSLCertificateKeyFile /absolute/path/to/the/website/key.key
 
     <Directory /absolute/path/to/shaarli/>
@@ -158,7 +195,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
     LogLevel  warn
     ErrorLog  /var/log/apache2/shaarli-error.log
     CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
    
+</VirtualHost>

    LightHttpd

    Nginx

    Foreword

    @@ -204,13 +241,13 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • user:group = john:users,

    • which corresponds to the following service configuration:

    -
    ; /etc/php/php-fpm.conf
+
    ; /etc/php/php-fpm.conf
 user = john
 group = users
 
 [...][](.html)
 listen.owner = john
-listen.group = users
    
+listen.group = users
    # /etc/nginx/nginx.conf
 user john users;
 
@@ -374,5 +411,10 @@ 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 c7b17c5a..fd98a608 100644 --- a/doc/Server-configuration.md +++ b/doc/Server-configuration.md @@ -2,19 +2,29 @@ *Example virtual host configurations for popular web servers* - [Apache](#apache)[](.html) -- [LightHttpd](#lighthttpd) (empty)[](.html) - [Nginx](#nginx)[](.html) ## Prerequisites +### Shaarli * Shaarli is installed in a directory readable/writeable by the user * the correct read/write permissions have been granted to the web server _user and/or group_ * for HTTPS / SSL: * a key pair (public, private) and a certificate have been generated * the appropriate server SSL extension is installed and active +### HTTPS, TLS and self-signed certificates Related guides: * [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)[](.html) * [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)[](.html) +* Generate a self-signed certificate (will trigger browser warnings) with apache2: `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key` + +### Proxies +If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set: +- `X-Forwarded-Proto`; +- `X-Forwarded-Host`; +- `X-Forwarded-For`. + +See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.[](.html) ## Apache ### Minimal @@ -29,7 +39,7 @@ This configuration will log both Apache and PHP errors, which may prove useful t See: * [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)[](.html) -* [PHP: php_value vs php_admin_value and the use of php_flag explained](PHP: php_value vs php_admin_value and the use of php_flag explained)[](.html) +* [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)[](.html) ```apache @@ -68,7 +78,7 @@ See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) DocumentRoot /absolute/path/to/shaarli/ SSLEngine on - SSLCertificateFile /absolute/path/to/the/website/certificate.crt + SSLCertificateFile /absolute/path/to/the/website/certificate.pem SSLCertificateKeyFile /absolute/path/to/the/website/key.key @@ -324,3 +334,15 @@ 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 f34f589b..ff0ad9cd 100644 --- a/doc/Server-requirements.html +++ b/doc/Server-requirements.html @@ -4,12 +4,12 @@ - Shaarli - Server requirements + Shaarli – Server requirements + -     - - - + + + - + - + - + - +
    HooksHooks Description
    render_headerrender_header Allow plugin to add content in page headers.
    render_includesrender_includes Allow plugin to include their own CSS files.
    render_footerrender_footer Allow plugin to add content in page footer and include their own JS files.
    render_linklistrender_linklist It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
    render_editlinkrender_editlink Allow to add fields in the form, or display elements.
    render_toolsrender_tools Allow to add content at the end of the page.
    render_picwallrender_picwall Allow to add content at the top and bottom of the page.
    render_tagcloudrender_tagcloud Allow to add content at the top and bottom of the page.
    render_dailyrender_daily Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
    savelinksavelink Allow to alter the link being saved in the datastore.
    7RC2planned7.0Supported✅
    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:✅
    @@ -106,32 +116,40 @@ -

    PHP 7 information:

    -

    Extensions

    - +
    +++++ - + - + - - - + + + - + + + + + + - + + + + + +
    ExtensionExtension Required?UsageUsage
    php-mbstringCentOS, Fedora, RHEL, Windowsmultibyte (Unicode) string supportopensslAllOpenSSL, HTTPS
    php-gdphp-mbstringCentOS, Fedora, RHEL, Windowsmultibyte (Unicode) string support
    php-gd -thumbnail resizingthumbnail resizing
    php-intlOptionalTag cloud intelligent sorting (eg. e->è->f)
    diff --git a/doc/Server-requirements.md b/doc/Server-requirements.md index 8f44d606..7955fddf 100644 --- a/doc/Server-requirements.md +++ b/doc/Server-requirements.md @@ -3,13 +3,14 @@ ### Release information - [PHP: Supported versions](http://php.net/supported-versions.php)[](.html) - [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_[](.html) +- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)[](.html) - [PHP 5 Changelog](http://php.net/ChangeLog-5.php)[](.html) - [PHP: Bugs](https://bugs.php.net/)[](.html) ### Supported versions Version | Status | Shaarli compatibility :---:|:---:|:---: -7 | RC2 | planned +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: @@ -18,14 +19,10 @@ Version | Status | Shaarli compatibility See also: - [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)[](.html) -PHP 7 information: -- Announcements: [Beta1](http://php.net/archive/2015.php#id2015-07-10-4), [RC1](http://php.net/archive/2015.php#id2015-08-21-1), [RC2](http://php.net/archive/2015.php#id2015-09-04-1)[](.html) -- [TODOLIST](https://wiki.php.net/todo/php70)[](.html) -- [Recent bugs](https://bugs.php.net/search.php?limit=30&order_by=id&direction=DESC&cmd=display&status=Open&bug_type=All&phpver=7.0)[](.html) -- [Git repository](http://git.php.net/?p=php-src.git;a=shortlog;h=refs/heads/PHP-7.0.0)[](.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) diff --git a/doc/Server-security.html b/doc/Server-security.html new file mode 100644 index 00000000..97f93780 --- /dev/null +++ b/doc/Server-security.html @@ -0,0 +1,166 @@ + + + + + + + Shaarli – Server security + + + + + + + +

    Server security

    +

    php.ini

    +

    PHP settings are defined in:

    + +

    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
    +

    Server environment

    + +

    fail2ban

    +

    fail2ban is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses iptables profiles to block brute-force attempts:

    + +

    Read Shaarli logs to ban IPs

    +

    Example configuration:

    + +

    /etc/fail2ban/jail.local

    +
    [shaarli-auth][](.html)
+enabled  = true
+port     = https,http
+filter   = shaarli-auth
+logpath  = /var/www/path/to/shaarli/data/log.txt
+maxretry = 3
+bantime = -1
    +

    /etc/fail2ban/filter.d/shaarli-auth.conf

    +
    [INCLUDES][](.html)
+before = common.conf
+[Definition][](.html)
+failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
+ignoreregex =
    + + diff --git a/doc/Server-security.md b/doc/Server-security.md new file mode 100644 index 00000000..0d16e284 --- /dev/null +++ b/doc/Server-security.md @@ -0,0 +1,60 @@ +#Server security +## php.ini +PHP settings are defined in: +- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g. + - `/etc/php5/php.ini` - used when running console scripts + - `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache + - `/etc/php5/php-fpm.conf` - used when PHP requests are proxied to PHP-FPM +- additional configuration files/entries, depending on the installed/enabled extensions: + - `/etc/php/conf.d/xdebug.ini` + +### Locate .ini files +#### Console environment +```bash +$ 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. + - Apache (with user dirs enabled): `/home/myself/public_html/phpinfo.php` + - `/var/www/test/phpinfo.php` +- make sure the script is readable by the web server user/group (usually, `www`, `www-data` or `httpd`) +- access the script from a web browser +- look at the _Loaded Configuration File_ and _Scan this dir for additional .ini files_ entries +```php + +``` + +## fail2ban +`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts: +- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)[](.html) +- [Source code](https://github.com/fail2ban/fail2ban)[](.html) + +### Read Shaarli logs to ban IPs +Example configuration: +- allow 3 login attempts per IP address +- after 3 failures, permanently ban the corresponding IP adddress + +`/etc/fail2ban/jail.local` +```ini +[shaarli-auth][](.html) +enabled = true +port = https,http +filter = shaarli-auth +logpath = /var/www/path/to/shaarli/data/log.txt +maxretry = 3 +bantime = -1 +``` + +`/etc/fail2ban/filter.d/shaarli-auth.conf` +```ini +[INCLUDES][](.html) +before = common.conf +[Definition][](.html) +failregex = \s-\s\s-\sLogin failed for user.*$ +ignoreregex = +``` diff --git a/doc/Shaarli-configuration.html b/doc/Shaarli-configuration.html index b7e29cb3..f53289fe 100644 --- a/doc/Shaarli-configuration.html +++ b/doc/Shaarli-configuration.html @@ -4,31 +4,49 @@ - Shaarli - Shaarli configuration + Shaarli – Shaarli configuration - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -81,6 +108,7 @@ code > span.er { color: #ff0000; font-weight: bold; }

    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 are enabled
    • its values override those defined in index.php

    File and directory permissions

    @@ -88,14 +116,14 @@ code > span.er { color: #ff0000; font-weight: bold; }
    • read access to the following resources:
        -
      • PHP scripts: index.php, application/*.php
        • -
      • 3rd party PHP and Javascript libraries: inc/*.php, inc\*.js
        • +
      • PHP scripts: index.php, application/*.php, plugins/*.php
        • +
      • 3rd party PHP and Javascript libraries: inc/*.php, inc/*.js
      • static assets:
          -
        • CSS stylesheets: inc\*.css
          • -
        • images\*
          • +
        • CSS stylesheets: inc/*.css
          • +
        • images/*
        • -
      • RainTPL templates: tpl\*.html
        • +
      • RainTPL templates: tpl/*.html
    • read, write and execution access to the following directories:
        @@ -117,7 +145,8 @@ code > span.er { color: #ff0000; font-weight: bold; }
      • if you have a domain / subdomain to serve Shaarli, configure the server accordingly

      Example data/config.php

      -
      <?php 
+
      See also Plugin System.
      
+
      <?php 
 // User login
 $GLOBALS['login'] = '<login>';[](.html)
 
@@ -146,6 +175,10 @@ code > span.er { color: #ff0000; font-weight: bold; }
 // 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)
@@ -218,6 +251,11 @@ code > span.er { color: #ff0000; font-weight: bold; }
 // 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)
+?>
    +

    Additional configuration

    +

    The playvideos plugin may require that you adapt your server's Content Security Policy configuration to work properly.

    diff --git a/doc/Shaarli-configuration.md b/doc/Shaarli-configuration.md index 5bf70a62..d0560d79 100644 --- a/doc/Shaarli-configuration.md +++ b/doc/Shaarli-configuration.md @@ -5,17 +5,18 @@ 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) * its values override those defined in `index.php` ## File and directory permissions The server process running Shaarli must have: - `read` access to the following resources: - - PHP scripts: `index.php`, `application/*.php` - - 3rd party PHP and Javascript libraries: `inc/*.php`, `inc\*.js` + - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php` + - 3rd party PHP and Javascript libraries: `inc/*.php`, `inc/*.js` - static assets: - - CSS stylesheets: `inc\*.css` - - `images\*` - - RainTPL templates: `tpl\*.html` + - CSS stylesheets: `inc/*.css` + - `images/*` + - RainTPL templates: `tpl/*.html` - `read`, `write` and `execution` access to the following directories: - `cache` - thumbnail cache - `data` - link data store, configuration options @@ -31,6 +32,8 @@ On a Linux distribution: - 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 ``` + +## 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) diff --git a/doc/Shaarli-installation.html b/doc/Shaarli-installation.html new file mode 100644 index 00000000..ae40b3a3 --- /dev/null +++ b/doc/Shaarli-installation.html @@ -0,0 +1,73 @@ + + + + + + + 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 new file mode 100644 index 00000000..be9726e0 --- /dev/null +++ b/doc/Shaarli-installation.md @@ -0,0 +1,6 @@ +#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 6fa5e77a..6dfdd564 100644 --- a/doc/Sharing-button.html +++ b/doc/Sharing-button.html @@ -4,12 +4,12 @@ - Shaarli - Sharing button + Shaarli – Sharing button + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -74,5 +83,13 @@
  • You can also check the “Private” box so that the link is saved but only visible to you.
  • Click Save.Voilà! Your link is now shared.
    • +

    Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)

    +

    Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.

    +

    See #196.

    +

    There is an open bug for both Firefox and Chromium:

    + diff --git a/doc/Sharing-button.md b/doc/Sharing-button.md index fe576a77..e4388863 100644 --- a/doc/Sharing-button.md +++ b/doc/Sharing-button.md @@ -17,3 +17,15 @@ _This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. U * You will be able to edit this link later using the ![(https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.]((https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png)-edit-button..html) * You can also check the “Private” box so that the link is saved but only visible to you. * Click `Save`.**Voilà! Your link is now shared.** + +### Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com) + +Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it. + +See [#196](https://github.com/shaarli/Shaarli#196).[](.html) + +There is an open bug for both Firefox and Chromium: + + * https://bugzilla.mozilla.org/show_bug.cgi?id=866522 + * https://code.google.com/p/chromium/issues/detail?id=233903 + diff --git a/doc/Static-analysis.html b/doc/Static-analysis.html index e95893a8..6d1695cb 100644 --- a/doc/Static-analysis.html +++ b/doc/Static-analysis.html @@ -4,12 +4,12 @@ - Shaarli - Static analysis + Shaarli – Static analysis + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/TODO.html b/doc/TODO.html index 7a6a4bf6..e7ce4f04 100644 --- a/doc/TODO.html +++ b/doc/TODO.html @@ -4,12 +4,12 @@ - Shaarli - TODO + Shaarli – TODO + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/Theming.html b/doc/Theming.html index a751eb98..1eda52e4 100644 --- a/doc/Theming.html +++ b/doc/Theming.html @@ -4,31 +4,49 @@ - Shaarli - Theming + Shaarli – Theming - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -89,14 +116,14 @@ code > span.er { color: #ff0000; font-weight: bold; }

    RainTPL template

    WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.

      -
    • Find the template you'd like to install (see the list of available templates|Theming#community-themes--templates)
      • +
    • Find the template you'd like to install (see the list of available templates|Theming#community-themes--templates)
    • 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.

      -
      $GLOBALS['config'['RAINTPL_TPL'] = 'tpl/my-template/';]('RAINTPL_TPL']-=-'tpl/my-template/';.html)
      • +
      $GLOBALS['config'['RAINTPL_TPL'] = 'tpl/my-template/';]('RAINTPL_TPL']-=-'tpl/my-template/';.html)

    Community themes & templates

      @@ -116,7 +143,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
    • 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
@@ -126,15 +153,15 @@ $ popd
 
 # set access rights for Apache
 $ chgrp -R http shaarli
-$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
    
+$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp

    Get config written:

    • go to the freshly installed site
    • fill the install form
    • log in to 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
    +

    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
    diff --git a/doc/Troubleshooting.html b/doc/Troubleshooting.html index 98fd5354..0d58f321 100644 --- a/doc/Troubleshooting.html +++ b/doc/Troubleshooting.html @@ -4,31 +4,49 @@ - Shaarli - Troubleshooting + Shaarli – Troubleshooting - +
    @@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -131,23 +158,24 @@ code > span.er { color: #ff0000; font-weight: bold; }

    Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.

    To remove the current IP bans, delete the file data/ipbans.php

    List of all login attempts

    -

    The file data/log.txt shows all logins (successful or failed) and bans/lifted bans.
    Search for failed in this file to look for unauthorized login attempts.

    +

    The file data/log.txt shows all logins (successful or failed) and bans/lifted bans.
    +Search for failed in this file to look for unauthorized login attempts.

    Hosting problems

    Old PHP versions

    • On free.fr : free.fr now support php 5.6.x(link)and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a sessions directory and a .htaccess file containing:
    -
    <IfDefine Free>
+
    <IfDefine Free>
 php56 1
-</IfDefine>
    
+</IfDefine>
    • If you have an error such as: Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to .php5
    • On 1and1 : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
    • If you have the error Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
    -
    //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
+
    //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
 // FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html 
-//if (strpos($status,'200 OK')) $title=html_extract_title($data);
    
+//if (strpos($status,'200 OK')) $title=html_extract_title($data);
    • On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
    • On lost-oasis, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : <? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>. To fix this, remove this message from php-include/prepend.php
      • diff --git a/doc/Unit-tests.html b/doc/Unit-tests.html index 6d760771..b933bc7c 100644 --- a/doc/Unit-tests.html +++ b/doc/Unit-tests.html @@ -4,31 +4,49 @@ - Shaarli - Unit tests + Shaarli – Unit tests - +
    +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -84,27 +111,27 @@ code > span.er { color: #ff0000; font-weight: bold; }
  • a local version, downloadable here

    • Sample usage

    -
    # system-wide version
+
    # system-wide version
 $ composer install
 $ composer update
 
 # local version
 $ php composer.phar self-update
 $ php composer.phar install
-$ php composer.phar update
    
+$ 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
    +
    zend_extension=xdebug.so

    Run unit tests

    Successful test suite:

    -
    $ make test
+
    $ make test
 
 -------
 PHPUNIT
@@ -117,9 +144,9 @@ $ composer update
    
 
 Time: 759 ms, Memory: 8.25Mb
 
-OK (36 tests, 65 assertions)
    +OK (36 tests, 65 assertions)

    Test suite with failures and errors:

    -
    $ make test
+
    $ make test
 -------
 PHPUNIT
 -------
@@ -165,7 +192,7 @@ DBTest.php on line 79 and defined
 /home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
 
 FAILURES!
-Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
    
+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-from-original-sebsauvage-Shaarli.html b/doc/Upgrade-from-original-sebsauvage-Shaarli.html new file mode 100644 index 00000000..5297c8bb --- /dev/null +++ b/doc/Upgrade-from-original-sebsauvage-Shaarli.html @@ -0,0 +1,75 @@ + + + + + + + Shaarli – Upgrade from original sebsauvage Shaarli + + + + + +
    + +
    +

    Upgrade from original sebsauvage Shaarli

    + + + diff --git a/doc/Upgrade-from-original-sebsauvage-Shaarli.md b/doc/Upgrade-from-original-sebsauvage-Shaarli.md new file mode 100644 index 00000000..6ae0c67b --- /dev/null +++ b/doc/Upgrade-from-original-sebsauvage-Shaarli.md @@ -0,0 +1,4 @@ +#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 0ba457f6..5b4b8a5f 100644 --- a/doc/Usage.html +++ b/doc/Usage.html @@ -4,12 +4,12 @@ - Shaarli - Usage + Shaarli – Usage + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/_Footer.html b/doc/_Footer.html index 98032386..8cc166ac 100644 --- a/doc/_Footer.html +++ b/doc/_Footer.html @@ -4,12 +4,12 @@ - Shaarli - _Footer + Shaarli – _Footer + - -

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

    +

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

    diff --git a/doc/_Sidebar.html b/doc/_Sidebar.html index fbf6dffd..2c7d2837 100644 --- a/doc/_Sidebar.html +++ b/doc/_Sidebar.html @@ -4,12 +4,12 @@ - Shaarli - _Sidebar + Shaarli – _Sidebar + -
    @@ -20,18 +20,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -43,6 +51,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • @@ -64,18 +73,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -87,6 +104,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md index 68e3b9f3..4522c254 100644 --- a/doc/_Sidebar.md +++ b/doc/_Sidebar.md @@ -4,14 +4,22 @@ - [Download](Download.html) - [Server requirements](Server-requirements.html) - [Server configuration](Server-configuration.html) + - [Server security](Server-security.html) + - [Shaarli installation](Shaarli-installation.html) - [Shaarli configuration](Shaarli-configuration.html) + - [Plugin installation & configuration](Plugin-installation-&-configuration.html) +- [Docker](Docker.html) +- [Plugin list](Plugin-list.html) - [Usage](Usage.html) - [Sharing button](Sharing-button.html) (bookmarklet) + - [Browsing and Searching](Browsing-and-Searching.html) - [Firefox share](Firefox-share.html) - [RSS feeds](RSS-feeds.html) - How To - [Backup, restore, import and export](Backup,-restore,-import-and-export.html) + - [Upgrade from original sebsauvage/Shaarli](Upgrade-from-original-sebsauvage/Shaarli.html) - [Copy an existing installation over SSH and serve it locally](Copy-an-existing-installation-over-SSH-and-serve-it-locally.html) + - [Create and serve multiple Shaarlis (farm)](Create-and-serve-multiple-Shaarlis-(farm).html) - [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html) - [Datastore hacks](Datastore-hacks.html) - [Troubleshooting](Troubleshooting.html) @@ -21,6 +29,7 @@ - [Directory structure](Directory-structure.html) - [3rd party libraries](3rd-party-libraries.html) - [Plugin System](Plugin-System.html) + - [Release Shaarli](Release-Shaarli.html) - [Security](Security.html) - [Static analysis](Static-analysis.html) - [Theming](Theming.html) diff --git a/doc/images/doc-logo.svg b/doc/images/doc-logo.svg new file mode 100644 index 00000000..37fc6658 --- /dev/null +++ b/doc/images/doc-logo.svg @@ -0,0 +1,522 @@ + + + Shaarli Logo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + Shaarli Logo + + + http://blog.idleman.fr/ + + + 2012-08-29 22:36:01+02:00 + + + http://sebsauvage.net/ + + + + + Shaarli + Logo + + + + + http://thatguynamedandy.com/, +http://mro.name/me + + + + http://sebsauvage.net/files/shaarli_logo.zip + http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion#comment_09a1e91bc0abc7db6d186a6abf429877 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/sidebar.html b/doc/sidebar.html index 826e4cb2..8603ecac 100644 --- a/doc/sidebar.html +++ b/doc/sidebar.html @@ -6,18 +6,26 @@
  • Download
  • Server requirements
  • Server configuration
    • +
  • Server security
    • +
  • Shaarli installation
  • Shaarli configuration
    • +
  • Plugin installation & configuration
    • +
  • Docker
    • +
  • Plugin list
  • Usage
  • How To
    • @@ -29,6 +37,7 @@
  • Directory structure
  • 3rd party libraries
  • Plugin System
    • +
  • Release Shaarli
  • Security
  • Static analysis
  • Theming
    • -- cgit v1.2.3