Shaarli wiki

Welcome to the Shaarli wiki! Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. For general info, read the README.

If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion or read the current issues. If you've found a bug, please create a new issue. If you would like a feature added to Shaarli, check the issues labeled feature, enhancement, and plugin.

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

Basic Usage

Add the sharing button (bookmarklet) to your browser

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.

Add Shaarli as a sharing service to Firefox

Other usage examples

Shaarli can be used:

Using Shaarli as a blog, notepad, pastebin...

RSS Feeds or Picture Wall for a specific search/tag

It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to only display results of a specific search, or for a specific tag. For example, if you want to subscribe only to links tagged photography:


Main data/options.php file

To change the configuration, create the file data/options.php, example:

    $GLOBALS['config']['LINKS_PER_PAGE'] = 30;
    $GLOBALS['config']['HIDE_TIMESTAMPS'] = true;
    $GLOBALS['config']['ENABLE_THUMBNAILS'] = false;  

Do not edit config options in index.php! Your changes would be lost when you upgrade. The following parameters are available (parameters (default value)):

Changing theme

See also:

Changing template

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

$GLOBALS['config']['RAINTPL_TPL'] = 'tpl/my-template/' ;

You can find a list of compatible templates in Related Software


You have two ways of backing up your database:


I forgot my password !

Delete the file data/config.php and display the page again. You will be asked for a new login/password.

I'm locked out - Login bruteforce protection

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

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

List of all login attempts

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

Exporting from Diigo

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

Importing from SemanticScuttle

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

Importing from Mister Wong

See this issue for import tweaks.

Hosting problems

php 1
SetEnv PHP_VER 5
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html 
//if (strpos($status,'200 OK')) $title=html_extract_title($data);

Dates are not properly formatted

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 :-( )

Problems on CentOS servers

On CentOS/RedHat derivatives, you may need to install the php-mbstring package.

My session expires ! I can't stay logged in

This can be caused by several things:

Sessions do not seem to work correctly on your server

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

pubsubhubbub support

Download publisher.php at the root of your Shaarli installation and set $GLOBALS['config']['PUBSUBHUB_URL'] in your config.php


Various hacks

Related software

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. TODO contact repos owners to see if they'd like to standardize their work for the community fork.

Server apps

Android apps

Themes & templates

Integrate Shaarli with other platforms

Alternative to Shaarli

Other links


Why did you create Shaarli ?

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… their Firefox addon sends to Diigo every single URL you visit (Don't believe me ? Use Tamper Data and open any page).

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.

Why use Shaarli and not Delicious/Diigo ?

With Shaarli:

What does Shaarli mean ?

Shaarli is for shaaring your links.

Technical details

Directory structure

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

    index.php : Main program.
    application/ : Shaarli classes
        ├── LinkDB.php
        └── Utils.php
    tests/ : Shaarli unitary & functional tests
        ├── LinkDBTest.php
        ├── utils  # utilities to ease testing
        │   └── ReferenceLinkDB.php
        └── UtilsTest.php
    COPYING : Shaarli license.
    inc/ : Includes (libraries, CSS…)
        ├── awesomplete.*: tags autocompletion library
        ├── blazy.*: picture wall lazy image loading library
        ├── shaarli.css, reset.css : Shaarli stylesheet.
        ├── qr.* : qr code generation library
        └──rain.tpl.class.php : RainTPL templating library.
    tpl/ : RainTPL templates for Shaarli. They are used to build the pages.
    images/ : Images and icons used in Shaarli.
    data/ : Directory where data is stored (bookmark database, configuration, logs, banlist…)
        ├── config.php : Shaarli configuration (login, password, timezone, title…)
        ├── datastore.php : Your link database (compressed).
        ├── ipban.php : IP address ban system data.
        ├── lastupdatecheck.txt : Update check timestamp file (used to check every 24 hours if a new version of Shaarli is available).
        └──log.txt : login/IPban log.
    cache/ : Directory containing the thumbnails cache. This directory is automatically created. You can erase it anytime you want.
    tmp/ : Temporary directory for compiled RainTPL templates. This directory is automatically created. You can erase it anytime you want.


Why not use a real database ? Files are slow !

Does browsing this page feel slow ? Try browsing older pages, too.

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 ?

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.

Wiki - TODO