aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Home.md
diff options
context:
space:
mode:
authorVirtualTam <virtualtam@flibidi.net>2015-07-22 05:02:10 +0200
committerVirtualTam <virtualtam@flibidi.net>2015-08-04 16:02:21 +0200
commit992af0b9d77cb4fbac2c37ef8d5896042d67a2a3 (patch)
tree4726baf18e7057eac3f9b6bdb5991fe6117814fc /doc/Home.md
parent96db105e4c0833324f7168edb5673278de8ccd54 (diff)
downloadShaarli-992af0b9d77cb4fbac2c37ef8d5896042d67a2a3.tar.gz
Shaarli-992af0b9d77cb4fbac2c37ef8d5896042d67a2a3.tar.zst
Shaarli-992af0b9d77cb4fbac2c37ef8d5896042d67a2a3.zip
Doc: sync from Wiki, generate HTML
Closes #291 Fixes #227 Modifications - HTML content: match the new Wiki structure - Makefile - generate a custom HTML sidebar - include the sidebar on all pages - infer and prepend page titles - handle relative links - add title metadata, e.g. Shaarli - <Page Name> Signed-off-by: VirtualTam <virtualtam@flibidi.net>
Diffstat (limited to 'doc/Home.md')
-rw-r--r--doc/Home.md449
1 files changed, 7 insertions, 442 deletions
diff --git a/doc/Home.md b/doc/Home.md
index b5d9c396..a824d983 100644
--- a/doc/Home.md
+++ b/doc/Home.md
@@ -1,449 +1,14 @@
1#Home
1# Shaarli wiki 2# Shaarli wiki
2 3
3Welcome to the [Shaarli](https://github.com/shaarli/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](https://github.com/shaarli/Shaarli/blob/master/README.md). 4Welcome to the [Shaarli](https://github.com/shaarli/Shaarli/) wiki![](.html)
4 5
5If 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). 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). 6Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
6
7_Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the `doc/` directory of your Shaarli installation._
8
9----------------------------------------------------------------------------------
10
11<!-- MarkdownTOC depth=3 -->
12
13- [Basic Usage](#basic-usage)
14 - [Add the sharing button (_bookmarklet_) to your browser](#add-the-sharing-button-_bookmarklet_-to-your-browser)
15 - [Add Shaarli as a sharing service to Firefox](#add-shaarli-as-a-sharing-service-to-firefox)
16 - [Share links using the _bookmarklet_](#share-links-using-the-_bookmarklet_)
17 - [Sharing links using Firefox share](#sharing-links-using-firefox-share)
18- [Other usage examples](#other-usage-examples)
19 - [Using Shaarli as a blog, notepad, pastebin...](#using-shaarli-as-a-blog-notepad-pastebin)
20 - [RSS Feeds or Picture Wall for a specific search/tag](#rss-feeds-or-picture-wall-for-a-specific-searchtag)
21- [Configuration](#configuration)
22 - [Main data/options.php file](#main-dataoptionsphp-file)
23 - [Changing theme](#changing-theme)
24 - [Changing template](#changing-template)
25- [Backup](#backup)
26- [Troubleshooting](#troubleshooting)
27 - [I forgot my password !](#i-forgot-my-password-)
28 - [I'm locked out - Login bruteforce protection](#im-locked-out---login-bruteforce-protection)
29 - [List of all login attempts](#list-of-all-login-attempts)
30 - [Exporting from Diigo](#exporting-from-diigo)
31 - [Importing from SemanticScuttle](#importing-from-semanticscuttle)
32 - [Importing from Mister Wong](#importing-from-mister-wong)
33 - [Hosting problems](#hosting-problems)
34 - [Dates are not properly formatted](#dates-are-not-properly-formatted)
35 - [Problems on CentOS servers](#problems-on-centos-servers)
36 - [My session expires ! I can't stay logged in](#my-session-expires--i-cant-stay-logged-in)
37 - [`Sessions do not seem to work correctly on your server`](#sessions-do-not-seem-to-work-correctly-on-your-server)
38 - [pubsubhubbub support](#pubsubhubbub-support)
39- [Notes](#notes)
40 - [Various hacks](#various-hacks)
41 - [Changing timestamp for a link](#changing-timestamp-for-a-link)
42- [Related software](#related-software)
43 - [Server apps](#server-apps)
44 - [Android apps](#android-apps)
45 - [Themes & templates](#themes--templates)
46 - [Integrate Shaarli with other platforms](#integrate-shaarli-with-other-platforms)
47 - [Alternative to Shaarli](#alternative-to-shaarli)
48- [Other links](#other-links)
49- [FAQ](#faq)
50 - [Why did you create Shaarli ?](#why-did-you-create-shaarli-)
51 - [Why use Shaarli and not Delicious/Diigo ?](#why-use-shaarli-and-not-deliciousdiigo-)
52 - [What does Shaarli mean ?](#what-does-shaarli-mean-)
53- [Technical details](#technical-details)
54 - [Directory structure](#directory-structure)
55 - [Development](#development)
56 - [Why not use a real database ? Files are slow !](#why-not-use-a-real-database--files-are-slow-)
57- [Wiki - TODO](#wiki---todo)
58
59<!-- /MarkdownTOC -->
60
61
62
63------------------------------------------------------------------
64
65# Basic Usage
66
67### Add the sharing button (_bookmarklet_) to your browser
68
69 * Open your Shaarli and `Login`
70 * Click the `Tools` button in the top bar
71 * Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
72
73_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._
74
75![](images/bookmarklet.png)
76
77
78### Add Shaarli as a sharing service to Firefox
79
80 * Open your Shaarli and `Login`
81 * Click the `Tools` button in the top bar
82 * Click the `✚Add to Firefox social` button and accept the activation.
83
84
85### Share links using the _bookmarklet_
86
87 * When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
88 * A window opens.
89 * You can freely edit title, description, tags... to find it later using the text search or tag filtering.
90 * You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.
91 * You can also check the “Private” box so that the link is saved but only visible to you.
92 * Click `Save`.**Voila! Your link is now shared.**
93
94
95### Sharing links using Firefox share
96
97 * Add the sharing service as described above
98 * When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [[images/firefoxshare.png]]
99 * You can edit your link before and after saving, just like the bookmarklet above.
100
101
102# Other usage examples
103Shaarli can be used:
104
105 * to share, comment and save interesting links and news
106 * to bookmark useful/frequent personal links (as private links) and share them between computers
107 * as a minimal blog/microblog/writing platform (no character limit)
108 * as a read-it-later list (for example items tagged `readlater`)
109 * to draft and save articles/ideas
110 * to keep code snippets
111 * to keep notes and documentation
112 * as a shared clipboard between machines
113 * as a todo list
114 * to store playlists (e.g. with the `music` or `video` tags)
115 * to keep extracts/comments from webpages that may disappear
116 * to keep track of ongoing discussions (for example items tagged `discussion`)
117 * [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
118 * to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
119
120### Using Shaarli as a blog, notepad, pastebin...
121
122 * Go to your Shaarli setup and log in
123 * Click the `Add Link` button
124 * To share text only, do not enter any URL in the corresponding input field and click `Add Link`
125 * Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
126 * Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
127
128
129### RSS Feeds or Picture Wall for a specific search/tag
130It 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`:
131 * Go to the desired Shaarli instance.
132 * Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
133 * Click on the `RSS Feed` button.
134 * You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.
135 * The same method **also works for a full-text search** (_Search_ box) **and for the Picture Wall** (want to only see pictures about `nature`?)
136 * You can also build the URL manually: `https://my.shaarli.domain/?do=rss&searchtags=nature`, `https://my.shaarli.domain/links/?do=picwall&searchterm=poney`
137
138![](images/rss-filter-1.png) ![](images/rss-filter-2.png)
139
140# Configuration
141
142### Main data/options.php file
143
144To change the configuration, create the file `data/options.php`, example:
145```
146 <?php
147 $GLOBALS['config']['LINKS_PER_PAGE'] = 30;
148 $GLOBALS['config']['HIDE_TIMESTAMPS'] = true;
149 $GLOBALS['config']['ENABLE_THUMBNAILS'] = false;
150 ?>
151```
152
153**Do not edit config options in index.php! Your changes would be lost when you upgrade.** The following parameters are available (parameters (default value)):
154
155 * `DATADIR ('data')` : This is the name of the subdirectory where Shaarli stores is data file. You can change it for better security.
156 * `CONFIG_FILE ($GLOBALS['config']['DATADIR'].'/config.php')` : Name of file which is used to store login/password.
157 * `DATASTORE ($GLOBALS['config']['DATADIR'].'/datastore.php')` : Name of file which contains the link database.
158 * `LINKS_PER_PAGE (20)` : Default number of links per page displayed.
159 * `IPBANS_FILENAME ($GLOBALS['config']['DATADIR'].'/ipbans.php')` : Name of file which records login attempts and IP bans.
160 * `BAN_AFTER (4)` : An IP address will be banned after this many failed login attempts.
161 * `BAN_DURATION (1800)` : Duration of ban (in seconds). (1800 seconds = 30 minutes)
162 * `OPEN_SHAARLI (false)` : If you set this option to true, anyone will be able to add/modify/delete/import/exports links without having to login.
163 * `HIDE_TIMESTAMPS (false)` : If you set this option to true, the date/time of each link will not be displayed (including in RSS Feed).#related-software
164 * `ENABLE_THUMBNAILS (true)` : Enable/disable thumbnails.
165 * `RAINTPL_TMP (tmp/)` : Raintpl cache directory (keep the trailing slash!)
166 * `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 [Changing template](#changing-template)
167 * `CACHEDIR ('cache')` : Directory where the thumbnails are stored.
168 * `ENABLE_LOCALCACHE (true)` : 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)
169 * `UPDATECHECK_FILENAME ($GLOBALS['config']['DATADIR'].'/lastupdatecheck.txt')` : name of the file used to store available shaarli version.
170 * `UPDATECHECK_INTERVAL (86400)` : 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.
171 * `ENABLE_UPDATECHECK`: Determines whether Shaarli check for new releases at https://github.com/shaarli/Shaarli
172 * `SHOW_ATOM (false)` : Show an `ATOM Feed` button next to the `Subscribe` (RSS) button. ATOM feeds are available at the address `?do=atom` regardless of this option.
173 * `ARCHIVE_ORG (false)` : For each link, display a link to an archived version on archive.org
174 * `ENABLE_RSS_PERMALINKS (true)`: choose whether the RSS item title link points directly to the link, or to the entry on Shaarli (permalink). `true` is the original Shaarli bahevior (point directly to the link)
175 * `HIDE_PUBLIC_LINKS (false)`: setting this to true hides all links, even public ones, for non-logged in users.
176
177
178### Changing theme
179 * Shaarli's apparence can be modified by editing CSS rules in `inc/user.css`. This file allows to override rules defined in the main `inc/shaarli.css` (only add changed rules), or define a whole new theme.
180 * Do not edit `inc/shaarli.css`! Your changes would be overriden when updating Shaarli.
181 * Some themes are available at https://github.com/shaarli/shaarli-themes.
182
183See also:
184 * [Download CSS styles for shaarlis listed in an opml file](https://github.com/shaarli/Shaarli/wiki/Download-CSS-styles-for-shaarlis-listed-in-an-opml-file)
185
186### Changing template
187
188| WARNING | This feature is currently being worked on and will be improved in the next releases. Experimental. |
189|---------|---------|
190
191 * 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.
192 * 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.
193 * Edit `data/options.php` to have Shaarli use this template. Eg.
194
195`$GLOBALS['config']['RAINTPL_TPL'] = 'tpl/my-template/' ;`
196
197You can find a list of compatible templates in [Related Software](#related-software)
198
199# Backup
200
201You have two ways of backing up your database:
202* **Backup the file `data/datastore.php`** (by FTP or SSH). Restore by putting the file back in place.
203 * Example command: `rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php`
204* **Export your links as HTML** (Menu `Tools` > `Export`). Restore by using the `Import` feature.
205 * This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool. Example command: `./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all`
206
207
208# Troubleshooting
209
210### I forgot my password !
211
212Delete the file data/config.php and display the page again. You will be asked for a new login/password.
213
214
215
216### I'm locked out - Login bruteforce protection
217Login 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.
218
219To remove the current IP bans, delete the file `data/ipbans.php`
220
221### List of all login attempts
222
223The file `data/log.txt` shows all logins (successful or failed) and bans/lifted bans.
224Search for `failed` in this file to look for unauthorized login attempts.
225 7
8For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).[](.html)
226 9
227### Exporting from Diigo 10If 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)
228 11
229If 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.) 12If 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)
230 13
231### Importing from SemanticScuttle 14_Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the `doc/` directory of your Shaarli installation._
232
233To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).
234
235### Importing from Mister Wong
236See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.
237
238
239### Hosting problems
240 * On **free.fr** : Please note that free uses php 5.1 and thus you will not have autocomplete in tag editing. Don't forget to create a `sessions` directory at the root of your webspace. Change the file extension to `.php5` or create a `.htaccess` file in the directory where Shaarli is located containing:
241
242```
243php 1
244SetEnv PHP_VER 5
245```
246
247 * 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`
248 * 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).
249 * 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:
250
251```
252//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
253// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
254//if (strpos($status,'200 OK')) $title=html_extract_title($data);
255```
256
257 * On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
258 * 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`
259
260### Dates are not properly formatted
261Shaarli 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 :-( )
262
263### Problems on CentOS servers
264On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
265
266
267### My session expires ! I can't stay logged in
268This can be caused by several things:
269
270* Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
271* 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 `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
272* 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).
273* Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
274* You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
275* If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
276
277### `Sessions do not seem to work correctly on your server`
278Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)).
279
280
281### pubsubhubbub support
282
283Download [publisher.php](https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php) at the root of your Shaarli installation and set `$GLOBALS['config']['PUBSUBHUB_URL']` in your `config.php`
284
285# Notes
286### Various hacks
287
288 * [Example patch: add a new "via" field for links](Example-patch---add-new-via-field-for-links)
289 * [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)
290 * To display the array representing the data saved in datastore.php, use the following snippet
291```
292$data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
293$out = unserialize(gzinflate(base64_decode($data)));
294echo "<pre>"; // Pretty printing is love, pretty printing is life
295print_r($out);
296echo "</pre>";
297exit;
298```
299This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation)
300
301### Changing timestamp for a link
302 * Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
303 * Remove `type="hidden"` from this line
304 * 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`.
305
306
307# Related software
308Unofficial 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. **TODO** contact repos owners to see if they'd like to standardize their work for the community fork.
309### Server apps
310 * [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
311 * [shaarli-river](https://github.com/mknexen/shaarli-river) - An aggregator for shaarlis with many features
312 * [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: [shaarli.fr](http://shaarli.fr/))
313 * [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
314 * [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
315
316### Android apps
317 * [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
318 * [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
319
320### Themes & templates
321 * [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
322 * [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
323 * [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
324 * [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
325 * [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.
326 * [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
327 * [Vinm/Blue-theme-for Shaarli](https://github.com/Vinm/Blue-theme-for-Shaarli) - A template/theme for Shaarli ([unmaintained](https://github.com/Vinm/Blue-theme-for-Shaarli/issues/2), compatibility unknown)
328 * [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
329
330### Integrate Shaarli with other platforms
331 * [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [TinyTiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
332 * [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - octoprress plugin to retrieve SHaarli links on the sidebara
333
334### Alternative to Shaarli
335 * [Bookie](https://github.com/bookieio/bookie) - Another self-hostable, Free bookmark sharing software, written in Python
336 * [Unmark](https://github.com/plainmade/unmark) - An open source to do app for bookmarks ([Homepage](https://unmark.it/))
337
338
339
340# Other links
341 * [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
342 * [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
343 * [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
344 * [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
345 * [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
346 * [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
347 * [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
348 * [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
349 * [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
350 * [Shaarli Communauty](http://shaarferme.etudiant-libre.fr.nf/index.php) - Another unofficial Shaarli hoster (unsupported, old fork), hoster unknown
351
352
353
354
355# FAQ
356
357### Why did you create Shaarli ?
358
359I 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… **their Firefox addon sends to Diigo every single URL you visit** (Don't believe me ? Use [Tamper Data](https://addons.mozilla.org/en-US/firefox/addon/tamper-data/) and open any page).
360
361Enough 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.
362
363### Why use Shaarli and not Delicious/Diigo ?
364
365With Shaarli:
366
367* The data is yours: It's hosted on your server.
368* Never fear of having your data locked-in.
369* Never fear to have your data sold to third party.
370* Your private links are not hosted on a third party server.
371* You are not tracked by browser addons (like Diigo does)
372* You can change the look and feel of the pages if you want.
373* You can change the behaviour of the program.
374* It's magnitude faster than most bookmarking services.
375
376### What does Shaarli mean ?
377
378Shaarli is for shaaring your links.
379
380
381
382# Technical details
383 * 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.
384 * Sessions automatically expires after 60 minutes. Sessions are protected against highjacking: The sessionID cannot be used from a different IP address.
385 * An .htaccess file protects the data file.
386 * 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:
387```
388<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
389...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
390```
391
392* 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.
393* Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
394* `magic_quotes` 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.
395* 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 @.
396
397### Directory structure
398
399Here is the directory structure of Shaarli and the purpose of the different files:
400
401```
402 index.php : Main program.
403 application/ : Shaarli classes
404 ├── LinkDB.php
405 └── Utils.php
406 tests/ : Shaarli unitary & functional tests
407 ├── LinkDBTest.php
408 ├── utils # utilities to ease testing
409 │ └── ReferenceLinkDB.php
410 └── UtilsTest.php
411 COPYING : Shaarli license.
412 inc/ : Includes (libraries, CSS…)
413 ├── awesomplete.*: tags autocompletion library
414 ├── blazy.*: picture wall lazy image loading library
415 ├── shaarli.css, reset.css : Shaarli stylesheet.
416 ├── qr.* : qr code generation library
417 └──rain.tpl.class.php : RainTPL templating library.
418 tpl/ : RainTPL templates for Shaarli. They are used to build the pages.
419 images/ : Images and icons used in Shaarli.
420 data/ : Directory where data is stored (bookmark database, configuration, logs, banlist…)
421 ├── config.php : Shaarli configuration (login, password, timezone, title…)
422 ├── datastore.php : Your link database (compressed).
423 ├── ipban.php : IP address ban system data.
424 ├── lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
425 └──log.txt : login/IPban log.
426 cache/ : Directory containing the thumbnails cache. This directory is automatically created. You can erase it anytime you want.
427 tmp/ : Temporary directory for compiled RainTPL templates. This directory is automatically created. You can erase it anytime you want.
428```
429
430### Development
431
432 * [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
433 * [Running unit tests](Running-unit-tests)
434 * Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
435 * [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
436 * [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
437
438### Why not use a real database ? Files are slow !
439
440Does browsing [this page](http://sebsauvage.net/links/) feel slow ? Try browsing older pages, too.
441
442It'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 ?
443
444The 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.
445
446# Wiki - TODO
447 * translate (new page can be called Home.fr, Home.es ... and linked from Home)
448 * add more screenshots
449 * add developer documentation (storage architecture, classes and functions, security handling, ...) \ No newline at end of file