aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2015-04-05 22:37:15 +0200
committernodiscc <nodiscc@gmail.com>2015-04-05 22:37:15 +0200
commit7a32b172b82c2571d39d0b239e06d6be73b174f3 (patch)
treeb46a4f02f67103d511671d682aa83063fded74d6 /doc
parent82af78b272ab0036eec289eb338934736aabbdc2 (diff)
downloadShaarli-7a32b172b82c2571d39d0b239e06d6be73b174f3.tar.gz
Shaarli-7a32b172b82c2571d39d0b239e06d6be73b174f3.tar.zst
Shaarli-7a32b172b82c2571d39d0b239e06d6be73b174f3.zip
add local HTML documentation
generated with 'make htmldoc'
Diffstat (limited to 'doc')
-rw-r--r--doc/Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli.html75
-rw-r--r--doc/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file.html167
-rw-r--r--doc/Example-patch---add-new-via-field-for-links.html201
-rw-r--r--doc/Home.html368
-rw-r--r--doc/Ideas-for-plugins.html26
-rw-r--r--doc/_Sidebar.html70
6 files changed, 907 insertions, 0 deletions
diff --git a/doc/Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli.html b/doc/Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli.html
new file mode 100644
index 00000000..25e4bc6b
--- /dev/null
+++ b/doc/Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli.html
@@ -0,0 +1,75 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title></title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link rel="stylesheet" href="github-markdown.css">
13</head>
14<body>
15<p>Example bash script:</p>
16<pre><code>#!/bin/bash
17#Description: Copy a Shaarli installation over SSH/SCP, serve it locally with php-cli
18#Will create a local-shaarli/ directory when you run it, backup your Shaarli there, and serve it locally.
19#Will NOT download linked pages. It&#39;s just a directly usable backup/copy/mirror of your Shaarli
20#Requires: ssh, scp and a working SSH access to the server where your Shaarli is installed
21#Usage: ./local-shaarli.sh
22#Author: nodiscc (nodiscc@gmail.com)
23#License: MIT (http://opensource.org/licenses/MIT)
24set -o errexit
25set -o nounset
26
27##### CONFIG #################
28#The port used by php&#39;s local server
29php_local_port=7431
30
31#Name of the SSH server and path where Shaarli is installed
32#TODO: pass these as command-line arguments
33remotehost=&quot;my.ssh.server&quot;
34remote_shaarli_dir=&quot;/var/www/shaarli&quot;
35
36
37###### FUNCTIONS #############
38_main() {
39 _CBSyncShaarli
40 _CBServeShaarli
41}
42
43_CBSyncShaarli() {
44 remote_temp_dir=$(ssh $remotehost mktemp -d)
45 remote_ssh_user=$(ssh $remotehost whoami)
46 ssh -t &quot;$remotehost&quot; sudo cp -r &quot;$remote_shaarli_dir&quot; &quot;$remote_temp_dir&quot;
47 ssh -t &quot;$remotehost&quot; sudo chown -R &quot;$remote_ssh_user&quot;:&quot;$remote_ssh_user&quot; &quot;$remote_temp_dir&quot;
48 scp -rq &quot;$remotehost&quot;:&quot;$remote_temp_dir&quot; local-shaarli
49 ssh &quot;$remotehost&quot; rm -r &quot;$remote_temp_dir&quot;
50}
51
52_CBServeShaarli() {
53 #TODO: allow serving a previously downloaded Shaarli
54 #TODO: ask before overwriting local copy, if it exists
55 cd local-shaarli/
56 php -S localhost:${php_local_port}
57 echo &quot;Please go to http://localhost:${php_local_port}&quot;
58}
59
60
61##### MAIN #################
62
63_main</code></pre>
64<p>This outputs:</p>
65<pre><code>$ ./local-shaarli.sh
66PHP 5.6.0RC4 Development Server started at Mon Sep 1 21:56:19 2014
67Listening on http://localhost:7431
68Document root is /home/user/local-shaarli/shaarli
69Press Ctrl-C to quit.
70
71[Mon Sep 1 21:56:27 2014] ::1:57868 [200]: /
72[Mon Sep 1 21:56:27 2014] ::1:57869 [200]: /index.html
73[Mon Sep 1 21:56:37 2014] ::1:57881 [200]: /...</code></pre>
74</body>
75</html>
diff --git a/doc/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file.html b/doc/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file.html
new file mode 100644
index 00000000..0f32fb84
--- /dev/null
+++ b/doc/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file.html
@@ -0,0 +1,167 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title></title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link rel="stylesheet" href="github-markdown.css">
13</head>
14<body>
15<h3 id="download-css-styles-for-shaarlis-listed-in-an-opml-file">Download CSS styles for shaarlis listed in an opml file</h3>
16<p>Example php script:</p>
17<pre><code>&lt;!---- ?php --&gt;
18&lt;!---- Copyright (c) 2014 Nicolas Delsaux (https://github.com/Riduidel) --&gt;
19&lt;!---- License: zlib (http://www.gzip.org/zlib/zlib_license.html) --&gt;
20
21/**
22 * Source: https://github.com/Riduidel
23 * Download css styles for shaarlis listed in an opml file
24 */
25define(&quot;SHAARLI_RSS_OPML&quot;, &quot;https://www.ecirtam.net/shaarlirss/custom/people.opml&quot;);
26
27define(&quot;THEMES_TEMP_FOLDER&quot;, &quot;new_themes&quot;);
28
29if(!file_exists(THEMES_TEMP_FOLDER)) {
30 mkdir(THEMES_TEMP_FOLDER);
31}
32
33function siteUrl($pathInSite) {
34 $indexPos = strpos($pathInSite, &quot;index.php&quot;);
35 if(!$indexPos) {
36 return $pathInSite;
37 } else {
38 return substr($pathInSite, 0, $indexPos);
39 }
40}
41
42function createShaarliHashFromOPMLL($opmlFile) {
43 $result = array();
44 $opml = file_get_contents($opmlFile);
45 $opmlXml = simplexml_load_string($opml);
46 $outlineElements = $opmlXml-&gt;xpath(&quot;body/outline&quot;);
47 foreach($outlineElements as $site) {
48 $siteUrl = siteUrl((string) $site[&#39;htmlUrl&#39;]);
49 $result[$siteUrl]=((string) $site[&#39;text&#39;]);
50 }
51 return $result;
52}
53
54function getSiteFolder($url) {
55 $domain = parse_url($url, PHP_URL_HOST);
56 return THEMES_TEMP_FOLDER.&quot;/&quot;.str_replace(&quot;.&quot;, &quot;_&quot;, $domain);
57}
58
59function get_http_response_code($theURL) {
60 $headers = get_headers($theURL);
61 return substr($headers[0], 9, 3);
62}
63
64/**
65 * This makes the code PHP-5 only (particularly the call to &quot;get_headers&quot;)
66 */
67function copyUserStyleFrom($url, $name, $knownStyles) {
68 $userStyle = $url.&quot;inc/user.css&quot;;
69 if(in_array($url, $knownStyles)) {
70 // TODO add log message
71 } else {
72 $statusCode = get_http_response_code($userStyle);
73 if(intval($statusCode)&lt;300) {
74 $styleSheet = file_get_contents($userStyle);
75 $siteFolder = getSiteFolder($url);
76 if(!file_exists($siteFolder)) {
77 mkdir($siteFolder);
78 }
79 if(!file_exists($siteFolder.&#39;/user.css&#39;)) {
80 // Copy stylesheet
81 file_put_contents($siteFolder.&#39;/user.css&#39;, $styleSheet);
82 }
83 if(!file_exists($siteFolder.&#39;/README.md&#39;)) {
84 // Then write a readme.md file
85 file_put_contents($siteFolder.&#39;/README.md&#39;,
86 &quot;User style from &quot;.$name.&quot;\n&quot;
87 .&quot;=============================&quot;
88 .&quot;\n\n&quot;
89 .&quot;This stylesheet was downloaded from &quot;.$userStyle.&quot; on &quot;.date(DATE_RFC822)
90 );
91 }
92 if(!file_exists($siteFolder.&#39;/config.ini&#39;)) {
93 // Write a config file containing useful informations
94 file_put_contents($siteFolder.&#39;/config.ini&#39;,
95 &quot;site_url=&quot;.$url.&quot;\n&quot;
96 .&quot;site_name=&quot;.$name.&quot;\n&quot;
97 );
98 }
99 if(!file_exists($siteFolder.&#39;/home.png&#39;)) {
100 // And finally copy generated thumbnail
101 $homeThumb = $siteFolder.&#39;/home.png&#39;;
102 file_put_contents($siteFolder.&#39;/home.png&#39;, file_get_contents(getThumbnailUrl($url)));
103 }
104 echo &#39;Theme have been downloaded from &lt;a href=&quot;&#39;.$url.&#39;&quot;&gt;&#39;.$url.&#39;&lt;/a&gt; into &#39;.$siteFolder
105 .&#39;. It looks like &lt;img src=&quot;&#39;.$homeThumb.&#39;&quot;&gt;&lt;br/&gt;&#39;;
106 }
107 }
108}
109
110function getThumbnailUrl($url) {
111 return &#39;http://api.webthumbnail.org/?url=&#39;.$url;
112}
113
114function copyUserStylesFrom($urlToNames, $knownStyles) {
115 foreach($urlToNames as $url =&gt; $name) {
116 copyUserStyleFrom($url, $name, $knownStyles);
117 }
118}
119
120/**
121 * Reading directory list, courtesy of http://www.laughing-buddha.net/php/dirlist/
122 * @param directory the directory we want to list files of
123 * @return a simple array containing the list of absolute file paths. Notice that current file (&quot;.&quot;) and parent one(&quot;..&quot;)
124 * are not listed here
125 */
126function getDirectoryList ($directory) {
127 $realPath = realpath($directory);
128 // create an array to hold directory list
129 $results = array();
130 // create a handler for the directory
131 $handler = opendir($directory);
132 // open directory and walk through the filenames
133 while ($file = readdir($handler)) {
134 // if file isn&#39;t this directory or its parent, add it to the results
135 if ($file != &quot;.&quot; &amp;&amp; $file != &quot;..&quot;) {
136 $results[] = realpath($realPath . &quot;/&quot; . $file);
137 }
138 }
139 // tidy up: close the handler
140 closedir($handler);
141 // done!
142 return $results;
143}
144
145/**
146 * Start in themes folder and look in all subfolders for config.ini files.
147 * These config.ini files allow us not to download styles again and again
148 */
149function findKnownStyles() {
150 $result = array();
151 $subFolders = getDirectoryList(&quot;themes&quot;);
152 foreach($subFolders as $folder) {
153 $configFile = $folder.&quot;/config.ini&quot;;
154 if(file_exists($configFile)) {
155 $iniParameters = parse_ini_file($configFile);
156 array_push($result, $iniParameters[&#39;site_url&#39;]);
157 }
158 }
159 return $result;
160}
161
162$knownStyles = findKnownStyles();
163copyUserStylesFrom(createShaarliHashFromOPMLL(SHAARLI_RSS_OPML), $knownStyles);
164
165&lt;!--- ? ----&gt;</code></pre>
166</body>
167</html>
diff --git a/doc/Example-patch---add-new-via-field-for-links.html b/doc/Example-patch---add-new-via-field-for-links.html
new file mode 100644
index 00000000..7df9d253
--- /dev/null
+++ b/doc/Example-patch---add-new-via-field-for-links.html
@@ -0,0 +1,201 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title></title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link rel="stylesheet" href="github-markdown.css">
13</head>
14<body>
15<p>Example patch to add a new field (&quot;via&quot;) for links, an input field to set the &quot;via&quot; property from the &quot;edit link&quot; dialog, and display the &quot;via&quot; field in the link list display. <strong>Untested, use at your own risk</strong></p>
16<p>Thanks to @Knah-Tsaeb in <a href="https://github.com/sebsauvage/Shaarli/pull/158">https://github.com/sebsauvage/Shaarli/pull/158</a></p>
17<pre><code>From e0f363c18e8fe67990ed2bb1a08652e24e70bbcb Mon Sep 17 00:00:00 2001
18From: Knah Tsaeb &lt;knah-tsaeb@knah-tsaeb.org&gt;
19Date: Fri, 11 Oct 2013 15:18:37 +0200
20Subject: [PATCH] Add a &quot;via&quot;/origin property for links, add new input in &quot;edit link&quot; dialog
21Thanks to:
22* https://github.com/Knah-Tsaeb/Shaarli/commit/040eb18ec8cdabd5ea855e108f81f97fbf0478c4
23* https://github.com/Knah-Tsaeb/Shaarli/commit/4123658eae44d7564d1128ce52ddd5689efee813
24* https://github.com/Knah-Tsaeb/Shaarli/commit/f1a8ca9cc8fe49b119d51b2d8382cc1a34542f96
25
26---
27 index.php | 43 ++++++++++++++++++++++++++++++++-----------
28 tpl/editlink.html | 1 +
29 tpl/linklist.html | 1 +
30 3 files changed, 34 insertions(+), 11 deletions(-)
31
32diff --git a/index.php b/index.php
33index 6fae2f8..53f798e 100644
34--- a/index.php
35+++ b/index.php
36@@ -436,6 +436,12 @@ if (isset($_POST[&#39;login&#39;]))
37 // ------------------------------------------------------------------------------------------
38 // Misc utility functions:
39
40+// Try to get just domain for @via
41+function getJustDomain($url){
42+ $parts = parse_url($url);
43+ return trim($parts[&#39;host&#39;]);
44+ }
45+
46 // Returns the server URL (including port and http/https), without path.
47 // e.g. &quot;http://myserver.com:8080&quot;
48 // You can append $_SERVER[&#39;SCRIPT_NAME&#39;] to get the current script URL.
49@@ -799,7 +805,8 @@ class linkdb implements Iterator, Countable, ArrayAccess
50 $found= (strpos(strtolower($l[&#39;title&#39;]),$s)!==false)
51 || (strpos(strtolower($l[&#39;description&#39;]),$s)!==false)
52 || (strpos(strtolower($l[&#39;url&#39;]),$s)!==false)
53- || (strpos(strtolower($l[&#39;tags&#39;]),$s)!==false);
54+ || (strpos(strtolower($l[&#39;tags&#39;]),$s)!==false)
55+ || (!empty($l[&#39;via&#39;]) &amp;&amp; (strpos(strtolower($l[&#39;via&#39;]),$s)!==false));
56 if ($found) $filtered[$l[&#39;linkdate&#39;]] = $l;
57 }
58 krsort($filtered);
59@@ -814,7 +821,7 @@ class linkdb implements Iterator, Countable, ArrayAccess
60 $t = str_replace(&#39;,&#39;,&#39; &#39;,($casesensitive?$tags:strtolower($tags)));
61 $searchtags=explode(&#39; &#39;,$t);
62 $filtered=array();
63- foreach($this-&gt;links as $l)
64+ foreach($this-&gt; links as $l)
65 {
66 $linktags = explode(&#39; &#39;,($casesensitive?$l[&#39;tags&#39;]:strtolower($l[&#39;tags&#39;])));
67 if (count(array_intersect($linktags,$searchtags)) == count($searchtags))
68@@ -905,7 +912,7 @@ function showRSS()
69 else $linksToDisplay = $LINKSDB;
70 $nblinksToDisplay = 50; // Number of links to display.
71 if (!empty($_GET[&#39;nb&#39;])) // In URL, you can specificy the number of links. Example: nb=200 or nb=all for all links.
72- {
73+ {
74 $nblinksToDisplay = $_GET[&#39;nb&#39;]==&#39;all&#39; ? count($linksToDisplay) : max($_GET[&#39;nb&#39;]+0,1) ;
75 }
76
77@@ -944,7 +951,12 @@ function showRSS()
78 // If user wants permalinks first, put the final link in description
79 if ($usepermalinks===true) $descriptionlink = &#39;(&lt;a href=&quot;&#39;.$absurl.&#39;&quot;&gt;Link&lt;/a&gt;)&#39;;
80 if (strlen($link[&#39;description&#39;])&gt;0) $descriptionlink = &#39;&lt;br&gt;&#39;.$descriptionlink;
81- echo &#39;&lt;description&gt;&lt;![CDATA[&#39;.nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link[&#39;description&#39;])))).$descriptionlink.&#39;]]&gt;&lt;/description&gt;&#39;.&quot;\n&lt;/item&gt;\n&quot;;
82+ if(!empty($link[&#39;via&#39;])){
83+ $via = &#39;&lt;br&gt;Origine =&gt; &lt;a href=&quot;&#39;.htmlspecialchars($link[&#39;via&#39;]).&#39;&quot;&gt;&#39;.htmlspecialchars(getJustDomain($link[&#39;via&#39;])).&#39;&lt;/a&gt;&#39;;
84+ } else {
85+ $via = &#39;&#39;;
86+ }
87+ echo &#39;&lt;description&gt;&lt;![CDATA[&#39;.nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link[&#39;description&#39;])))).$via.$descriptionlink.&#39;]]&gt;&lt;/description&gt;&#39;.&quot;\n&lt;/item&gt;\n&quot;;
88 $i++;
89 }
90 echo &#39;&lt;/channel&gt;&lt;/rss&gt;&lt;!-- Cached version of &#39;.htmlspecialchars(pageUrl()).&#39; --&gt;&#39;;
91@@ -980,7 +992,7 @@ function showATOM()
92 else $linksToDisplay = $LINKSDB;
93 $nblinksToDisplay = 50; // Number of links to display.
94 if (!empty($_GET[&#39;nb&#39;])) // In URL, you can specificy the number of links. Example: nb=200 or nb=all for all links.
95- {
96+ {
97 $nblinksToDisplay = $_GET[&#39;nb&#39;]==&#39;all&#39; ? count($linksToDisplay) : max($_GET[&#39;nb&#39;]+0,1) ;
98 }
99
100@@ -1006,11 +1018,16 @@ function showATOM()
101
102 // Add permalink in description
103 $descriptionlink = htmlspecialchars(&#39;(&lt;a href=&quot;&#39;.$guid.&#39;&quot;&gt;Permalink&lt;/a&gt;)&#39;);
104+ if(isset($link[&#39;via&#39;]) &amp;&amp; !empty($link[&#39;via&#39;])){
105+ $via = htmlspecialchars(&#39;&lt;/br&gt; Origine =&gt; &lt;a href=&quot;&#39;.$link[&#39;via&#39;].&#39;&quot;&gt;&#39;.getJustDomain($link[&#39;via&#39;]).&#39;&lt;/a&gt;&#39;);
106+ } else {
107+ $via = &#39;&#39;;
108+ }
109 // If user wants permalinks first, put the final link in description
110 if ($usepermalinks===true) $descriptionlink = htmlspecialchars(&#39;(&lt;a href=&quot;&#39;.$absurl.&#39;&quot;&gt;Link&lt;/a&gt;)&#39;);
111 if (strlen($link[&#39;description&#39;])&gt;0) $descriptionlink = &#39;&amp;lt;br&amp;gt;&#39;.$descriptionlink;
112
113- $entries.=&#39;&lt;content type=&quot;html&quot;&gt;&#39;.htmlspecialchars(nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link[&#39;description&#39;]))))).$descriptionlink.&quot;&lt;/content&gt;\n&quot;;
114+ $entries.=&#39;&lt;content type=&quot;html&quot;&gt;&#39;.htmlspecialchars(nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link[&#39;description&#39;]))))).$descriptionlink.$via.&quot;&lt;/content&gt;\n&quot;;
115 if ($link[&#39;tags&#39;]!=&#39;&#39;) // Adding tags to each ATOM entry (as mentioned in ATOM specification)
116 {
117 foreach(explode(&#39; &#39;,$link[&#39;tags&#39;]) as $tag)
118@@ -1478,7 +1495,7 @@ function renderPage()
119 if (!startsWith($url,&#39;http:&#39;) &amp;&amp; !startsWith($url,&#39;https:&#39;) &amp;&amp; !startsWith($url,&#39;ftp:&#39;) &amp;&amp; !startsWith($url,&#39;magnet:&#39;) &amp;&amp; !startsWith($url,&#39;?&#39;))
120 $url = &#39;http://&#39;.$url;
121 $link = array(&#39;title&#39;=&gt;trim($_POST[&#39;lf_title&#39;]),&#39;url&#39;=&gt;$url,&#39;description&#39;=&gt;trim($_POST[&#39;lf_description&#39;]),&#39;private&#39;=&gt;(isset($_POST[&#39;lf_private&#39;]) ? 1 : 0),
122- &#39;linkdate&#39;=&gt;$linkdate,&#39;tags&#39;=&gt;str_replace(&#39;,&#39;,&#39; &#39;,$tags));
123+ &#39;linkdate&#39;=&gt;$linkdate,&#39;tags&#39;=&gt;str_replace(&#39;,&#39;,&#39; &#39;,$tags), &#39;via&#39;=&gt;trim($_POST[&#39;lf_via&#39;]));
124 if ($link[&#39;title&#39;]==&#39;&#39;) $link[&#39;title&#39;]=$link[&#39;url&#39;]; // If title is empty, use the URL as title.
125 $LINKSDB[$linkdate] = $link;
126 $LINKSDB-&gt;savedb(); // Save to disk.
127@@ -1556,7 +1573,8 @@ function renderPage()
128 $title = (empty($_GET[&#39;title&#39;]) ? &#39;&#39; : $_GET[&#39;title&#39;] ); // Get title if it was provided in URL (by the bookmarklet).
129 $description = (empty($_GET[&#39;description&#39;]) ? &#39;&#39; : $_GET[&#39;description&#39;]); // Get description if it was provided in URL (by the bookmarklet). [Bronco added that]
130 $tags = (empty($_GET[&#39;tags&#39;]) ? &#39;&#39; : $_GET[&#39;tags&#39;] ); // Get tags if it was provided in URL
131- $private = (!empty($_GET[&#39;private&#39;]) &amp;&amp; $_GET[&#39;private&#39;] === &quot;1&quot; ? 1 : 0); // Get private if it was provided in URL
132+ $via = (empty($_GET[&#39;via&#39;]) ? &#39;&#39; : $_GET[&#39;via&#39;] );
133+ $private = (!empty($_GET[&#39;private&#39;]) &amp;&amp; $_GET[&#39;private&#39;] === &quot;1&quot; ? 1 : 0); // Get private if it was provided in URL
134 if (($url!=&#39;&#39;) &amp;&amp; parse_url($url,PHP_URL_SCHEME)==&#39;&#39;) $url = &#39;http://&#39;.$url;
135 // If this is an HTTP link, we try go get the page to extract the title (otherwise we will to straight to the edit form.)
136 if (empty($title) &amp;&amp; parse_url($url,PHP_URL_SCHEME)==&#39;http&#39;)
137@@ -1567,7 +1585,7 @@ function renderPage()
138 {
139 // Look for charset in html header.
140 preg_match(&#39;#&lt;meta .*charset=.*&gt;#Usi&#39;, $data, $meta);
141-
142+
143 // If found, extract encoding.
144 if (!empty($meta[0]))
145 {
146@@ -1577,7 +1595,7 @@ function renderPage()
147 $html_charset = (!empty($enc[1])) ? strtolower($enc[1]) : &#39;utf-8&#39;;
148 }
149 else { $html_charset = &#39;utf-8&#39;; }
150-
151+
152 // Extract title
153 $title = html_extract_title($data);
154 if (!empty($title))
155@@ -1592,7 +1610,7 @@ function renderPage()
156 $url=&#39;?&#39;.smallHash($linkdate);
157 $title=&#39;Note: &#39;;
158 }
159- $link = array(&#39;linkdate&#39;=&gt;$linkdate,&#39;title&#39;=&gt;$title,&#39;url&#39;=&gt;$url,&#39;description&#39;=&gt;$description,&#39;tags&#39;=&gt;$tags,&#39;private&#39;=&gt;$private);
160+ $link = array(&#39;linkdate&#39;=&gt;$linkdate,&#39;title&#39;=&gt;$title,&#39;url&#39;=&gt;$url,&#39;description&#39;=&gt;$description,&#39;tags&#39;=&gt;$tags,&#39;via&#39; =&gt; $via,&#39;private&#39;=&gt;$private);
161 }
162
163 $PAGE = new pageBuilder;
164@@ -1842,6 +1860,9 @@ function buildLinkList($PAGE,$LINKSDB)
165 $taglist = explode(&#39; &#39;,$link[&#39;tags&#39;]);
166 uasort($taglist, &#39;strcasecmp&#39;);
167 $link[&#39;taglist&#39;]=$taglist;
168+ if(!empty($link[&#39;via&#39;])){
169+ $link[&#39;via&#39;]=htmlspecialchars($link[&#39;via&#39;]);
170+ }
171 $linkDisp[$keys[$i]] = $link;
172 $i++;
173 }
174diff --git a/tpl/editlink.html b/tpl/editlink.html
175index 4a2c30c..14d4f9c 100644
176--- a/tpl/editlink.html
177+++ b/tpl/editlink.html
178@@ -16,6 +16,7 @@
179 &lt;i&gt;Title&lt;/i&gt;&lt;br&gt;&lt;input type=&quot;text&quot; name=&quot;lf_title&quot; value=&quot;{$link.title|htmlspecialchars}&quot; style=&quot;width:100%&quot;&gt;&lt;br&gt;
180 &lt;i&gt;Description&lt;/i&gt;&lt;br&gt;&lt;textarea name=&quot;lf_description&quot; rows=&quot;4&quot; cols=&quot;25&quot; style=&quot;width:100%&quot;&gt;{$link.description|htmlspecialchars}&lt;/textarea&gt;&lt;br&gt;
181 &lt;i&gt;Tags&lt;/i&gt;&lt;br&gt;&lt;input type=&quot;text&quot; id=&quot;lf_tags&quot; name=&quot;lf_tags&quot; value=&quot;{$link.tags|htmlspecialchars}&quot; style=&quot;width:100%&quot;&gt;&lt;br&gt;
182+ &lt;i&gt;Origine&lt;/i&gt;&lt;br&gt;&lt;input type=&quot;text&quot; name=&quot;lf_via&quot; value=&quot;{$link.via|htmlspecialchars}&quot; style=&quot;width:100%&quot;&gt;&lt;br&gt;
183 {if condition=&quot;($link_is_new &amp;&amp; $GLOBALS[&#39;privateLinkByDefault&#39;]==true) || $link.private == true&quot;}
184 &lt;input type=&quot;checkbox&quot; checked=&quot;checked&quot; name=&quot;lf_private&quot; id=&quot;lf_private&quot;&gt;
185 &amp;nbsp;&lt;label for=&quot;lf_private&quot;&gt;&lt;i&gt;Private&lt;/i&gt;&lt;/label&gt;&lt;br&gt;
186diff --git a/tpl/linklist.html b/tpl/linklist.html
187index ddc38cb..0a8475f 100644
188--- a/tpl/linklist.html
189+++ b/tpl/linklist.html
190@@ -43,6 +43,7 @@
191 &lt;span class=&quot;linktitle&quot;&gt;&lt;a href=&quot;{$redirector}{$value.url|htmlspecialchars}&quot;&gt;{$value.title|htmlspecialchars}&lt;/a&gt;&lt;/span&gt;
192 &lt;br&gt;
193 {if=&quot;$value.description&quot;}&lt;div class=&quot;linkdescription&quot;{if condition=&quot;$search_type==&#39;permalink&#39;&quot;} style=&quot;max-height:none !important;&quot;{/if}&gt;{$value.description}&lt;/div&gt;{/if}
194+ {if condition=&quot;isset($value.via) &amp;&amp; !empty($value.via)&quot;}&lt;div&gt;&lt;a href=&quot;{$value.via}&quot;&gt;Origine =&gt; {$value.via|getJustDomain}&lt;/a&gt;&lt;/div&gt;{/if}
195 {if=&quot;!$GLOBALS[&#39;config&#39;][&#39;HIDE_TIMESTAMPS&#39;] || isLoggedIn()&quot;}
196 &lt;span class=&quot;linkdate&quot; title=&quot;Permalink&quot;&gt;&lt;a href=&quot;?{$value.linkdate|smallHash}&quot;&gt;{$value.localdate|htmlspecialchars} - permalink&lt;/a&gt; - &lt;/span&gt;
197 {else}
198--
1992.1.1</code></pre>
200</body>
201</html>
diff --git a/doc/Home.html b/doc/Home.html
new file mode 100644
index 00000000..e4d117f1
--- /dev/null
+++ b/doc/Home.html
@@ -0,0 +1,368 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title></title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link rel="stylesheet" href="github-markdown.css">
13</head>
14<body>
15<h1 id="shaarli-wiki">Shaarli wiki</h1>
16<p>Welcome to the <a href="https://github.com/shaarli/Shaarli/">Shaarli</a> wiki! Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. For general info, read the <a href="https://github.com/shaarli/Shaarli/blob/master/README.md">README</a>.</p>
17<p>If you have any questions or ideas, please join the <a href="https://gitter.im/shaarli/Shaarli">chat</a> (also reachable via <a href="https://irc.gitter.im/">IRC</a>), post them in our <a href="https://github.com/shaarli/Shaarli/issues/44">general discussion</a> or read the current <a href="https://github.com/shaarli/Shaarli/issues">issues</a>. If you've found a bug, please create a <a href="https://github.com/shaarli/Shaarli/issues/new">new issue</a>.</p>
18<p>If you'd like a feature added, see if it fits in the list of <a href="Ideas-for-plugins">Ideas for Plugins</a> and update the corresponding bug report.</p>
19<p><em>Note: This documentation is available online at <a href="https://github.com/shaarli/Shaarli/wiki">https://github.com/shaarli/Shaarli/wiki</a>, and locally in the <code>doc/</code> directory of your Shaarli installation.</em></p>
20<hr />
21<!-- MarkdownTOC depth=3 -->
22
23
24<ul>
25<li><p><a href="#basic-usage">Basic Usage</a></p>
26<ul>
27<li><a href="#add-the-sharing-button-_bookmarklet_-to-your-browser">Add the sharing button (<em>bookmarklet</em>) to your browser</a><br /></li>
28<li><a href="#share-links-using-the-_bookmarklet_">Share links using the <em>bookmarklet</em></a><br /></li>
29</ul></li>
30<li><p><a href="#other-usage-examples">Other usage examples</a></p>
31<ul>
32<li><a href="#using-shaarli-as-a-blog-notepad-pastebin">Using Shaarli as a blog, notepad, pastebin...</a><br /></li>
33<li><a href="#rss-feeds-or-picture-wall-for-a-specific-searchtag">RSS Feeds or Picture Wall for a specific search/tag</a><br /></li>
34</ul></li>
35<li><p><a href="#configuration">Configuration</a></p>
36<ul>
37<li><a href="#main-dataoptionsphp-file">Main data/options.php file</a><br /></li>
38<li><a href="#changing-theme">Changing theme</a><br /></li>
39<li><a href="#changing-template">Changing template</a><br /></li>
40</ul></li>
41<li><a href="#backup">Backup</a><br /></li>
42<li><p><a href="#troubleshooting">Troubleshooting</a></p>
43<ul>
44<li><a href="#i-forgot-my-password-">I forgot my password !</a><br /></li>
45<li><a href="#im-locked-out---login-bruteforce-protection">I'm locked out - Login bruteforce protection</a><br /></li>
46<li><a href="#list-of-all-login-attempts">List of all login attempts</a><br /></li>
47<li><a href="#exporting-from-diigo">Exporting from Diigo</a><br /></li>
48<li><a href="#importing-from-semanticscuttle">Importing from SemanticScuttle</a><br /></li>
49<li><a href="#importing-from-mister-wong">Importing from Mister Wong</a><br /></li>
50<li><a href="#hosting-problems">Hosting problems</a><br /></li>
51<li><a href="#dates-are-not-properly-formatted">Dates are not properly formatted</a><br /></li>
52<li><a href="#problems-on-centos-servers">Problems on CentOS servers</a><br /></li>
53<li><a href="#my-session-expires--i-cant-stay-logged-in">My session expires ! I can't stay logged in</a><br /></li>
54<li><a href="#sessions-do-not-seem-to-work-correctly-on-your-server"><code>Sessions do not seem to work correctly on your server</code></a><br /></li>
55<li><a href="#pubsubhubbub-support">pubsubhubbub support</a><br /></li>
56</ul></li>
57<li><p><a href="#notes">Notes</a></p>
58<ul>
59<li><a href="#various-hacks">Various hacks</a><br /></li>
60<li><a href="#changing-timestamp-for-a-link">Changing timestamp for a link</a><br /></li>
61</ul></li>
62<li><a href="#related-software">Related software</a><br /></li>
63<li><a href="#other-links">Other links</a><br /></li>
64<li><p><a href="#faq">FAQ</a></p>
65<ul>
66<li><a href="#why-did-you-create-shaarli-">Why did you create Shaarli ?</a><br /></li>
67<li><a href="#why-use-shaarli-and-not-deliciousdiigo-">Why use Shaarli and not Delicious/Diigo ?</a><br /></li>
68<li><a href="#what-does-shaarli-mean-">What does Shaarli mean ?</a><br /></li>
69</ul></li>
70<li><p><a href="#technical-details">Technical details</a></p>
71<ul>
72<li><a href="#directory-structure">Directory structure</a><br /></li>
73<li><a href="#why-not-use-a-real-database--files-are-slow-">Why not use a real database ? Files are slow !</a><br /></li>
74</ul></li>
75<li><p><a href="#wiki---todo">Wiki - TODO</a></p></li>
76</ul>
77<!-- /MarkdownTOC -->
78
79
80
81
82<hr />
83<h1 id="basic-usage">Basic Usage</h1>
84<h3 id="add-the-sharing-button-bookmarklet-to-your-browser">Add the sharing button (<em>bookmarklet</em>) to your browser</h3>
85<ul>
86<li>Open your Shaarli and <code>Login</code><br /></li>
87<li>Click the <code>Tools</code> button in the top bar<br /></li>
88<li>Drag the <strong><code>✚Shaare link</code> button</strong>, and drop it to your browser's bookmarks bar.</li>
89</ul>
90<p><em>This bookmarklet button in compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar.</em></p>
91<p><img src="images/bookmarklet.png" /></p>
92<h3 id="share-links-using-the-bookmarklet">Share links using the <em>bookmarklet</em></h3>
93<ul>
94<li>When you are visiting a webpage you would like to share with Shaarli, click the <em>bookmarklet</em> you just added.<br /></li>
95<li>A window opens.<br /></li>
96<li>You can freely edit title, description, tags... to find it later using the text search or tag filtering.<br /></li>
97<li>You will be able to edit this link later using the <img src="https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png" /> edit button.<br /></li>
98<li>You can also check the “Private” box so that the link is saved but only visible to you.<br /></li>
99<li>Click <code>Save</code>.<strong>Voila! Your link is now shared.</strong></li>
100</ul>
101<h1 id="other-usage-examples">Other usage examples</h1>
102<p>Shaarli can be used:</p>
103<ul>
104<li>to share, comment and save interesting links and news<br /></li>
105<li>to bookmark useful/frequent personal links (as private links) and share them between computers<br /></li>
106<li>as a minimal blog/microblog/writing platform (no character limit)<br /></li>
107<li>as a read-it-later list (for example items tagged <code>readlater</code>)<br /></li>
108<li>to draft and save articles/ideas<br /></li>
109<li>to keep code snippets<br /></li>
110<li>to keep notes and documentation<br /></li>
111<li>as a shared clipboard between machines<br /></li>
112<li>as a todo list<br /></li>
113<li>to store playlists (e.g. with the <code>music</code> or <code>video</code> tags)<br /></li>
114<li>to keep extracts/comments from webpages that may disappear<br /></li>
115<li>to keep track of ongoing discussions (for example items tagged <code>discussion</code>)<br /></li>
116<li><a href="http://shaarli.chassegnouf.net/?9Efeiw">to feed RSS aggregators</a> (planets) with specific tags<br /></li>
117<li>to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)</li>
118</ul>
119<h3 id="using-shaarli-as-a-blog-notepad-pastebin...">Using Shaarli as a blog, notepad, pastebin...</h3>
120<ul>
121<li>Go to your Shaarli setup and log in<br /></li>
122<li>Click the <code>Add Link</code> button<br /></li>
123<li>To share text only, do not enter any URL in the corresponding input field and click <code>Add Link</code><br /></li>
124<li>Pick a title and enter your article, or note, in the description field; add a few tags; optionally check <code>Private</code> then click <code>Save</code><br /></li>
125<li>Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.</li>
126</ul>
127<h3 id="rss-feeds-or-picture-wall-for-a-specific-searchtag">RSS Feeds or Picture Wall for a specific search/tag</h3>
128<p>It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to <strong>only display results of a specific search, or for a specific tag</strong>. For example, if you want to subscribe only to links tagged <code>photography</code>:</p>
129<ul>
130<li>Go to the desired Shaarli instance.<br /></li>
131<li>Search for the <code>photography</code> tag in the <em>Filter by tag</em> box. Links tagged <code>photography</code> are displayed.<br /></li>
132<li>Click on the <code>RSS Feed</code> button.<br /></li>
133<li>You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.<br /></li>
134<li>The same method <strong>also works for a full-text search</strong> (<em>Search</em> box) <strong>and for the Picture Wall</strong> (want to only see pictures about <code>nature</code>?)<br /></li>
135<li>You can also build the URL manually: <code>https://my.shaarli.domain/?do=rss&amp;searchtags=nature</code>, <code>https://my.shaarli.domain/links/?do=picwall&amp;searchterm=poney</code></li>
136</ul>
137<p><img src="rss-filter-1.png" /> <img src="rss-filter-2.png" /></p>
138<h1 id="configuration">Configuration</h1>
139<h3 id="main-dataoptions.php-file">Main data/options.php file</h3>
140<p>To change the configuration, create the file <code>data/options.php</code>, example:</p>
141<pre><code> &lt;?php
142 $GLOBALS[&#39;config&#39;][&#39;LINKS_PER_PAGE&#39;] = 30;
143 $GLOBALS[&#39;config&#39;][&#39;HIDE_TIMESTAMPS&#39;] = true;
144 $GLOBALS[&#39;config&#39;][&#39;ENABLE_THUMBNAILS&#39;] = false;
145 ?&gt;</code></pre>
146<p><strong>Do not edit config options in index.php! Your changes would be lost when you upgrade.</strong> The following parameters are available (parameters (default value)):</p>
147<ul>
148<li><code>DATADIR ('data')</code> : This is the name of the subdirectory where Shaarli stores is data file. You can change it for better security.<br /></li>
149<li><code>CONFIG_FILE ($GLOBALS['config']['DATADIR'].'/config.php')</code> : Name of file which is used to store login/password.<br /></li>
150<li><code>DATASTORE ($GLOBALS['config']['DATADIR'].'/datastore.php')</code> : Name of file which contains the link database.<br /></li>
151<li><code>LINKS_PER_PAGE (20)</code> : Default number of links per page displayed.<br /></li>
152<li><code>IPBANS_FILENAME ($GLOBALS['config']['DATADIR'].'/ipbans.php')</code> : Name of file which records login attempts and IP bans.<br /></li>
153<li><code>BAN_AFTER (4)</code> : An IP address will be banned after this many failed login attempts.<br /></li>
154<li><code>BAN_DURATION (1800)</code> : Duration of ban (in seconds). (1800 seconds = 30 minutes)<br /></li>
155<li><code>OPEN_SHAARLI (false)</code> : If you set this option to true, anyone will be able to add/modify/delete/import/exports links without having to login.<br /></li>
156<li><code>HIDE_TIMESTAMPS (false)</code> : If you set this option to true, the date/time of each link will not be displayed (including in RSS Feed).<br /></li>
157<li><code>ENABLE_THUMBNAILS (true)</code> : Enable/disable thumbnails.<br /></li>
158<li><code>RAINTPL_TMP (tmp/)</code> : Raintpl cache directory (keep the trailing slash!)<br /></li>
159<li>`RAINTPL_TPL (tpl/) : Raintpl template directory (keep the trailing slash!). Edit this option if you want to change the rendering template (page structure) used by Shaarli. See <a href="#changing-template">Changing template</a><br /></li>
160<li><code>CACHEDIR ('cache')</code> : Directory where the thumbnails are stored.<br /></li>
161<li><code>ENABLE_LOCALCACHE (true)</code> : If you have a limited quota on your webspace, you can set this option to false: Shaarli will not generate thumbnails which need to be cached locally (vimeo, flickr, etc.). Thumbnails will still be visible for the services which do not use the local cache (youtube.com, imgur.com, dailymotion.com, imageshack.us)<br /></li>
162<li><code>UPDATECHECK_FILENAME ($GLOBALS['config']['DATADIR'].'/lastupdatecheck.txt')</code> : name of the file used to store available shaarli version.<br /></li>
163<li><code>UPDATECHECK_INTERVAL (86400)</code> : Delay between new Shaarli version check. 86400 seconds = 24 hours. Note that if you do not login for a week, Shaarli will not check for new version for a week.<br /></li>
164<li><code>ENABLE_UPDATECHECK</code>: Determines whether Shaarli check for new releases at <a href="https://github.com/shaarli/Shaarli">https://github.com/shaarli/Shaarli</a><br /></li>
165<li><code>SHOW_ATOM (false)</code> : Show an <code>ATOM Feed</code> button next to the <code>Subscribe</code> (RSS) button. ATOM feeds are available at the address <code>?do=atom</code> regardless of this option.<br /></li>
166<li><code>ARCHIVE_ORG (false)</code> : For each link, display a link to an archived version on archive.org<br /></li>
167<li><code>ENABLE_RSS_PERMALINKS (true)</code>: choose whether the RSS item title link points directly to the link, or to the entry on Shaarli (permalink). <code>true</code> is the original Shaarli bahevior (point directly to the link)</li>
168</ul>
169<h3 id="changing-theme">Changing theme</h3>
170<ul>
171<li>Shaarli's apparence can be modified by editing CSS rules in <code>inc/user.css</code>. This file allows to override rules defined in the main <code>inc/shaarli.css</code> (only add changed rules), or define a whole new theme.<br /></li>
172<li>Do not edit <code>inc/shaarli.css</code>! Your changes would be overriden when updating Shaarli.<br /></li>
173<li>Some themes are available at <a href="https://github.com/shaarli/shaarli-themes">https://github.com/shaarli/shaarli-themes</a>.</li>
174</ul>
175<p>See also:</p>
176<ul>
177<li><a href="https://github.com/shaarli/Shaarli/wiki/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file">Download CSS styles for shaarlis listed in an opml file</a></li>
178</ul>
179<h3 id="changing-template">Changing template</h3>
180<p>| 💥 | This feature is currently being worked on and will be improved in the next releases. Experimental. |<br />|---------|---------|</p>
181<ul>
182<li>Find the template you'd like to install. See the list of available templates (TODO). Find it's git clone URL or download the zip archive for the template.<br /></li>
183<li>In your Shaarli <code>tpl/</code> directory, run <code>git clone https://url/of/my-template/</code> or unpack the zip archive. There should now be a <code>my-template/</code> directory under the <code>tpl/</code> dir, containing directly all the template files.<br /></li>
184<li>Edit <code>data/options.php</code> to have Shaarli use this template. Eg.</li>
185</ul>
186<p><code>$GLOBALS['config']['RAINTPL_TPL'] = 'tpl/my-template/' ;</code></p>
187<p>You can find a list of compatible templates in <a href="#Related-software">Related Software</a></p>
188<h1 id="backup">Backup</h1>
189<p>You have two ways of backing up your database:</p>
190<ul>
191<li><strong>Backup the file <code>data/datastore.php</code></strong> (by FTP or SSH). Restore by putting the file back in place.<br /></li>
192<li>Example command: <code>rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php</code><br /></li>
193<li><strong>Export your links as HTML</strong> (Menu <code>Tools</code> &gt; <code>Export</code>). Restore by using the <code>Import</code> feature.<br /></li>
194<li>This can be done using the <a href="https://github.com/nodiscc/shaarchiver">shaarchiver</a> tool. Example command: <code>./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all</code></li>
195</ul>
196<h1 id="troubleshooting">Troubleshooting</h1>
197<h3 id="i-forgot-my-password">I forgot my password !</h3>
198<p>Delete the file data/config.php and display the page again. You will be asked for a new login/password.</p>
199<h3 id="im-locked-out---login-bruteforce-protection">I'm locked out - Login bruteforce protection</h3>
200<p>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.</p>
201<p>To remove the current IP bans, delete the file <code>data/ipbans.php</code></p>
202<h3 id="list-of-all-login-attempts">List of all login attempts</h3>
203<p>The file <code>data/log.txt</code> shows all logins (successful or failed) and bans/lifted bans.<br />Search for <code>failed</code> in this file to look for unauthorized login attempts.</p>
204<h3 id="exporting-from-diigo">Exporting from Diigo</h3>
205<p>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.)</p>
206<h3 id="importing-from-semanticscuttle">Importing from SemanticScuttle</h3>
207<p>To correctly import the tags from a <a href="http://semanticscuttle.sourceforge.net/">SemanticScuttle</a> HTML export, edit the HTML file before importing and replace all occurences of <code>tags=</code> (lowercase) to <code>TAGS=</code> (uppercase).</p>
208<h3 id="importing-from-mister-wong">Importing from Mister Wong</h3>
209<p>See <a href="https://github.com/sebsauvage/Shaarli/issues/146">this issue</a> for import tweaks.</p>
210<h3 id="hosting-problems">Hosting problems</h3>
211<ul>
212<li>On <strong>free.fr</strong> : Please note that free uses php 5.1 and thus you will not have autocomplete in tag editing. Don't forget to create a <code>sessions</code> directory at the root of your webspace. Change the file extension to <code>.php5</code> or create a <code>.htaccess</code> file in the directory where Shaarli is located containing:</li>
213</ul>
214<pre><code>php 1
215SetEnv PHP_VER 5</code></pre>
216<ul>
217<li>If you have an error such as: <code>Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx</code>, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to <code>.php5</code><br /></li>
218<li>On <strong>1and1</strong> : 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).<br /></li>
219<li>If you have the error <code>Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx</code>, 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:</li>
220</ul>
221<pre><code>//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
222// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) &lt;head&gt; in html
223//if (strpos($status,&#39;200 OK&#39;)) $title=html_extract_title($data);</code></pre>
224<ul>
225<li>On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.<br /></li>
226<li>On <strong>lost-oasis</strong>, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : <code>&lt;? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?&gt;</code>. To fix this, remove this message from <code>php-include/prepend.php</code></li>
227</ul>
228<h3 id="dates-are-not-properly-formatted">Dates are not properly formatted</h3>
229<p>Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( )</p>
230<h3 id="problems-on-centos-servers">Problems on CentOS servers</h3>
231<p>On <strong>CentOS</strong>/RedHat derivatives, you may need to install the <code>php-mbstring</code> package.</p>
232<h3 id="my-session-expires-i-cant-stay-logged-in">My session expires ! I can't stay logged in</h3>
233<p>This can be caused by several things:</p>
234<ul>
235<li>Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a <code>session</code> directory on the root of your website.) You may need to create the session directory of set it up.<br /></li>
236<li>Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the <code>sessions</code> subdirectory and add <code>ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');</code>. Make sure this directory is not browsable !)<br /></li>
237<li>If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).<br /></li>
238<li>Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.<br /></li>
239<li>You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.<br /></li>
240<li>If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.</li>
241</ul>
242<h3 id="sessions-do-not-seem-to-work-correctly-on-your-server"><code>Sessions do not seem to work correctly on your server</code></h3>
243<p>Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have <strong>no dots</strong> in the hostname (e.g. <code>localhost</code> or <code>http://my-webserver/shaarli/</code>), some browsers will not store cookies at all (this respects the <a href="http://curl.haxx.se/rfc/cookie_spec.html">HTTP cookie specification</a>).</p>
244<h3 id="pubsubhubbub-support">pubsubhubbub support</h3>
245<p>Download <a href="https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php">publisher.php</a> at the root of your Shaarli installation and set <code>$GLOBALS['config']['PUBSUBHUB_URL']</code> in your <code>config.php</code></p>
246<h1 id="notes">Notes</h1>
247<h3 id="various-hacks">Various hacks</h3>
248<ul>
249<li><a href="Example-patch---add-new-via-field-for-links">Example patch: add a new &quot;via&quot; field for links</a><br /></li>
250<li><a href="Copy-a-Shaarli-installation-over-SSH-SCP,-serve-it-locally-with-php-cli">Copy a Shaarli installation over SSH SCP, serve it locally with php cli</a><br /></li>
251<li>To display the array representing the data saved in datastore.php, use the following snippet (TODO where is it gone?)</li>
252</ul>
253<h3 id="changing-timestamp-for-a-link">Changing timestamp for a link</h3>
254<ul>
255<li>Look for <code>&lt;input type=&quot;hidden&quot; name=&quot;lf_linkdate&quot; value=&quot;{$link.linkdate}&quot;&gt;</code> in <code>tpl/editlink.tpl</code> (line 14)<br /></li>
256<li>Remove <code>type=&quot;hidden&quot;</code> from this line<br /></li>
257<li>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 <code>YYYMMDD_HHMMS</code>.</li>
258</ul>
259<pre><code>$data = &quot;tZNdb9MwFIb... &lt;Commented content inside datastore.php&gt;&quot;;
260$out = unserialize(gzinflate(base64_decode($data)));
261echo &quot;&lt;pre&gt;&quot;; // Pretty printing is love, pretty printing is life
262print_r($out);
263echo &quot;&lt;/pre&gt;&quot;;
264exit;</code></pre>
265<p>This will output the internal representation of the datastore, &quot;unobfuscated&quot; (if this can really be considered obfuscation)</p>
266<h1 id="related-software">Related software</h1>
267<p>Unofficial but relatedd work on Shaarli. If you maintain one of these, please get in touch with us to help us find a way to adapt your work to our fork. <strong>TODO</strong> contact repos owners to see if they'd like to standardize their work for the community fork.</p>
268<ul>
269<li><a href="https://github.com/nodiscc/shaarchiver">shaarchiver</a> - Archive your Shaarli bookmarks and their content<br /></li>
270<li><a href="http://sebsauvage.net/links/?ZAyDzg">Shaarli for Android</a> - Android application that adds Shaarli as a sharing provider<br /></li>
271<li><a href="https://play.google.com/store/apps/details?id=com.dimtion.shaarlier">Shaarlier for Android</a> - Android application to simply add links directly into your Shaarli<br /></li>
272<li><a href="https://github.com/mknexen/shaarli-river">shaarli-river</a> - an aggregator for shaarlis with many features<br /></li>
273<li><a href="https://github.com/DMeloni/shaarlo">Shaarlo</a> - an aggregator for shaarlis with many features (<a href="http://shaarli.fr/">Demo</a>)<br /></li>
274<li><a href="https://github.com/kalvn/shaarli-blocks">kalvn/shaarli-blocks</a> - A template/theme for Shaarli<br /></li>
275<li><a href="https://github.com/kalvn/Shaarli-Material">kalvn/Shaarli-Material</a> -<br />A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.<br /></li>
276<li><a href="https://github.com/Vinm/Blue-theme-for-Shaarli">Vinm/Blue-theme-for Shaarli</a> - A template/theme for Shaarli (<a href="https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2">unmaintained</a>, compatibility unknown)<br /></li>
277<li><a href="https://github.com/vivienhaese/shaarlitheme">vivienhaese/shaarlitheme</a> - A Shaarli fork meant to be run in an openshift instance<br /></li>
278<li><a href="https://github.com/jcsaaddupuy/tt-rss-shaarli">tt-rss-shaarli</a> - <a href="http://tt-rss.org/">TinyTiny RSS</a> plugin that adds support for sharing articles with Shaarli<br /></li>
279<li><a href="https://github.com/dhoko/ShaarliTemplate">dhoko/ShaarliTemplate</a> - A template/theme for Shaarli<br /></li>
280<li><a href="https://github.com/mknexen/shaarli-api">mknexen/shaarli-api</a> - a REST API for Shaarli<br /></li>
281<li><a href="https://github.com/alexisju/albinomouse-template">Albinomouse</a> - A full template for Shaarli<br /></li>
282<li><a href="https://github.com/BoboTiG/shaarlimages">Shaarlimages</a> - An image-oriented aggregator for Shaarlis<br /></li>
283<li><a href="https://github.com/AkibaTech/Shaarli---SuperHero-Theme">Shaarli Superhero Theme</a> - A template/theme for Shaarli<br /></li>
284<li><a href="https://github.com/misterair/limonade">Limonade</a> - A fork of Shaarli with a new template<br /></li>
285<li><a href="https://github.com/ahmet2mir/octopress-shaarli">octopress-shaarli</a> - octoprress plugin to retrieve SHaarli links on the sidebara<br /></li>
286<li><a href="https://github.com/bookieio/bookie">Bookie</a> - Another self-hostable, Free bookmark sharing software, written in Python<br /></li>
287<li><a href="https://github.com/plainmade/unmark">Unmark</a> - An open source to do app for bookmarks (<a href="https://unmark.it/">Homepage</a>)</li>
288</ul>
289<h1 id="other-links">Other links</h1>
290<ul>
291<li><a href="http://sebsauvage.net/links/">Liens en vrac de sebsauvage</a> - the original Shaarli<br /></li>
292<li><a href="http://porneia.free.fr/pub/links/ou-est-shaarli.html">A large list of Shaarlis</a><br /></li>
293<li><a href="https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json">A list of working Shaarli aggregators</a><br /></li>
294<li><a href="https://github.com/Oros42/shaarlis_list">A list of some known Shaarlis</a><br /></li>
295<li><a href="http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-">Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net</a> (fr) <em>16/09/2011 - the original post about Shaarli</em><br /></li>
296<li><a href="http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas">Original ideas/fixme/TODO page</a><br /></li>
297<li><a href="http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion">Original discussion page</a> (fr)<br /></li>
298<li><a href="http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history">Original revisions history</a><br /></li>
299<li><a href="https://www.shaarli.fr/my.php">Shaarli.fr/my</a> - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of <a href="https://github.com/DMeloni">DMeloni</a><br /></li>
300<li><a href="http://shaarferme.etudiant-libre.fr.nf/index.php">Shaarli Communauty</a> - Another unofficial Shaarli hoster (unsupported, old fork), hoster unknown</li>
301</ul>
302<h1 id="faq">FAQ</h1>
303<h3 id="why-did-you-create-shaarli">Why did you create Shaarli ?</h3>
304<p>I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… <strong>their Firefox addon sends to Diigo every single URL you visit</strong> (Don't believe me ? Use <a href="https://addons.mozilla.org/en-US/firefox/addon/tamper-data/">Tamper Data</a> and open any page).</p>
305<p>Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.</p>
306<h3 id="why-use-shaarli-and-not-deliciousdiigo">Why use Shaarli and not Delicious/Diigo ?</h3>
307<p>With Shaarli:</p>
308<ul>
309<li>The data is yours: It's hosted on your server.<br /></li>
310<li>Never fear of having your data locked-in.<br /></li>
311<li>Never fear to have your data sold to third party.<br /></li>
312<li>Your private links are not hosted on a third party server.<br /></li>
313<li>You are not tracked by browser addons (like Diigo does)<br /></li>
314<li>You can change the look and feel of the pages if you want.<br /></li>
315<li>You can change the behaviour of the program.<br /></li>
316<li>It's magnitude faster than most bookmarking services.</li>
317</ul>
318<h3 id="what-does-shaarli-mean">What does Shaarli mean ?</h3>
319<p>Shaarli is for shaaring your links.</p>
320<h1 id="technical-details">Technical details</h1>
321<ul>
322<li>Application is protected against XSRF (Cross-site requests forgery): Forms which act on data (save,delete…) contain a token generated by the server. Any posted form which does not contain a valid token is rejected. Any token can only be used once. Token are attached to the session and cannot be reused in another session.<br /></li>
323<li>Sessions automatically expires after 60 minutes. Sessions are protected against highjacking: The sessionID cannot be used from a different IP address.<br /></li>
324<li>An .htaccess file protects the data file.<br /></li>
325<li><p>Link database is an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a .php file. Thus even if the server does not support htaccess files, the data file will still not be readable by URL. The database looks like this:</p>
326<pre><code>&lt;?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
327...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?&gt;</code></pre></li>
328<li>The password is salted, hashed and stored in the data subdirectory, in a php file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.<br /></li>
329<li>Shaarli relies on <code>HTTP_REFERER</code> for some functions (like redirects and clicking on tags). If you have disabled or masqueraded <code>HTTP_REFERER</code> in your browser, some features of Shaarli may not work<br /></li>
330<li><code>magic_quotes</code> is a horrible option of php which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with magic_quotes on, so you should not be bothered even on crappy hosts.<br /></li>
331<li><p>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 @.</p></li>
332</ul>
333<h3 id="directory-structure">Directory structure</h3>
334<p>Here is the directory structure of Shaarli and the purpose of the different files:</p>
335<pre><code> index.php : Main program.
336 COPYING : Shaarli license.
337 inc/ : Includes (libraries, CSS…)
338 shaarli.css : Shaarli stylesheet.
339 jquery.min.js : jQuery javascript library.
340 jquery-ui.min.js : jQuery-UI javascript library.
341 jquery-MIT-LICENSE.txt: jQuery license.
342 jquery.lazyload.min.js: LazyLoad javascript library.
343 rain.tpl.class.php : RainTPL templating library.
344 tpl/ : RainTPL templates for Shaarli. They are used to build the pages.
345 images/ : Images and icons used in Shaarli.
346 data/ : Directory where data is stored (bookmark database, configuration, logs, banlist…)
347 config.php : Shaarli configuration (login, password, timezone, title…)
348 datastore.php : Your link database (compressed).
349 ipban.php : IP address ban system data.
350 lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
351 log.txt : login/IPban log.
352 cache/ : Directory containing the thumbnails cache. This directory is automatically created. You can erase it anytime you want.
353 tmp/ : Temporary directory for compiled RainTPL templates. This directory is automatically created. You can erase it anytime you want.</code></pre>
354<h3 id="why-not-use-a-real-database-files-are-slow">Why not use a real database ? Files are slow !</h3>
355<p>Does browsing <a href="http://sebsauvage.net/links/">this page</a> feel slow ? Try browsing older pages, too.</p>
356<p>It's not slow at all, is it ? And don't forget the database contains more than 16000 links, and it's on a shared host, with 32000 visitors/day for my website alone. And it's still damn fast. Why ?</p>
357<p>The data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.</p>
358<h1 id="wiki---todo">Wiki - TODO</h1>
359<ul>
360<li>Translate (new page can be called Home.fr, Home.es ...) and linked from Home<br /></li>
361<li>add more screenshots<br /></li>
362<li>add developer documentation (storage architecture, classes and functions, security handling, ...)<br /></li>
363<li>Contact related projects<br /></li>
364<li>Add a Table of Contents to the wiki (can be added to the sidebar)</li>
365</ul>
366<p>...</p>
367</body>
368</html>
diff --git a/doc/Ideas-for-plugins.html b/doc/Ideas-for-plugins.html
new file mode 100644
index 00000000..8ca3572c
--- /dev/null
+++ b/doc/Ideas-for-plugins.html
@@ -0,0 +1,26 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title></title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link rel="stylesheet" href="github-markdown.css">
13</head>
14<body>
15<p>Please list here ideas for potential plugins. Do not include lengthy discussion about why/how the plugin should work, but link instead to an issue where this would have been discussed.<br />By listing these ideas here, we can keep the issues list a bit more clean, and have a centralized place where people wanting to contribute can find potential enhancement ideas.<br />Also have a look at <a href="https://github.com/shaarli/Shaarli/issues/14">https://github.com/shaarli/Shaarli/issues/14</a> for other suggestions.</p>
16<ul>
17<li><a href="https://github.com/shaarli/Shaarli/issues/101">Mozilla Social API integration</a><br /></li>
18<li><a href="https://github.com/shaarli/Shaarli/issues/58">File sharing/Upload service integration</a><br /></li>
19<li><a href="https://github.com/sebsauvage/Shaarli/pull/70">Publish to social media services (twitter, facebook, ...)</a><br /></li>
20<li><a href="https://github.com/sebsauvage/Shaarli/issues/170">Comment system</a><br /></li>
21<li><a href="https://github.com/sebsauvage/Shaarli/pull/144">Syntax highlighting support</a><br /></li>
22<li><a href="https://github.com/sebsauvage/Shaarli/issues/81">Piwik tracking code integration</a><br /></li>
23<li><a href="https://github.com/sebsauvage/Shaarli/issues/75">Pingback support</a></li>
24</ul>
25</body>
26</html>
diff --git a/doc/_Sidebar.html b/doc/_Sidebar.html
new file mode 100644
index 00000000..b9e2ed39
--- /dev/null
+++ b/doc/_Sidebar.html
@@ -0,0 +1,70 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title></title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <link rel="stylesheet" href="github-markdown.css">
13</head>
14<body>
15<ul>
16<li><p><a href="#basic-usage">Basic Usage</a></p>
17<ul>
18<li><a href="#add-the-sharing-button-_bookmarklet_-to-your-browser">Add the sharing button (<em>bookmarklet</em>) to your browser</a><br /></li>
19<li><a href="#share-links-using-the-_bookmarklet_">Share links using the <em>bookmarklet</em></a><br /></li>
20</ul></li>
21<li><p><a href="#other-usage-examples">Other usage examples</a></p>
22<ul>
23<li><a href="#using-shaarli-as-a-blog-notepad-pastebin">Using Shaarli as a blog, notepad, pastebin...</a><br /></li>
24<li><a href="#rss-feeds-or-picture-wall-for-a-specific-searchtag">RSS Feeds or Picture Wall for a specific search/tag</a><br /></li>
25</ul></li>
26<li><p><a href="#configuration">Configuration</a></p>
27<ul>
28<li><a href="#main-dataoptionsphp-file">Main data/options.php file</a><br /></li>
29<li><a href="#changing-theme">Changing theme</a><br /></li>
30</ul></li>
31<li><a href="#backup">Backup</a><br /></li>
32<li><p><a href="#login-bruteforce-protection">Login bruteforce protection</a></p>
33<ul>
34<li><a href="#list-of-all-login-attempts">List of all login attempts</a><br /></li>
35</ul></li>
36<li><p><a href="#troubleshooting">Troubleshooting</a></p>
37<ul>
38<li><a href="#i-forgot-my-password-">I forgot my password !</a><br /></li>
39<li><a href="#exporting-from-diigo">Exporting from Diigo</a><br /></li>
40<li><a href="#importing-from-semanticscuttle">Importing from SemanticScuttle</a><br /></li>
41<li><a href="#importing-from-mister-wong">Importing from Mister Wong</a><br /></li>
42<li><a href="#hosting-problems">Hosting problems</a><br /></li>
43<li><a href="#dates-are-not-properly-formatted">Dates are not properly formatted</a><br /></li>
44<li><a href="#problems-on-centos-servers">Problems on CentOS servers</a><br /></li>
45<li><a href="#my-session-expires--i-cant-stay-logged-in">My session expires ! I can't stay logged in</a><br /></li>
46<li><a href="#sessions-do-not-seem-to-work-correctly-on-your-server"><code>Sessions do not seem to work correctly on your server</code></a><br /></li>
47<li><a href="#pubsubhubbub-support">pubsubhubbub support</a><br /></li>
48</ul></li>
49<li><p><a href="#notes">Notes</a></p>
50<ul>
51<li><a href="#various-hacks">Various hacks</a><br /></li>
52<li><a href="#changing-timestamp-for-a-link">Changing timestamp for a link</a><br /></li>
53</ul></li>
54<li><a href="#related-software">Related software</a><br /></li>
55<li><a href="#other-links">Other links</a><br /></li>
56<li><p><a href="#faq">FAQ</a></p>
57<ul>
58<li><a href="#why-did-you-create-shaarli-">Why did you create Shaarli ?</a><br /></li>
59<li><a href="#why-use-shaarli-and-not-deliciousdiigo-">Why use Shaarli and not Delicious/Diigo ?</a><br /></li>
60<li><a href="#what-does-shaarli-mean-">What does Shaarli mean ?</a><br /></li>
61</ul></li>
62<li><p><a href="#technical-details">Technical details</a></p>
63<ul>
64<li><a href="#directory-structure">Directory structure</a><br /></li>
65<li><a href="#why-not-use-a-real-database--files-are-slow-">Why not use a real database ? Files are slow !</a><br /></li>
66</ul></li>
67<li><p><a href="#wiki---todo">Wiki - TODO</a></p></li>
68</ul>
69</body>
70</html>