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.)
To correctly import the tags from a SemanticScuttle HTML export, edit the HTML file before importing and replace all occurences of tags= (lowercase) to TAGS= (uppercase).
-
Scuttle
-
Shaarli cannot import data directly from Scuttle. However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
-
Import Shaarli links to Firefox
-
-
Export your Shaarli links as described above.
-
For compatibility reasons, check Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)
-
In Firefox, open the bookmark manager (not the sidebar! Bookmarks menu > Show all bookmarks or Ctrl+Shift+B)
-
Select Import and Backup > Import bookmarks in HTML format
-
-
Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
-
You may be interested in these Firefox addons to manage links imported from Shaarli
Use the Search text field to search in any of the fields of all links (Title, URL, Description...)
-
Exclude text/tags: Use the - operator before a word or tag (example -uninteresting) to prevent entries containing (or tagged) uninteresting from showing up in the search results.
-
Exact text search: Use double-quotes (example "exact search") to search for the exact expression.
-
Both exclude patterns and exact searches can be combined with normal searches (example "exact search" term otherterm -notthis "very exact" stuff -notagain)
-
Tags search
-
Use the Filter by tags field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).
-
Hidden tags: Tags starting with a dot . (example .secret) are private. They can only be seen and searched when logged in.
-
Alternatively you can use the Tag cloud to discover all tags and click on any of them to display related links.
-
To search for links that are not tagged, enter "" in the tag search field.
-
Filtering RSS feeds/Picture wall
-
RSS feeds can also be restricted to only return items matching a text/tag search: see RSS feeds.
Unofficial but related 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 with the community fork.
Self dead link - Detect dead links on shaarli. This version use the database of shaarli. Another version, can be used for other shaarli instances (but is more resource consuming).
-
-
Mobile Apps
-
-
Shaarli💫 iOS share extension - see #308 for some promo codes,
-
Shaarli for Android - Android application that adds Shaarli as a sharing provider
-
Shaarlier for Android - Android application to simply add links directly into your Shaarli
Copy an existing installation over SSH and serve it locally
-
Example bash script:
-
#!/bin/bash
-#Description: Copy a Shaarli installation over SSH/SCP, serve it locally with php-cli
-#Will create a local-shaarli/ directory when you run it, backup your Shaarli there, and serve it locally.
-#Will NOT download linked pages. It's just a directly usable backup/copy/mirror of your Shaarli
-#Requires: ssh, scp and a working SSH access to the server where your Shaarli is installed
-#Usage: ./local-shaarli.sh
-#Author: nodiscc (nodiscc@gmail.com)
-#License: MIT (http://opensource.org/licenses/MIT)
-set-o errexit
-set-o nounset
-
-##### CONFIG #################
-#The port used by php's local server
-php_local_port=7431
-
-#Name of the SSH server and path where Shaarli is installed
-#TODO: pass these as command-line arguments
-remotehost="my.ssh.server"
-remote_shaarli_dir="/var/www/shaarli"
-
-
-###### FUNCTIONS #############
-_main(){
- _CBSyncShaarli
- _CBServeShaarli
-}
-
-_CBSyncShaarli(){
- remote_temp_dir=$(ssh$remotehost mktemp -d)
- remote_ssh_user=$(ssh$remotehost whoami)
- ssh -t "$remotehost" sudo cp -r "$remote_shaarli_dir""$remote_temp_dir"
- ssh -t "$remotehost" sudo chown -R "$remote_ssh_user":"$remote_ssh_user""$remote_temp_dir"
- scp -rq "$remotehost":"$remote_temp_dir" local-shaarli
- ssh"$remotehost" rm -r "$remote_temp_dir"
-}
-
-_CBServeShaarli(){
- #TODO: allow serving a previously downloaded Shaarli
- #TODO: ask before overwriting local copy, if it exists
- cd local-shaarli/
- php -S localhost:${php_local_port}
- echo"Please go to http://localhost:${php_local_port}"
-}
-
-
-##### MAIN #################
-
-_main
-
This outputs:
-
$ ./local-shaarli.sh
-PHP 5.6.0RC4 Development Server started at Mon Sep 1 21:56:19 2014
-Listening on http://localhost:7431
-Document root is /home/user/local-shaarli/shaarli
-Press Ctrl-C to quit.
-
-[Mon Sep 1 21:56:27 2014] ::1:57868 [200]: /[](.html)
-[Mon Sep 1 21:56:27 2014] ::1:57869 [200]: /index.html[](.html)
-[Mon Sep 1 21:56:37 2014] ::1:57881 [200]: /...[](.html)
Example bash script (creates multiple shaarli instances and generates an HTML index of them)
-
#!/bin/bash
-set-o errexit
-set-o nounset
-
-#config
-shaarli_base_dir='/var/www/shaarli'
-accounts='bob john whatever username'
-shaarli_repo_url='https://github.com/shaarli/Shaarli'
-ref="master"
-
-#clone multiple shaarli instances
-if [!-d"$shaarli_base_dir" ]; thenmkdir"$shaarli_base_dir";fi[](.html)
-
-foraccount in $accounts;do
- if [-d"$shaarli_base_dir/$account" ];[](.html)
- thenecho"[info] account $account already exists, skipping";[](.html)
- elseecho"[info] creating new account $account ...";git clone --quiet "$shaarli_repo_url" -b "$ref""$shaarli_base_dir/$account";fi[](.html)
-done
-
-#generate html index of shaarlis
-htmlhead='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<!-- Minimal html template thanks to http://www.sitepoint.com/a-minimal-html-document/ -->
-<html lang="en">
- <head>
- <meta http-equiv="content-type" content="text/html; charset=utf-8">
- <title>My Shaarli farm</title>
- <style>body {font-family: "Open Sans"}</style>
- </head>
- <body>
- <div>
- <h1>My Shaarli farm</h1>
- <ul style="list-style-type: none;">'
-
-accountlinks=''
-
-htmlfooter='
- </ul>
- </div>
- </body>
-</html>'
-
-
-
-foraccount in $accounts;doaccountlinks="$accountlinks\n<li><a href=\"$account\">$account</a></li>"; done
-if [-d"$shaarli_base_dir/index.html" ]; thenecho"[removing old index.html]";rm"$shaarli_base_dir/index.html" ];fi[](.html)
-echo"[info] generating new index of shaarlis"[](.html)
-echo -e "$htmlhead$accountlinks$htmlfooter">"$shaarli_base_dir/index.html"
-echo'[info] done.'[](.html)
-echo"[info] list of accounts: $accounts"[](.html)
-echo"[info] contents of $shaarli_base_dir:"[](.html)
-tree -a -L 1 "$shaarli_base_dir"
-
This script just serves as an example. More precise or complex (applying custom configuration, etc) automation is possible using configuration management software like Ansible
After all jobs have finished, Travis returns the results to GitHub:
-
-
a status icon represents the result for the master branch:
-
Pull Requests are updated with the Travis result
-
-
Green: all tests have passed
-
Red: some tests failed
-
Orange: tests are pending
-
-
-
-
diff --git a/doc/Development.md b/doc/Development.md
deleted file mode 100644
index 6cfcb683..00000000
--- a/doc/Development.md
+++ /dev/null
@@ -1,35 +0,0 @@
-#Development
-## Guidelines
-Please have a look at the following pages:
-- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)[](.html)
-- [Static analysis](Static-analysis.html) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
- - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard[](.html)
- - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide[](.html)
-- [Unit tests](Unit-tests.html)
-- [GnuPG signature](GnuPG-signature.html) for tags/releases
-
-## Continuous integration tools
-### Local development
-A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:[](.html)
-- Documentation - generate a local HTML copy of the GitHub wiki
-- [Static analysis](Static-analysis.html) - check that the code is compliant to PHP conventions
-- [Unit tests](Unit-tests.html) - ensure there are no regressions introduced by new commits
-
-### Automatic builds
-[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:[](.html)
-- each time a commit is merged to the mainline (`master` branch)
-- each time a Pull Request is submitted or updated
-
-A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server-requirements.html)).
-
-Each build job:
-- updates Composer
-- installs 3rd-party test dependencies with Composer
-- runs [Unit tests](Unit-tests.html)
-
-After all jobs have finished, Travis returns the results to GitHub:
-- a status icon represents the result for the `master` branch: []((https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli).html)
-- Pull Requests are updated with the Travis result
- - Green: all tests have passed
- - Red: some tests failed
- - Orange: tests are pending
diff --git a/doc/Directory-structure.html b/doc/Directory-structure.html
deleted file mode 100644
index 3f75db8e..00000000
--- a/doc/Directory-structure.html
+++ /dev/null
@@ -1,135 +0,0 @@
-
-
-
-
-
-
- Shaarli – Directory structure
-
-
-
-
-
-
-
$ docker search debian
-
-NAME DESCRIPTION STARS OFFICIAL AUTOMATED
-ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK][](.html)
-debian Debian is a Linux distribution that's comp... 603 [OK][](.html)
-google/debian 47 [OK][](.html)
-
Show available tags for a repository
-
$ curl https://index.docker.io/v1/repositories/debian/tags |python -m json.tool
-
-% Total % Received % Xferd Average Speed Time Time Time Current
-Dload Upload Total Spent Left Speed
-100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
# map the host's :8000 port to the container's :80 port
-$ docker create -p 8000:80 shaarli/shaarli
-d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
-
-# launch the container in the background
-$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
-d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
-
-# list active containers
-$ docker ps
-CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
-d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo
-
Stop and destroy a container
-
$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
-backstabbing_galileo
-
-# check the container is stopped
-$ docker ps
-CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
-
-# list ALL containers
-$ docker ps -a
-CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
-d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo
-
-# destroy the container
-$ docker rm backstabbing_galileo # let's put an end to these barbarian practices
-backstabbing_galileo
-
-$ docker ps -a
-CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your server is properly configured.
-
Several releases are available:
-
-
Latest release (recommended)
-
Download as an archive
-
Get the latest released version from the releases page.
-
Download our shaarli-full archive to include dependencies.
In most cases, download Shaarli from the releases page. Cloning using git or downloading Github branches as zip files requires additional steps (see below).
Example patch to add a new field ("via") for links, an input field to set the "via" property from the "edit link" dialog, and display the "via" field in the link list display. Untested, use at your own risk
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:
-
-
The data is yours: It's hosted on your server.
-
Never fear of having your data locked-in.
-
Never fear to have your data sold to third party.
-
Your private links are not hosted on a third party server.
-
You are not tracked by browser addons (like Diigo does)
-
You can change the look and feel of the pages if you want.
-
You can change the behaviour of the program.
-
It's magnitude faster than most bookmarking services.
-
-
What does Shaarli mean?
-
Shaarli is for shaaring your links.
-
My Shaarli is broken!
-
First of all, ensure that both the web server and Shaarli are correctly configured, and that your installation is supported.
-
If everything looks right but the issue(s) remain(s), please:
if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)
-
else, open a new issue, and provide information about the problem:
-
-
what happens? - display glitches, invalid data, security flaws...
-
what is your configuration? - OS, server version, activated extensions, web browser...
-
is it reproducible?
-
-
-
-
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.
Click the ✚Add to Firefox social button and accept the activation.
-
-
Sharing links using Firefox share
-
-
Add the sharing service as described above
-
When you are visiting a webpage you would like to share with Shaarli, click the Firefox Share button images/firefoxshare.png
-
You can edit your link before and after saving, just like the bookmarklet above.
-
-
-
-
-
-
-
-
-
-
Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections.
Gnu Privacy Guard (GnuPG) is an Open Source implementation of the Pretty Good [](.html)
-Privacy (OpenPGP) specification. Its main purposes are digital authentication,
-signature and encryption.
-
It is often used by the FLOSS community to verify:
You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
-
-
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during key signing parties, see:
$ gpg --gen-key
-
-gpg (GnuPG) 2.1.6;Copyright (C) 2015 Free Software Foundation, Inc.
-This is free software: you are free to change and redistribute it.
-There is NO WARRANTY, to the extent permitted by law.
-
-Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
-
-GnuPG needs to construct a user ID to identify your key.
-
-Real name: Marvin the Paranoid Android
-Email address: marvin@h2g2.net
-You selected this USER-ID:
- "Marvin the Paranoid Android <marvin@h2g2.net>"
-
-Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
-We need to generate a lot of random bytes. It is a good idea to perform
-some other action (type on the keyboard, move the mouse, utilize the
-disks) during the prime generation;this gives the random number
-generator a better chance to gain enough entropy.
-
gpg - entropy interlude
-
At this point, you will:
-
-
be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
-
be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step may take some time
-
-
gpg - key creation confirmation
-
gpg: key A9D53A3E marked as ultimately trusted
-public and secret key created and signed.
-
-gpg: checking the trustdb
-gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
-gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
-pub rsa2048/A9D53A3E 2015-07-31
- Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
-uid [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>[](.html)
-sub rsa2048/8C0EACF1 2015-07-31
-
gpg - submit your public key to a PGP server (Optional)
-
$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
-gpg: sending key A9D53A3E to hkp server pgp.mit.edu
If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion (archive) or read the current issues. If you've found a bug, please create a new issue.
-
If you would like a feature added to Shaarli, check the issues labeled feature, enhancement, and plugin.
At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an init() function to execute and run it if it exists. This function must be named this way, and takes the ConfigManager as parameter.
-
<plugin_name>_init($conf)
-
This function can be used to create initial data, load default settings, etc. But also to set plugin errors. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
-
Understanding hooks
-
A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
-
These functions need to be named with this pattern:
For exemple, if my plugin want to add data to the header, this function is needed:
-
hook_demo_plugin_render_header
-
If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
-
Plugin's data
-
Parameters
-
Every hook function has a $data parameter. Its content differs for each hooks.
-
This parameter needs to be returned every time, otherwise data is lost.
-
return $data;
-
Filling templates placeholder
-
Template placeholders are displayed in template in specific places.
-
RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
-
For example, let's add a value in the placeholder top_placeholder which is displayed at the top of my page:
-
$data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
-# OR
-array_push($data['top_placeholder'],'My','content');[](.html)
-
-return$data;
-
Data manipulation
-
When a page is displayed, every variable send to the template engine is passed to plugins before that in $data.
-
The data contained by this array can be altered before template rendering.
-
For exemple, in linklist, it is possible to alter every title:
-
// mind the reference if you want $data to be altered
-foreach($data['links']as &$value) {[](.html)
- // String reverse every title.
- $value['title'] = strrev($value['title']);[](.html)
-}
-
-return$data;
-
Metadata
-
Every plugin needs a <plugin_name>.meta file, which is in fact an .ini file (KEY="VALUE"), to be listed in plugin administration.
-
Each file contain two keys:
-
-
description: plugin description
-
parameters: user parameter names, separated by a ;.
-
parameter.<PARAMETER_NAME>: add a text description the specified parameter.
-
-
-
Note: In PHP, parse_ini_file() seems to want strings to be between by quotes " in the ini file.
-
-
It's not working!
-
Use demo_plugin as a functional example. It covers most of the plugin system features.
Make sure your webserver can read and write the files in your plugin folder.
-
-
Plugin configuration
-
In Shaarli's administration page (Tools link), go to Plugin administration.
-
Here you can enable and disable all plugins available, and configure them.
-
-
Plugin order
-
In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.
-
This is important in case plugins are depending on each other. Read plugins README details for more information.
-
Use case: The (non existent) plugin shaares_footer adds a footer to every shaare in Markdown syntax. It needs to be processed before (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.
-
File mode
-
Enabled plugin are stored in your config.php parameters file, under the array:
To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key iat (issued at). This token will be accepted during 9 minutes.
The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot ., hashed in SHA512 with the API secret available in Shaarli administration page.
Feeds are available in ATOM with ?do=atom and RSS with do=RSS.
-
Options:
-
-
You can use permalinks in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
-
-
E.G. https://my.shaarli.domain/?do=atom&permalinks.
-
-
You can use nb parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: 50). The keyword all is available if you want everything.
-
GitHub allows drafting the release note for the upcoming release, from the Releases page. This way, the release note can be drafted while contributions are merged to master.
-
CHANGELOG.md
-
This file should contain the same information as the release note draft for the upcoming version.
-
Update it to:
-
-
add new entries (additions, fixes, etc.)
-
mark the current version as released by setting its date and link
-
add a new section for the future unreleased version
Increment the version code, create and push a signed tag
-
Bump Shaarli's version
-
$ cd /path/to/shaarli
-
-# create a new branch
-$ git fetch upstream
-$ git checkout upstream/master -b v0.5.0
-
-# bump the version number
-$ vim index.php shaarli_version.php
-
-# rebuild the documentation from the wiki
-$ make htmldoc
-
-# commit the changes
-$ git add index.php shaarli_version.php doc
-$ git commit -s -m "Bump version to v0.5.0"
-
-# push the commit on your GitHub fork
-$ git push origin v0.5.0
-
Create and merge a Pull Request
-
This one is pretty straightforward ;-)
-
Create and push a signed tag
-
# update your local copy
-$ git checkout master
-$ git fetch upstream
-$ git pull upstream master
-
-# create a signed tag
-$ git tag -s -m "Release v0.5.0" v0.5.0
-
-# push it to "upstream"
-$ git push --tags upstream
-
Verify a signed tag
-
v0.5.0 is the first GPG-signed tag pushed on the Community Shaarli.
-
Let's have a look at its signature!
-
$ cd /path/to/shaarli
-$ git fetch upstream
-
-# get the SHA1 reference of the tag
-$ git show-ref tags/v0.5.0
-f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
-
-# verify the tag signature information
-$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
-gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
-gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)
-
Publish the GitHub release
-
Update release badges
-
Update README.md so version badges display and point to the newly released Shaarli version(s).
-
Create a GitHub release from a Git tag
-
From the previously drafted release:
-
-
edit the release notes (if needed)
-
specify the appropriate Git tag
-
publish the release
-
profit!
-
-
Generate and upload all-in-one release archives
-
Users with a shared hosting may have:
-
-
no SSH access
-
no possibility to install PHP packages or server extensions
-
no possibility to run scripts
-
-
To ease Shaarli installations, it is possible to generate and upload additional release archives,
-that will contain Shaarli code plus all required third-party libraries:
-
$ make release_archive
-
This will create the following archives:
-
-
shaarli-vX.Y.Z-full.tar
-
shaarli-vX.Y.Z-full.zip
-
-
The archives need to be manually uploaded on the previously created GitHub release.
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
-
-
PHP
-
-
magic_quotes is an 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.
-
-
Server and sessions
-
-
Directories are protected using .htaccess files
-
Forms are 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.
-
Tokens are attached to the session and cannot be reused in another session.
-
Sessions automatically expire after 60 minutes.
-
Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
-
-
Shaarli datastore and configuration
-
-
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.
-
Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a .php file.
-
Even if the server does not support .htaccess files, the data file will still not be readable by URL.
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 @.
Generate a self-signed certificate (will trigger browser warnings) with apache2: make-ssl-cert generate-default-snakeoil --force-overwrite will create /etc/ssl/certs/ssl-cert-snakeoil.pem and /etc/ssl/private/ssl-cert-snakeoil.key
-
-
Proxies
-
If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
Shaarli use .htaccess Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive AllowOverride All in your virtual host configuration for them to work.
-
Warning: If you use Apache 2.2 or lower, you need mod_version to be installed and enabled.
-
Apache module mod_rewritemust be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root .htaccess file.
-
LightHttpd
-
Nginx
-
Foreword
-
Nginx does not natively interpret PHP scripts; to this effect, we will run a FastCGI service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
Some bookmark dumps generated by web browsers can be huge due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
-
To increase upload size, you will need to modify both nginx and PHP configuration:
# /etc/nginx/nginx.conf
-[...][](.html)
-
-http {
- [...][](.html)
-
- root /home/john/web;
- access_log /var/log/nginx/access.log;
- error_log /var/log/nginx/error.log;
-
- server {
- # virtual host for a first domain
- listen 80;
- server_name my.first.domain.org;
-
- location /shaarli/ {
- # Slim - rewrite URLs
- try_files $uri /shaarli/index.php$is_args$args;
-
- access_log /var/log/nginx/shaarli.access.log;
- error_log /var/log/nginx/shaarli.error.log;
- }
-
- location = /shaarli/favicon.ico {
- # serve the Shaarli favicon from its custom location
- alias /var/www/shaarli/images/favicon.ico;
- }
-
- include deny.conf;
- include static_assets.conf;
- include php.conf;
- }
-
- server {
- # virtual host for a second domain
- listen 80;
- server_name second.domain.com;
-
- location /minigal/ {
- access_log /var/log/nginx/minigal.access.log;
- error_log /var/log/nginx/minigal.error.log;
- }
-
- include deny.conf;
- include static_assets.conf;
- include php.conf;
- }
-}
-
Redirect HTTP to HTTPS
-
Assuming you have generated a (self-signed) key and certificate, and they are located under /home/john/ssl/localhost.{key,crt}, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
Robots - Restricting search engines and web crawler traffic
-
Creating a robots.txt with the following contents at the root of your Shaarli installation will prevent honest web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
title: Shaarli's instance title.
-header_link: Link to the homepage.
-links_per_page: Number of shaares displayed per page.
-timezone: See the list of supported timezones.
-enabled_plugins: List of enabled plugins.
-
Security
-
session_protection_disabled: Disable session cookie hijacking protection (not recommended).
-It might be useful if your IP adress often changes.
-ban_after: Failed login attempts before being IP banned.
-ban_duration: IP ban duration in seconds.
-open_shaarli: Anyone can add a new link while logged out if enabled.
-trusted_proxies: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
-
Resources
-
data_dir: Data directory.
-datastore: Shaarli's links database file path.
-history: Shaarli's operation history file path.
-updates: File path for the ran updates file.
-log: Log file path.
-update_check: Last update check file path.
-raintpl_tpl: Templates directory.
-raintpl_tmp: Template engine cache directory.
-thumbnails_cache: Thumbnails cache directory.
-page_cache: Shaarli's internal cache directory.
-ban_file: Banned IP file path.
-
Updates
-
check_updates: Enable or disable update check to the git repository.
-check_updates_branch: Git branch used to check updates (e.g. stable or master).
-check_updates_interval: Look for new version every N seconds (default: every day).
-
Privacy
-
default_private_links: Check the private checkbox by default for every new link.
-hide_public_links: All links are hidden while logged out.
-hide_timestamps: Timestamps are hidden.
-
Feed
-
rss_permalinks: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
-show_atom: Display ATOM feed button.
-
Thumbnail
-
enable_thumbnails: Enable or disable thumbnail display.
-enable_localcache: Enable or disable local cache.
-
Redirector
-
url: Redirector URL, such as anonym.to.
-encode_url: Enable this if the redirector needs encoded URL to work properly.
Add the sharing button (bookmarklet) to your browser
-
-
Open your Shaarli and Login
-
Click the Tools button in the top bar
-
Drag the ✚Shaare link button, and drop it to your browser's bookmarks bar.
-
-
This bookmarklet button is 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.
-
-
Share links using the bookmarklet
-
-
When you are visiting a webpage you would like to share with Shaarli, click the bookmarklet you just added.
-
A window opens.
-
You can freely edit title, description, tags... to find it later using the text search or tag filtering.
-
You will be able to edit this link later using the
-
You can also check the “Private” box so that the link is saved but only visible to you.
-
Click Save.Voilà! Your link is now shared.
-
-
Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)
-
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
network.http.referer.trimmingPolicy - trim the URI not to send a full Referer
-
-
0 (default): send full URI
-
1: scheme+host+port+path
-
2: scheme+host+port
-
-
Firefox, localhost and redirections
-
localhost is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
-
To solve this, assign a local domain to your host, e.g.
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.
-
Hosting problems
-
Old PHP versions
-
-
On free.fr : free.fr now support php 5.6.x(link)and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a sessions directory and a .htaccess file containing:
-
-
<IfDefine Free>
-php56 1
-</IfDefine>
-
-
If you have an error such as: Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to .php5
-
On 1and1 : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
-
If you have the error Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
-
-
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
-// 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);
-
-
On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
-
On lost-oasis, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : <? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>. To fix this, remove this message from php-include/prepend.php
-
-
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 sebsauvage.net :-( )
-
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:
-
-
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.
-
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 !)
-
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).
-
Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
-
You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
-
If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
-
-
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]('PUBSUBHUB_URL']-in-your-config.php`.html)
# system-wide version
-$ composer install
-$ composer update
-
-# local version
-$ php composer.phar self-update
-$ php composer.phar install
-$ php composer.phar update
-
Install Shaarli dev dependencies
-
$ cd /path/to/shaarli
-$ composer update
-
Install and enable Xdebug to generate PHPUnit coverage reports
-
For Debian-based distros:
-
$ aptitude install php5-xdebug
-
For ArchLinux:
-
$ pacman -S xdebug
-
Then add the following line to /etc/php/php.ini:
-
zend_extension=xdebug.so
-
Run unit tests
-
Successful test suite:
-
$ make test
-
--------
-PHPUNIT
--------
-PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
-
-Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
-
-....................................
-
-Time: 759 ms, Memory: 8.25Mb
-
-OK (36 tests, 65 assertions)
-
Test suite with failures and errors:
-
$ make test
--------
-PHPUNIT
--------
-PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
-
-Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
-
-E..FF...............................
-
-Time: 802 ms, Memory: 8.25Mb
-
-There was 1 error:
-
-1) LinkDBTest::testConstructLoggedIn
-Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
-DBTest.php on line 79 and defined
-
-/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
-/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
-
---
-
-There were 2 failures:
-
-1) LinkDBTest::testCheckDBNew
-Failed asserting that two strings are equal.
---- Expected
-+++ Actual
-@@ @@
--'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
-+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
-
-/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
-
-2) LinkDBTest::testCheckDBLoad
-Failed asserting that two strings are equal.
---- Expected
-+++ Actual
-@@ @@
--'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
-+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
-
-/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
-
-FAILURES!
-Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
-
Test results and coverage
-
By default, PHPUnit will run all suitable tests found under the tests directory.
-
Each test has 3 possible outcomes:
-
-
. - success
-
F - failure: the test was run but its results are invalid
-
the code does not behave as expected
-
dependencies to external elements: globals, session, cache...
-
E - error: something went wrong and the tested code has crashed
-
typos in the code, or in the test code
-
dependencies to missing external elements
-
-
If Xdebug has been installed and activated, two coverage reports will be generated:
-
-
a summary in the console
-
a detailed HTML report with metrics for tested code
-
to open it in a web browser: firefox coverage/index.html &
-
-
Executing specific tests
-
Add a @group annotation in a test class or method comment:
It is recommended to backup this repository before starting updating/upgrading Shaarli:
-
-
users with SSH access: copy or archive the directory to a temporary location
-
users with FTP access: download a local copy of your Shaarli installation using your favourite client
-
-
Migrating data from a previous installation
-
As all user data is kept under data, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:
All tagged revisions can be downloaded as tarballs or ZIP archives from the releases page.
-
We recommend that you use the latest release tarball with the -full suffix. It contains the dependencies, please read Download and installation for git complete instructions.
-
Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the data directory!
-
After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to data/config.json.php (see Shaarli configuration for more details).
the default remote is named origin and points to Sebsauvage's repository
-
the current branch is master
-
-
if you have personal branches containing customizations, you will need to rebase them after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break
-
-
the working copy is clean:
-
-
no versioned file has been locally modified
-
no untracked files are present
-
-
-
Step 0: show repository information
-
$ cd /path/to/shaarli
-
-$ git remote -v
-origin https://github.com/sebsauvage/Shaarli (fetch)
-origin https://github.com/sebsauvage/Shaarli (push)
-
-$ git branch -vv
-* master 029f75f [origin/master] Update README.md[](.html)
-
-$ git status
-On branch master
-Your branch is up-to-date with 'origin/master'.
-nothing to commit, working directory clean
After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to data/config.php (see Shaarli configuration for more details).
-
Troubleshooting
-
If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
-
You must specify an integer as a key
-
In v0.8.1 we changed how link keys are handled (from timestamps to incremental integers).
-Take a look at data/updates.txt content.
-
updates.txt contains updateMethodDatastoreIds
-
Try to delete it and refresh your page while being logged in.
-
updates.txt doesn't exists or doesn't contain updateMethodDatastoreIds
-
-
Create data/updates.txt if it doesn't exist.
-
Paste this string in the update file ;updateMethodRenameDashTags;
It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
-
master branch
-
The master branch is the development branch. Any new change MUST go through this branch using Pull Requests.
-
Remarks:
-
-
This branch shouldn't be used for production as it isn't necessary stable.
-
3rd party aren't required to be compatible with the latest changes.
-
Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
-
The version in this branch is always dev.
-
-
v0.x branch
-
This v0.x branch, points to the latest v0.x.y release.
-
Explanation:
-
When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
-
In this case, the issue is fixed in the master branch, and the fix is backported the to the v0.x branch. Then a new release is made from the v0.x branch.
-
This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
-
latest branch
-
This branch point the latest release. It recommended to use it to get the latest tested changes.
-
stable branch
-
The stable branch doesn't contain any major bug, and is one major digit version behind the latest release.
-
For example, the current latest release is v0.8.3, the stable branch is an alias to the latest v0.7.x release. When the v0.9.0 version will be released, the stable will move to the latest v0.8.x release.
-
Remarks:
-
-
Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
-
-
Releases
-
Releases are always made from the latest v0.x branch.
-
Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
-
Advices on 3rd party git repos workflow
-
Versioning
-
Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the changelog (Draft means not released yet) and the commit log (like tpl folder for themes)). You can either:
-
-
use the Shaarli version number, with your repo version. For example, if Shaarli v0.8.3 is released, publish a v0.8.3-1 release, where v0.8.3 states Shaarli compatibility and -1 is your own version digit for the current Shaarli version.
-
use your own versioning scheme, and state Shaarli compatibility in the release description.
-
-
Using this, any user will be able to pick the release matching his own Shaarli version.
-
Major bugfix backport releases
-
To be able to support backported fixes, it recommended to use our workflow:
-
# In master, fix the major bug
-git commit -m "Katastrophe"
-git push origin master
-# Get your commit hash
-git log --format="%H" -n 1
-# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
-git checkout -b katastrophe v0.8.2-1
-# Backport the fix commit to your brand new branch
-git cherry-pick <fix commit hash>
-git push origin katastrophe
-# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
To export links as an HTML file, under Tools > Export, choose:
+- Export all to export both public and private links
+- Export public to export public links only
+- Export private to export private links only
+
Restore by using the Import feature.
+* This can be done using the shaarchiver tool.
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.)
To correctly import the tags from a SemanticScuttle HTML export, edit the HTML file before importing and replace all occurences of tags= (lowercase) to TAGS= (uppercase).
+
Scuttle
+
Shaarli cannot import data directly from Scuttle. However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
+
Import Shaarli links to Firefox
+
+
Export your Shaarli links as described above.
+
For compatibility reasons, check Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)
+
In Firefox, open the bookmark manager (not the sidebar! Bookmarks menu > Show all bookmarks or Ctrl+Shift+B)
+
Select Import and Backup > Import bookmarks in HTML format
+
+
Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
+
You may be interested in these Firefox addons to manage links imported from Shaarli
Add the sharing button (bookmarklet) to your browser
+
+
Open your Shaarli and Login
+
Click the Tools button in the top bar
+
Drag the ✚Shaare link button, and drop it to your browser's bookmarks bar.
+
+
This bookmarklet button is 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.
+
+
Share links using the bookmarklet
+
+
When you are visiting a webpage you would like to share with Shaarli, click the bookmarklet you just added.
+
A window opens.
+
You can freely edit title, description, tags... to find it later using the text search or tag filtering.
+
You will be able to edit this link later using the edit button.
+
You can also check the “Private” box so that the link is saved but only visible to you.
+
Click Save.Voilà! Your link is now shared.
+
+
Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)
+
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
Use the Search text field to search in any of the fields of all links (Title, URL, Description...)
+
Exclude text/tags: Use the - operator before a word or tag (example -uninteresting) to prevent entries containing (or tagged) uninteresting from showing up in the search results.
+
Exact text search: Use double-quotes (example "exact search") to search for the exact expression.
+
Both exclude patterns and exact searches can be combined with normal searches (example "exact search" term otherterm -notthis "very exact" stuff -notagain)
+
Tags search
+
Use the Filter by tags field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).
+
Hidden tags: Tags starting with a dot . (example .secret) are private. They can only be seen and searched when logged in.
+
Alternatively you can use the Tag cloud to discover all tags and click on any of them to display related links.
+
To search for links that are not tagged, enter "" in the tag search field.
+
Filtering RSS feeds/Picture wall
+
RSS feeds can also be restricted to only return items matching a text/tag search: see RSS feeds.
Unofficial but related 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 with the community fork.
Self dead link - Detect dead links on shaarli. This version use the database of shaarli. Another version, can be used for other shaarli instances (but is more resource consuming).
+
Bookmark Archiver - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
+
+
Mobile Apps
+
+
ShaarliOS iOS share extension - see #308 for some promo codes,
+
Shaarli for Android - Android application that adds Shaarli as a sharing provider
+
Shaarlier for Android - Android application to simply add links directly into your Shaarli
A Makefile is available to perform project-related operations:
+- Documentation - generate a local HTML copy of the GitHub wiki
+- Static analysis - check that the code is compliant to PHP conventions
+- Unit tests - ensure there are no regressions introduced by new commits
+
Automatic builds
+
Travis CI is a Continuous Integration build server, that runs a build:
+- each time a commit is merged to the mainline (master branch)
+- each time a Pull Request is submitted or updated
+
A build is composed of several jobs: one for each supported PHP version (see Server requirements).
+
Each build job:
+- updates Composer
+- installs 3rd-party test dependencies with Composer
+- runs Unit tests
+
After all jobs have finished, Travis returns the results to GitHub:
+- a status icon represents the result for the master branch:
+- Pull Requests are updated with the Travis result
+ - Green: all tests have passed
+ - Red: some tests failed
+ - Orange: tests are pending
#!/bin/bash
+#Description: Copy a Shaarli installation over SSH/SCP, serve it locally with php-cli
+#Will create a local-shaarli/ directory when you run it, backup your Shaarli there, and serve it locally.
+#Will NOT download linked pages. It's just a directly usable backup/copy/mirror of your Shaarli
+#Requires: ssh, scp and a working SSH access to the server where your Shaarli is installed
+#Usage: ./local-shaarli.sh
+#Author: nodiscc (nodiscc@gmail.com)
+#License: MIT (http://opensource.org/licenses/MIT)
+set -o errexit
+set -o nounset
+
+##### CONFIG #################
+#The port used by php's local server
+php_local_port=7431
+
+#Name of the SSH server and path where Shaarli is installed
+#TODO: pass these as command-line arguments
+remotehost="my.ssh.server"
+remote_shaarli_dir="/var/www/shaarli"
+
+
+###### FUNCTIONS #############
+_main() {
+ _CBSyncShaarli
+ _CBServeShaarli
+}
+
+_CBSyncShaarli() {
+ remote_temp_dir=$(ssh $remotehost mktemp -d)
+ remote_ssh_user=$(ssh $remotehost whoami)
+ ssh -t "$remotehost" sudo cp -r "$remote_shaarli_dir" "$remote_temp_dir"
+ ssh -t "$remotehost" sudo chown -R "$remote_ssh_user":"$remote_ssh_user" "$remote_temp_dir"
+ scp -rq "$remotehost":"$remote_temp_dir" local-shaarli
+ ssh "$remotehost" rm -r "$remote_temp_dir"
+}
+
+_CBServeShaarli() {
+ #TODO: allow serving a previously downloaded Shaarli
+ #TODO: ask before overwriting local copy, if it exists
+ cd local-shaarli/
+ php -S localhost:${php_local_port}
+ echo "Please go to http://localhost:${php_local_port}"
+}
+
+
+##### MAIN #################
+
+_main
+
+
+
This outputs:
+
$ ./local-shaarli.sh
+PHP 5.6.0RC4 Development Server started at Mon Sep 1 21:56:19 2014
+Listening on http://localhost:7431
+Document root is /home/user/local-shaarli/shaarli
+Press Ctrl-C to quit.
+
+[Mon Sep 1 21:56:27 2014] ::1:57868 [200]: /
+[Mon Sep 1 21:56:27 2014] ::1:57869 [200]: /index.html
+[Mon Sep 1 21:56:37 2014] ::1:57881 [200]: /...
+
Example bash script (creates multiple shaarli instances and generates an HTML index of them)
+
#!/bin/bash
+set -o errexit
+set -o nounset
+
+#config
+shaarli_base_dir='/var/www/shaarli'
+accounts='bob john whatever username'
+shaarli_repo_url='https://github.com/shaarli/Shaarli'
+ref="master"
+
+#clone multiple shaarli instances
+if [ ! -d "$shaarli_base_dir" ]; then mkdir "$shaarli_base_dir"; fi
+
+for account in $accounts; do
+ if [ -d "$shaarli_base_dir/$account" ];
+ then echo "[info] account $account already exists, skipping";
+ else echo "[info] creating new account $account ..."; git clone --quiet "$shaarli_repo_url" -b "$ref" "$shaarli_base_dir/$account"; fi
+done
+
+#generate html index of shaarlis
+htmlhead='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!-- Minimal html template thanks to http://www.sitepoint.com/a-minimal-html-document/ -->
+<html lang="en">
+ <head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8">
+ <title>My Shaarli farm</title>
+ <style>body {font-family: "Open Sans"}</style>
+ </head>
+ <body>
+ <div>
+ <h1>My Shaarli farm</h1>
+ <ul style="list-style-type: none;">'
+
+accountlinks=''
+
+htmlfooter='
+ </ul>
+ </div>
+ </body>
+</html>'
+
+
+
+for account in $accounts; do accountlinks="$accountlinks\n<li><a href=\"$account\">$account</a></li>"; done
+if [ -d "$shaarli_base_dir/index.html" ]; then echo "[removing old index.html]"; rm "$shaarli_base_dir/index.html" ]; fi
+echo "[info] generating new index of shaarlis"
+echo -e "$htmlhead $accountlinks $htmlfooter" > "$shaarli_base_dir/index.html"
+echo '[info] done.'
+echo "[info] list of accounts: $accounts"
+echo "[info] contents of $shaarli_base_dir:"
+tree -a -L 1 "$shaarli_base_dir"
+
+
+
This script just serves as an example. More precise or complex (applying custom configuration, etc) automation is possible using configuration management software like Ansible
$ docker search debian
+
+NAME DESCRIPTION STARS OFFICIAL AUTOMATED
+ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]
+debian Debian is a Linux distribution that's comp... 603 [OK]
+google/debian 47 [OK]
+
+
+
Show available tags for a repository
+
$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
+
+% Total % Received % Xferd Average Speed Time Time Time Current
+Dload Upload Total Spent Left Speed
+100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
+
To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your server is properly configured.
+
Several releases are available:
+
+
Latest release (recommended)
+
Download as an archive
+
Get the latest released version from the releases page.
+
Download our shaarli-full archive to include dependencies.
In most cases, download Shaarli from the releases page. Cloning using git or downloading Github branches as zip files requires additional steps (see below).
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:
+
+
The data is yours: It's hosted on your server.
+
Never fear of having your data locked-in.
+
Never fear to have your data sold to third party.
+
Your private links are not hosted on a third party server.
+
You are not tracked by browser addons (like Diigo does)
+
You can change the look and feel of the pages if you want.
+
You can change the behaviour of the program.
+
It's magnitude faster than most bookmarking services.
+
+
What does Shaarli mean?
+
Shaarli is for shaaring your links.
+
My Shaarli is broken!
+
First of all, ensure that both the web server and Shaarli are correctly configured, and that your installation is supported.
+
If everything looks right but the issue(s) remain(s), please:
+- take a look at the troubleshooting section
+- come chat with us on Gitter, we'll be happy to help ;-)
+- browse active issues and Pull Requests
+ - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)
+ - else, open a new issue, and provide information about the problem:
+ - what happens? - display glitches, invalid data, security flaws...
+ - what is your configuration? - OS, server version, activated extensions, web browser...
+ - is it reproducible?
+
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.
Shaarli is intended:
+ * to share, comment and save interesting links and news
+ * to bookmark useful/frequent personal links (as private links) and share them between computers
+ * as a minimal blog/microblog/writing platform (no character limit)
+ * as a read-it-later list (for example items tagged readlater)
+ * to draft and save articles/ideas
+ * to keep code snippets
+ * to keep notes and documentation
+ * as a shared clipboard between machines
+ * as a todo list
+ * to store playlists (e.g. with the music or video tags)
+ * to keep extracts/comments from webpages that may disappear
+ * to keep track of ongoing discussions (for example items tagged discussion)
+ * to feed RSS aggregators (planets) with specific tags
+ * to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
+
Using Shaarli as a blog, notepad, pastebin...
+
+
Go to your Shaarli setup and log in
+
Click the Add Link button
+
To share text only, do not enter any URL in the corresponding input field and click Add Link
+
Pick a title and enter your article, or note, in the description field; add a few tags; optionally check Private then click Save
+
Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
Click the ✚Add to Firefox social button and accept the activation.
+
+
Sharing links using Firefox share
+
+
Add the sharing service as described above
+
When you are visiting a webpage you would like to share with Shaarli, click the Firefox Share button images/firefoxshare.png
+
You can edit your link before and after saving, just like the bookmarklet above.
+
+
+
+
+
+
Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections.
Gnu Privacy Guard (GnuPG) is an Open Source implementation of the Pretty Good
+Privacy (OpenPGP) specification. Its main purposes are digital authentication,
+signature and encryption.
+
It is often used by the FLOSS community to verify:
+- Linux package signatures: Debian SecureApt, ArchLinux Master
+Keys
+- SCM releases & maintainer identity
+
Trust
+
To quote Phil Pennock (the author of the SKS key server - http://sks.spodhuis.org/):
+
+
You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
$ gpg --gen-key
+
+gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
+
+GnuPG needs to construct a user ID to identify your key.
+
+Real name: Marvin the Paranoid Android
+Email address: marvin@h2g2.net
+You selected this USER-ID:
+ "Marvin the Paranoid Android <marvin@h2g2.net>"
+
+Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
+We need to generate a lot of random bytes. It is a good idea to perform
+some other action (type on the keyboard, move the mouse, utilize the
+disks) during the prime generation; this gives the random number
+generator a better chance to gain enough entropy.
+
+
+
gpg - entropy interlude
+
At this point, you will:
+- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
+- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step may take some time
At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an init() function to execute and run it if it exists. This function must be named this way, and takes the ConfigManager as parameter.
+
<plugin_name>_init($conf)
+
+
This function can be used to create initial data, load default settings, etc. But also to set plugin errors. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
+
Understanding hooks
+
A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
+
These functions need to be named with this pattern:
When a page is displayed, every variable send to the template engine is passed to plugins before that in $data.
+
The data contained by this array can be altered before template rendering.
+
For exemple, in linklist, it is possible to alter every title:
+
// mind the reference if you want $data to be altered
+foreach ($data['links'] as &$value) {
+ // String reverse every title.
+ $value['title'] = strrev($value['title']);
+}
+
+return $data;
+
+
+
Metadata
+
Every plugin needs a <plugin_name>.meta file, which is in fact an .ini file (KEY="VALUE"), to be listed in plugin administration.
+
Each file contain two keys:
+
+
description: plugin description
+
parameters: user parameter names, separated by a ;.
+
parameter.<PARAMETER_NAME>: add a text description the specified parameter.
+
+
+
Note: In PHP, parse_ini_file() seems to want strings to be between by quotes " in the ini file.
+
+
It's not working!
+
Use demo_plugin as a functional example. It covers most of the plugin system features.
Make sure your webserver can read and write the files in your plugin folder.
+
+
Plugin configuration
+
In Shaarli's administration page (Tools link), go to Plugin administration.
+
Here you can enable and disable all plugins available, and configure them.
+
+
Plugin order
+
In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.
+
This is important in case plugins are depending on each other. Read plugins README details for more information.
+
Use case: The (non existent) plugin shaares_footer adds a footer to every shaare in Markdown syntax. It needs to be processed before (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.
+
File mode
+
Enabled plugin are stored in your config.php parameters file, under the array:
To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key iat (issued at). This token will be accepted during 9 minutes.
The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot ., hashed in SHA512 with the API secret available in Shaarli administration page.
Feeds are available in ATOM with ?do=atom and RSS with do=RSS.
+
Options:
+- You can use permalinks in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
+ - E.G. https://my.shaarli.domain/?do=atom&permalinks.
+- You can use nb parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: 50). The keyword all is available if you want everything.
+ - https://my.shaarli.domain/?do=atom&permalinks&nb=42
+ - https://my.shaarli.domain/?do=atom&permalinks&nb=all
+
RSS Feeds or Picture Wall for a specific search/tag
+
It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to only display results of a specific search, or for a specific tag.
+
For example, if you want to subscribe only to links tagged photography:
+- Go to the desired Shaarli instance.
+- Search for the photography tag in the Filter by tag box. Links tagged photography are displayed.
+- Click on the RSS Feed button.
+- You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.
+- The same method also works for a full-text search (Search box) and for the Picture Wall (want to only see pictures about nature?)
+- You can also build the URLs manually:
+ - https://my.shaarli.domain/?do=rss&searchtags=nature
+ - https://my.shaarli.domain/links/?do=picwall&searchterm=poney
This guide assumes that you have:
+- a GPG key matching your GitHub authentication credentials
+ - i.e., the email address identified by the GPG key is the same as the one in your ~/.gitconfig
+- a GitHub fork of Shaarli
+- a local clone of your Shaarli fork, with the following remotes:
+ - origin pointing to your GitHub fork
+ - upstream pointing to the main Shaarli repository
+- maintainer permissions on the main Shaarli repository, to:
+ - push the signed tag
+ - create a new release
+- Composer and Pandoc need to be installed
+
GitHub release draft and CHANGELOG.md
+
See http://keepachangelog.com/en/0.3.0/ for changelog formatting.
+
GitHub release draft
+
GitHub allows drafting the release note for the upcoming release, from the Releases page. This way, the release note can be drafted while contributions are merged to master.
+
CHANGELOG.md
+
This file should contain the same information as the release note draft for the upcoming version.
+
Update it to:
+- add new entries (additions, fixes, etc.)
+- mark the current version as released by setting its date and link
+- add a new section for the future unreleased version
Increment the version code, updated docs, create and push a signed tag
+
Generate documentation
+
$ cd /path/to/shaarli
+
+# create a new branch
+$ git fetch upstream
+$ git checkout upstream/master -b v0.5.0
+
+# rebuild the documentation from the wiki
+$ make htmldoc
+
+# commit the changes
+$ git add doc
+$ git commit -s -m "Generate documentation for v0.5.0"
+
+# push the commit on your GitHub fork
+$ git push origin v0.5.0
+
+
+
Create and merge a Pull Request
+
This one is pretty straightforward ;-)
+
Bump Shaarli version to v0.x branch
+
$ git checkout master
+$ git fetch upstream
+$ git pull upstream master
+
+# IF the branch doesn't exists
+$ git checkout -b v0.5
+# OR if the branch already exists
+$ git checkout v0.5
+$ git rebase upstream/master
+
+# Bump shaarli version from dev to 0.5.0, **without the `v`**
+$ vim shaarli_version.php
+$ git add shaarli_version
+$ git commit -s -m "Bump Shaarli version to v0.5.0"
+$ git push upstream v0.5
+
+
+
Create and push a signed tag
+
# update your local copy
+$ git checkout v0.5
+$ git fetch upstream
+$ git pull upstream v0.5
+
+# create a signed tag
+$ git tag -s -m "Release v0.5.0" v0.5.0
+
+# push it to "upstream"
+$ git push --tags upstream
+
+
+
Verify a signed tag
+
v0.5.0 is the first GPG-signed tag pushed on the Community Shaarli.
+
Let's have a look at its signature!
+
$ cd /path/to/shaarli
+$ git fetch upstream
+
+# get the SHA1 reference of the tag
+$ git show-ref tags/v0.5.0
+f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
+
+# verify the tag signature information
+$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
+gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
+gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate]
+
+
+
Publish the GitHub release
+
Update release badges
+
Update README.md so version badges display and point to the newly released Shaarli version(s), in the master branch.
+
Create a GitHub release from a Git tag
+
From the previously drafted release:
+- edit the release notes (if needed)
+- specify the appropriate Git tag
+- publish the release
+- profit!
+
Generate and upload all-in-one release archives
+
Users with a shared hosting may have:
+- no SSH access
+- no possibility to install PHP packages or server extensions
+- no possibility to run scripts
+
To ease Shaarli installations, it is possible to generate and upload additional release archives,
+that will contain Shaarli code plus all required third-party libraries.
+
From the v0.5 branch:
+
$ make release_archive
+
+
+
This will create the following archives:
+- shaarli-vX.Y.Z-full.tar
+- shaarli-vX.Y.Z-full.zip
+
The archives need to be manually uploaded on the previously created GitHub release.
+
Update stable and latest branches
+
$ git checkout latest
+# latest release
+$ git merge v0.5.0
+# fix eventual conflicts
+$ make test
+$ git push upstream latest
+$ git checkout stable
+# latest previous major
+$ git merge v0.4.5
+# fix eventual conflicts
+$ make test
+$ git push upstream stable
+
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
+
+
PHP
+
+
magic_quotes is an 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.
+
+
Server and sessions
+
+
Directories are protected using .htaccess files
+
Forms are 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.
+
Tokens are attached to the session and cannot be reused in another session.
+
Sessions automatically expire after 60 minutes.
+
Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
+
+
Shaarli datastore and configuration
+
+
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.
+
Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a .php file.
+
Even if the server does not support .htaccess files, the data file will still not be readable by URL.
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 @.
If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
+- X-Forwarded-Proto;
+- X-Forwarded-Host;
+- X-Forwarded-For.
Shaarli use .htaccess Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive AllowOverride All in your virtual host configuration for them to work.
+
Warning: If you use Apache 2.2 or lower, you need mod_version to be installed and enabled.
+
Apache module mod_rewritemust be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root .htaccess file.
+
LightHttpd
+
Nginx
+
Foreword
+
Nginx does not natively interpret PHP scripts; to this effect, we will run a FastCGI service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
Once Nginx and PHP-FPM are installed, we need to ensure:
+- Nginx and PHP-FPM are running using the same user and group
+- both these user and group have
+ - read permissions for Shaarli resources
+ - execute permissions for Shaarli directories AND their parent directories
+
On a production server:
+- user:group will likely be http:http, www:www or www-data:www-data
+- files will be located under /var/www, /var/http or /usr/share/nginx
+
On a development server:
+- files may be located in a user's home directory
+- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
+
For all following configuration examples, this user/group pair will be used:
+- user:group = john:users,
+
which corresponds to the following service configuration:
+
; /etc/php/php-fpm.conf
+user = john
+group = users
+
+[...]
+listen.owner = john
+listen.group = users
+
Some bookmark dumps generated by web browsers can be huge due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
+
To increase upload size, you will need to modify both nginx and PHP configuration:
The previous setup is sufficient for development purposes, but has several major caveats:
+- every content that does not match the PHP rule will be sent to client browsers:
+ - dotfiles - in our case, .htaccess
+ - temporary files, e.g. Vim or Emacs files: index.php~
+- asset / static resource caching is not optimized
+- if serving several PHP sites, there will be a lot of duplication: location /shaarli/, location /mysite/, etc.
+
To solve this, we will split Nginx configuration in several parts, that will be included when needed:
# /etc/nginx/nginx.conf
+[...]
+
+http {
+ [...]
+
+ root /home/john/web;
+ access_log /var/log/nginx/access.log;
+ error_log /var/log/nginx/error.log;
+
+ server {
+ # virtual host for a first domain
+ listen 80;
+ server_name my.first.domain.org;
+
+ location /shaarli/ {
+ # Slim - rewrite URLs
+ try_files $uri /shaarli/index.php$is_args$args;
+
+ access_log /var/log/nginx/shaarli.access.log;
+ error_log /var/log/nginx/shaarli.error.log;
+ }
+
+ location = /shaarli/favicon.ico {
+ # serve the Shaarli favicon from its custom location
+ alias /var/www/shaarli/images/favicon.ico;
+ }
+
+ include deny.conf;
+ include static_assets.conf;
+ include php.conf;
+ }
+
+ server {
+ # virtual host for a second domain
+ listen 80;
+ server_name second.domain.com;
+
+ location /minigal/ {
+ access_log /var/log/nginx/minigal.access.log;
+ error_log /var/log/nginx/minigal.error.log;
+ }
+
+ include deny.conf;
+ include static_assets.conf;
+ include php.conf;
+ }
+}
+
+
+
Redirect HTTP to HTTPS
+
Assuming you have generated a (self-signed) key and certificate, and they are located under /home/john/ssl/localhost.{key,crt}, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
PHP settings are defined in:
+- a main configuration file, usually found under /etc/php5/php.ini; some distributions provide different configuration environments, e.g.
+ - /etc/php5/php.ini - used when running console scripts
+ - /etc/php5/apache2/php.ini - used when a client requests PHP resources from Apache
+ - /etc/php5/php-fpm.conf - used when PHP requests are proxied to PHP-FPM
+- additional configuration files/entries, depending on the installed/enabled extensions:
+ - /etc/php/conf.d/xdebug.ini
create a phpinfo.php script located in a path supported by the web server, e.g.
+
Apache (with user dirs enabled): /home/myself/public_html/phpinfo.php
+
/var/www/test/phpinfo.php
+
+
+
make sure the script is readable by the web server user/group (usually, www, www-data or httpd)
+
access the script from a web browser
+
look at the Loaded Configuration File and Scan this dir for additional .ini files entries
+
+
<?php phpinfo(); ?>
+
+
+
fail2ban
+
fail2ban is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses iptables profiles to block brute-force attempts:
+- Official website
+- Source code
+
Read Shaarli logs to ban IPs
+
Example configuration:
+- allow 3 login attempts per IP address
+- after 3 failures, permanently ban the corresponding IP adddress
Robots - Restricting search engines and web crawler traffic
+
Creating a robots.txt with the following contents at the root of your Shaarli installation will prevent honest web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
Do not edit configuration options in index.php! Your changes would be lost.
+
Once your Shaarli instance is installed, the file data/config.json.php is generated:
+ it contains all settings in JSON format, and can be edited to customize values
+ it defines which plugins are enabled
+ its values override those defined in index.php
+ it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
+
File and directory permissions
+
The server process running Shaarli must have:
+- read access to the following resources:
+ - PHP scripts: index.php, application/*.php, plugins/*.php
+ - 3rd party PHP and Javascript libraries: inc/*.php, inc/*.js
+ - static assets:
+ - CSS stylesheets: inc/*.css
+ - images/*
+ - RainTPL templates: tpl/*.html
+- read, write and execution access to the following directories:
+ - cache - thumbnail cache
+ - data - link data store, configuration options
+ - pagecache - Atom/RSS feed cache
+ - tmp - RainTPL page cache
+
On a Linux distribution:
+- the web server user will likely be www or http (for Apache2)
+- it will be a member of a group of the same name: www:www, http:http
+- to give it access to Shaarli, either:
+ - unzip Shaarli in the default web server location (usually /var/www/) and set the web server user as the owner
+ - put users in the same group as the web server, and set the appropriate access rights
+- if you have a domain / subdomain to serve Shaarli, configure the server accordingly
title: Shaarli's instance title.
+header_link: Link to the homepage.
+links_per_page: Number of shaares displayed per page.
+timezone: See the list of supported timezones.
+enabled_plugins: List of enabled plugins.
+
Security
+
session_protection_disabled: Disable session cookie hijacking protection (not recommended).
+It might be useful if your IP adress often changes.
+ban_after: Failed login attempts before being IP banned.
+ban_duration: IP ban duration in seconds.
+open_shaarli: Anyone can add a new link while logged out if enabled.
+trusted_proxies: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
+allowed_protocols: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store javascript: links (bookmarklets) in Shaarli (default: ["ftp", "ftps", "magnet"]).
+
Resources
+
data_dir: Data directory.
+datastore: Shaarli's links database file path.
+history: Shaarli's operation history file path.
+updates: File path for the ran updates file.
+log: Log file path.
+update_check: Last update check file path.
+raintpl_tpl: Templates directory.
+raintpl_tmp: Template engine cache directory.
+thumbnails_cache: Thumbnails cache directory.
+page_cache: Shaarli's internal cache directory.
+ban_file: Banned IP file path.
+
Updates
+
check_updates: Enable or disable update check to the git repository.
+check_updates_branch: Git branch used to check updates (e.g. stable or master).
+check_updates_interval: Look for new version every N seconds (default: every day).
+
Privacy
+
default_private_links: Check the private checkbox by default for every new link.
+hide_public_links: All links are hidden while logged out.
+hide_timestamps: Timestamps are hidden.
+
Feed
+
rss_permalinks: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
+show_atom: Display ATOM feed button.
+
Thumbnail
+
enable_thumbnails: Enable or disable thumbnail display.
+enable_localcache: Enable or disable local cache.
+
Redirector
+
url: Redirector URL, such as anonym.to.
+encode_url: Enable this if the redirector needs encoded URL to work properly.
# map the host's :8000 port to the container's :80 port
+$ docker create -p 8000:80 shaarli/shaarli
+d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+
+# launch the container in the background
+$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+
+# list active containers
+$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo
+
+
+
Stop and destroy a container
+
$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
+backstabbing_galileo
+
+# check the container is stopped
+$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+
+# list ALL containers
+$ docker ps -a
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo
+
+# destroy the container
+$ docker rm backstabbing_galileo # let's put an end to these barbarian practices
+backstabbing_galileo
+
+$ docker ps -a
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+
WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.
+
Installation:
+- find a theme you'd like to install
+- copy or clone the theme folder under tpl/<a_sweet_theme>
+- enable the theme:
+ - Shaarli < v0.9.0: edit data/config.json.php and set the value of raintpl_tpl to the new theme name:
+ "raintpl_tpl": "tpl\/my-template\/"
+ - Shaarli >= v0.9.0: select the theme through the Tools page
With the following configuration:
+- Apache 2 / PHP 5.6
+- user sites are enabled, e.g. /home/user/public_html/somedir is served as http://localhost/~user/somedir
+- http is the name of the Apache user
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
HTTP settings are available by browsing about:config, here are the available settings and their values.
+
network.http.sendRefererHeader - determines when to send the Referer HTTP header
+- 0: Never send the referring URL
+ - not recommended, may break some sites
+- 1: Send only on clicked links
+- 2 (default): Send for links and images
+
network.http.referer.XOriginPolicy - Cross-domain origin policy
+- 0 (default): Always send
+- 1: Send if base domains match
+- 2: Send if hosts match
+
network.http.referer.spoofSource - Referer spoofing (~faking)
+- false (default): real referer
+- true: spoof referer (use target URI as referer)
+ - known to break some functionality in Shaarli
+
network.http.referer.trimmingPolicy - trim the URI not to send a full Referer
+- 0 (default): send full URI
+- 1: scheme+host+port+path
+- 2: scheme+host+port
+
Firefox, localhost and redirections
+
localhost is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
+
To solve this, assign a local domain to your host, e.g.
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.
+
Hosting problems
+
Old PHP versions
+
+
On free.fr : free.fr now support php 5.6.x(link)and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a sessions directory and a .htaccess file containing:
+
+
<IfDefine Free>
+php56 1
+</IfDefine>
+
+
+
+
If you have an error such as: Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to .php5
+
On 1and1 : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
+
If you have the error Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
+
+
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
+// 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);
+
+
+
+
On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
+
On lost-oasis, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : <? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>. To fix this, remove this message from php-include/prepend.php
+
+
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 sebsauvage.net :-( )
+
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:
+
+
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.
+
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 !)
+
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).
+
Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
+
You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
+
If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
+
+
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
The framework used is PHPUnit; it can be installed with Composer, which is a dependency management tool.
+
Regarding Composer, you can either use:
+ a system-wide version, e.g. installed through your distro's package manager
+ a local version, downloadable here
+
Sample usage
+
# system-wide version
+$ composer install
+$ composer update
+
+# local version
+$ php composer.phar self-update
+$ php composer.phar install
+$ php composer.phar update
+
+
+
Install Shaarli dev dependencies
+
$ cd /path/to/shaarli
+$ composer update
+
+
+
Install and enable Xdebug to generate PHPUnit coverage reports
+
For Debian-based distros:
+
$ aptitude install php5-xdebug
+
+
+
For ArchLinux:
+
$ pacman -S xdebug
+
+
+
Then add the following line to /etc/php/php.ini:
+
zend_extension=xdebug.so
+
+
+
Run unit tests
+
Successful test suite:
+
$ make test
+
+-------
+PHPUNIT
+-------
+PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
+
+Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
+
+....................................
+
+Time: 759 ms, Memory: 8.25Mb
+
+OK (36 tests, 65 assertions)
+
+
+
Test suite with failures and errors:
+
$ make test
+-------
+PHPUNIT
+-------
+PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
+
+Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
+
+E..FF...............................
+
+Time: 802 ms, Memory: 8.25Mb
+
+There was 1 error:
+
+1) LinkDBTest::testConstructLoggedIn
+Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
+DBTest.php on line 79 and defined
+
+/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
+/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
+
+--
+
+There were 2 failures:
+
+1) LinkDBTest::testCheckDBNew
+Failed asserting that two strings are equal.
+--- Expected
++++ Actual
+@@ @@
+-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
++'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
+
+/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
+
+2) LinkDBTest::testCheckDBLoad
+Failed asserting that two strings are equal.
+--- Expected
++++ Actual
+@@ @@
+-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
++'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
+
+/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
+
+FAILURES!
+Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
+
+
+
Test results and coverage
+
By default, PHPUnit will run all suitable tests found under the tests directory.
+
Each test has 3 possible outcomes:
+. - success
+F - failure: the test was run but its results are invalid
+ * the code does not behave as expected
+ * dependencies to external elements: globals, session, cache...
+* E - error: something went wrong and the tested code has crashed
+ * typos in the code, or in the test code
+ * dependencies to missing external elements
+
If Xdebug has been installed and activated, two coverage reports will be generated:
+ a summary in the console
+ a detailed HTML report with metrics for tested code
+ * to open it in a web browser: firefox coverage/index.html &
+
Executing specific tests
+
Add a @group annotation in a test class or method comment:
If anything goes wrong, it's important for us to know which version you're upgrading from.
+The current version is present in the version.php file.
+
Backup your data
+
Shaarli stores all user data under the data directory:
+- data/config.php - main configuration file
+- data/datastore.php - bookmarked links
+- data/ipbans.php - banned IP addresses
+- data/updates.txt - contains all automatic update to the configuration and datastore files already run
It is recommended to backup this repository before starting updating/upgrading Shaarli:
+- users with SSH access: copy or archive the directory to a temporary location
+- users with FTP access: download a local copy of your Shaarli installation using your favourite client
+
Migrating data from a previous installation
+
As all user data is kept under data, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:
All tagged revisions can be downloaded as tarballs or ZIP archives from the releases page.
+
We recommend that you use the latest release tarball with the -full suffix. It contains the dependencies, please read Download and installation for git complete instructions.
+
Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the data directory!
+
After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to data/config.json.php (see Shaarli configuration for more details).
The following guide assumes that:
+- you have a basic knowledge of Git branching and remote repositories
+- the default remote is named origin and points to Sebsauvage's repository
+- the current branch is master
+ - if you have personal branches containing customizations, you will need to rebase them after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break!
+- the working copy is clean:
+ - no versioned file has been locally modified
+ - no untracked files are present
+
Step 0: show repository information
+
$ cd /path/to/shaarli
+
+$ git remote -v
+origin https://github.com/sebsauvage/Shaarli (fetch)
+origin https://github.com/sebsauvage/Shaarli (push)
+
+$ git branch -vv
+* master 029f75f [origin/master] Update README.md
+
+$ git status
+On branch master
+Your branch is up-to-date with 'origin/master'.
+nothing to commit, working directory clean
+
After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to data/config.php (see Shaarli configuration for more details).
+
Troubleshooting
+
If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
+
You must specify an integer as a key
+
In v0.8.1 we changed how link keys are handled (from timestamps to incremental integers).
+Take a look at data/updates.txt content.
+
updates.txt contains updateMethodDatastoreIds
+
Try to delete it and refresh your page while being logged in.
+
updates.txt doesn't exists or doesn't contain updateMethodDatastoreIds
+
+
Create data/updates.txt if it doesn't exist.
+
Paste this string in the update file ;updateMethodRenameDashTags;
It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
+
master branch
+
The master branch is the development branch. Any new change MUST go through this branch using Pull Requests.
+
Remarks:
+
+
This branch shouldn't be used for production as it isn't necessary stable.
+
3rd party aren't required to be compatible with the latest changes.
+
Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
+
The version in this branch is always dev.
+
+
v0.x branch
+
This v0.x branch, points to the latest v0.x.y release.
+
Explanation:
+
When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
+
In this case, the issue is fixed in the master branch, and the fix is backported the to the v0.x branch. Then a new release is made from the v0.x branch.
+
This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
+
latest branch
+
This branch point the latest release. It recommended to use it to get the latest tested changes.
+
stable branch
+
The stable branch doesn't contain any major bug, and is one major digit version behind the latest release.
+
For example, the current latest release is v0.8.3, the stable branch is an alias to the latest v0.7.x release. When the v0.9.0 version will be released, the stable will move to the latest v0.8.x release.
+
Remarks:
+
+
Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
+
+
Releases
+
Releases are always made from the latest v0.x branch.
+
Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
+
Advices on 3rd party git repos workflow
+
Versioning
+
Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the changelog (Draft means not released yet) and the commit log (like tpl folder for themes)). You can either:
+
+
use the Shaarli version number, with your repo version. For example, if Shaarli v0.8.3 is released, publish a v0.8.3-1 release, where v0.8.3 states Shaarli compatibility and -1 is your own version digit for the current Shaarli version.
+
use your own versioning scheme, and state Shaarli compatibility in the release description.
+
+
Using this, any user will be able to pick the release matching his own Shaarli version.
+
Major bugfix backport releases
+
To be able to support backported fixes, it recommended to use our workflow:
+
# In master, fix the major bug
+git commit -m "Katastrophe"
+git push origin master
+# Get your commit hash
+git log --format="%H" -n 1
+# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
+git checkout -b katastrophe v0.8.2-1
+# Backport the fix commit to your brand new branch
+git cherry-pick <fix commit hash>
+git push origin katastrophe
+# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
+
If you have any questions or ideas, please join the chat (also reachable via IRC), post them in our general discussion (archive) or read the current issues. If you've found a bug, please create a new issue.
+
If you would like a feature added to Shaarli, check the issues labeled feature, enhancement, and plugin.
+
Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the doc/ directory of your Shaarli installation.
\n\n\n\n\nfeed.atom.xml\n and \nfeed.rss.xml\n:\n\n\nIn headers tags section:\n\n\n{loop=\"$feed_plugins_header\"}\n {$value}\n{/loop}\n\n\n\n\nAfter each entry:\n\n\n{loop=\"$value.feed_plugins\"}\n {$value}\n{/loop}",
+ "title": "Plugin System"
+ },
+ {
+ "location": "/Plugin-System/#developer-api",
+ "text": "",
+ "title": "Developer API"
+ },
+ {
+ "location": "/Plugin-System/#what-can-i-do-with-plugins",
+ "text": "The plugin system let you: insert content into specific places across templates. alter data before templates rendering. alter data before saving new links.",
+ "title": "What can I do with plugins?"
+ },
+ {
+ "location": "/Plugin-System/#how-can-i-create-a-plugin-for-shaarli",
+ "text": "First, chose a plugin name, such as demo_plugin . Under plugin folder, create a folder named with your plugin name. Then create a .php file in that folder. You should have the following tree view: | index.php\n| plugins/\n|---| demo_plugin/\n| |---| demo_plugin.php",
+ "title": "How can I create a plugin for Shaarli?"
+ },
+ {
+ "location": "/Plugin-System/#plugin-initialization",
+ "text": "At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an init() function to execute and run it if it exists. This function must be named this way, and takes the ConfigManager as parameter. _init($conf) This function can be used to create initial data, load default settings, etc. But also to set plugin errors . If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.",
+ "title": "Plugin initialization"
+ },
+ {
+ "location": "/Plugin-System/#understanding-hooks",
+ "text": "A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution. These functions need to be named with this pattern: hook__($data, $conf) Parameters: data: see $data section conf: the ConfigManager instance. For exemple, if my plugin want to add data to the header, this function is needed: hook_demo_plugin_render_header If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.",
+ "title": "Understanding hooks"
+ },
+ {
+ "location": "/Plugin-System/#plugins-data",
+ "text": "",
+ "title": "Plugin's data"
+ },
+ {
+ "location": "/Plugin-System/#parameters",
+ "text": "Every hook function has a $data parameter. Its content differs for each hooks. This parameter needs to be returned every time , otherwise data is lost. return $data;",
+ "title": "Parameters"
+ },
+ {
+ "location": "/Plugin-System/#filling-templates-placeholder",
+ "text": "Template placeholders are displayed in template in specific places. RainTPL displays every element contained in the placeholder's array. These element can be added by plugins. For example, let's add a value in the placeholder top_placeholder which is displayed at the top of my page: $data['top_placeholder'][] = 'My content';\n# OR\narray_push($data['top_placeholder'], 'My', 'content');\n\nreturn $data;",
+ "title": "Filling templates placeholder"
+ },
+ {
+ "location": "/Plugin-System/#data-manipulation",
+ "text": "When a page is displayed, every variable send to the template engine is passed to plugins before that in $data . The data contained by this array can be altered before template rendering. For exemple, in linklist, it is possible to alter every title: // mind the reference if you want $data to be altered\nforeach ($data['links'] as &$value) {\n // String reverse every title.\n $value['title'] = strrev($value['title']);\n}\n\nreturn $data;",
+ "title": "Data manipulation"
+ },
+ {
+ "location": "/Plugin-System/#metadata",
+ "text": "Every plugin needs a .meta file, which is in fact an .ini file ( KEY=\"VALUE\" ), to be listed in plugin administration. Each file contain two keys: description : plugin description parameters : user parameter names, separated by a ; . parameter. : add a text description the specified parameter. Note: In PHP, parse_ini_file() seems to want strings to be between by quotes \" in the ini file.",
+ "title": "Metadata"
+ },
+ {
+ "location": "/Plugin-System/#its-not-working",
+ "text": "Use demo_plugin as a functional example. It covers most of the plugin system features. If it's still not working, please open an issue .",
+ "title": "It's not working!"
+ },
+ {
+ "location": "/Plugin-System/#hooks",
+ "text": "Hooks Description render_header Allow plugin to add content in page headers. render_includes Allow plugin to include their own CSS files. render_footer Allow plugin to add content in page footer and include their own JS files. render_linklist It allows to add content at the begining and end of the page, after every link displayed and to alter link data. render_editlink Allow to add fields in the form, or display elements. render_tools Allow to add content at the end of the page. render_picwall Allow to add content at the top and bottom of the page. render_tagcloud Allow to add content at the top and bottom of the page, and after all tags. render_taglist Allow to add content at the top and bottom of the page, and after all tags. render_daily Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. render_feed Allow to do add tags in RSS and ATOM feeds. save_link Allow to alter the link being saved in the datastore. delete_link Allow to do an action before a link is deleted from the datastore.",
+ "title": "Hooks"
+ },
+ {
+ "location": "/Plugin-System/#render_header",
+ "text": "Triggered on every page. Allow plugin to add content in page headers.",
+ "title": "render_header"
+ },
+ {
+ "location": "/Plugin-System/#data",
+ "text": "$data is an array containing: _PAGE_ : current target page (eg: linklist , picwall , etc.). _LOGGEDIN_ : true if user is logged in, false otherwise.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: buttons_toolbar : after the list of buttons in the header. fields_toolbar : after search fields in the header. Note: This will only be called in linklist.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_includes",
+ "text": "Triggered on every page. Allow plugin to include their own CSS files.",
+ "title": "render_includes"
+ },
+ {
+ "location": "/Plugin-System/#data_1",
+ "text": "$data is an array containing: _PAGE_ : current target page (eg: linklist , picwall , etc.). _LOGGEDIN_ : true if user is logged in, false otherwise.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_1",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: css_files : called after loading default CSS. Note: only add the path of the CSS file. E.g: plugins/demo_plugin/custom_demo.css .",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_footer",
+ "text": "Triggered on every page. Allow plugin to add content in page footer and include their own JS files.",
+ "title": "render_footer"
+ },
+ {
+ "location": "/Plugin-System/#data_2",
+ "text": "$data is an array containing: _PAGE_ : current target page (eg: linklist , picwall , etc.). _LOGGEDIN_ : true if user is logged in, false otherwise.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_2",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: text : called after the end of the footer text. endofpage : called at the end of the page. js_files : called at the end of the page, to include custom JS scripts. Note: only add the path of the JS file. E.g: plugins/demo_plugin/custom_demo.js .",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_linklist",
+ "text": "Triggered when linklist is displayed (list of links, permalink, search, tag filtered, etc.). It allows to add content at the begining and end of the page, after every link displayed and to alter link data.",
+ "title": "render_linklist"
+ },
+ {
+ "location": "/Plugin-System/#data_3",
+ "text": "$data is an array containing: _LOGGEDIN_ : true if user is logged in, false otherwise. All templates data, including links.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_3",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: action_plugin : next to the button \"private only\" at the top and bottom of the page. link_plugin : for every link, between permalink and link URL. plugin_start_zone : before displaying the template content. plugin_end_zone : after displaying the template content.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_editlink",
+ "text": "Triggered when the link edition form is displayed. Allow to add fields in the form, or display elements.",
+ "title": "render_editlink"
+ },
+ {
+ "location": "/Plugin-System/#data_4",
+ "text": "$data is an array containing: All templates data.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_4",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: edit_link_plugin : after tags field.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_tools",
+ "text": "Triggered when the \"tools\" page is displayed. Allow to add content at the end of the page.",
+ "title": "render_tools"
+ },
+ {
+ "location": "/Plugin-System/#data_5",
+ "text": "$data is an array containing: All templates data.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_5",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: tools_plugin : at the end of the page.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_picwall",
+ "text": "Triggered when picwall is displayed. Allow to add content at the top and bottom of the page.",
+ "title": "render_picwall"
+ },
+ {
+ "location": "/Plugin-System/#data_6",
+ "text": "$data is an array containing: _LOGGEDIN_ : true if user is logged in, false otherwise. All templates data.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_6",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: plugin_start_zone : before displaying the template content. plugin_end_zone : after displaying the template content.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_tagcloud",
+ "text": "Triggered when tagcloud is displayed. Allow to add content at the top and bottom of the page.",
+ "title": "render_tagcloud"
+ },
+ {
+ "location": "/Plugin-System/#data_7",
+ "text": "$data is an array containing: _LOGGEDIN_ : true if user is logged in, false otherwise. All templates data.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_7",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: plugin_start_zone : before displaying the template content. plugin_end_zone : after displaying the template content. For each tag, the following placeholder can be used: tag_plugin : after each tag",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_taglist",
+ "text": "Triggered when taglist is displayed. Allow to add content at the top and bottom of the page.",
+ "title": "render_taglist"
+ },
+ {
+ "location": "/Plugin-System/#data_8",
+ "text": "$data is an array containing: _LOGGEDIN_ : true if user is logged in, false otherwise. All templates data.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_8",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: plugin_start_zone : before displaying the template content. plugin_end_zone : after displaying the template content. For each tag, the following placeholder can be used: tag_plugin : after each tag",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_daily",
+ "text": "Triggered when tagcloud is displayed. Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.",
+ "title": "render_daily"
+ },
+ {
+ "location": "/Plugin-System/#data_9",
+ "text": "$data is an array containing: _LOGGEDIN_ : true if user is logged in, false otherwise. All templates data, including links.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_9",
+ "text": "Items can be displayed in templates by adding an entry in $data[''] array. List of placeholders: link_plugin : used at bottom of each link. plugin_start_zone : before displaying the template content. plugin_end_zone : after displaying the template content.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#render_feed",
+ "text": "Triggered when the ATOM or RSS feed is displayed. Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.",
+ "title": "render_feed"
+ },
+ {
+ "location": "/Plugin-System/#data_10",
+ "text": "$data is an array containing: _LOGGEDIN_ : true if user is logged in, false otherwise. _PAGE_ : containing either rss or atom . All templates data, including links.",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#template-placeholders_10",
+ "text": "Tags can be added in feeds by adding an entry in $data[''] array. List of placeholders: feed_plugins_header : used as a header tag in the feed. For each links: feed_plugins : additional tag for every link entry.",
+ "title": "Template placeholders"
+ },
+ {
+ "location": "/Plugin-System/#save_link",
+ "text": "Triggered when a link is save (new link or edit). Allow to alter the link being saved in the datastore.",
+ "title": "save_link"
+ },
+ {
+ "location": "/Plugin-System/#data_11",
+ "text": "$data is an array containing the link being saved: id title url shorturl description private tags created updated",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#delete_link",
+ "text": "Triggered when a link is deleted. Allow to execute any action before the link is actually removed from the datastore",
+ "title": "delete_link"
+ },
+ {
+ "location": "/Plugin-System/#data_12",
+ "text": "$data is an array containing the link being saved: id title url shorturl description private tags created updated",
+ "title": "Data"
+ },
+ {
+ "location": "/Plugin-System/#guide-for-template-designer",
+ "text": "",
+ "title": "Guide for template designer"
+ },
+ {
+ "location": "/Plugin-System/#plugin-administration",
+ "text": "Your theme must include a plugin administration page: pluginsadmin.html . Note: repo's template link needs to be added when the PR is merged. Use the default one as an example. Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include plugin_admin.js , only if: you're using a table. you call orderUp() and orderUp() onclick on arrows. you add data-line and data-order to your rows. Otherwise, you can use your own JS as long as this field is send by the form:",
+ "title": "Plugin administration"
+ },
+ {
+ "location": "/Plugin-System/#placeholder-system",
+ "text": "In order to make plugins work with every custom themes, you need to add variable placeholder in your templates. It's a RainTPL loop like this: {loop=\"$plugin_variable\"}\n {$value}\n{/loop} You should enable demo_plugin for testing purpose, since it uses every placeholder available.",
+ "title": "Placeholder system"
+ },
+ {
+ "location": "/Plugin-System/#list-of-placeholders",
+ "text": "page.header.html At the end of the menu: {loop=\"$plugins_header.buttons_toolbar\"}\n {$value}\n{/loop} At the end of file, before clearing floating blocks: {if=\"!empty($plugin_errors) && isLoggedIn()\"}\n
\n {loop=\"plugin_errors\"}\n
{$value}
\n {/loop}\n
\n{/if} includes.html At the end of the file: {loop=\"$plugins_includes.css_files\"}\n\n{/loop} page.footer.html At the end of your footer notes: {loop=\"$plugins_footer.text\"}\n {$value}\n{/loop} At the end of file: {loop=\"$plugins_footer.js_files\"}\n \n{/loop} linklist.html After search fields: {loop=\"$plugins_header.fields_toolbar\"}\n {$value}\n{/loop} Before displaying the link list (after paging): {loop=\"$plugin_start_zone\"}\n {$value}\n{/loop} For every links (icons): {loop=\"$value.link_plugin\"}\n {$value}\n{/loop} Before end paging: {loop=\"$plugin_end_zone\"}\n {$value}\n{/loop} linklist.paging.html After the \"private only\" icon: {loop=\"$action_plugin\"}\n {$value}\n{/loop} editlink.html After tags field: {loop=\"$edit_link_plugin\"}\n {$value}\n{/loop} tools.html After the last tool: {loop=\"$tools_plugin\"}\n {$value}\n{/loop} picwall.html Top:
feed.atom.xml and feed.rss.xml : In headers tags section: {loop=\"$feed_plugins_header\"}\n {$value}\n{/loop} After each entry: {loop=\"$value.feed_plugins\"}\n {$value}\n{/loop}",
+ "title": "List of placeholders"
+ },
+ {
+ "location": "/Release-Shaarli/",
+ "text": "See \nGit - Maintaining a project - Tagging your \nreleases\n.\n\n\nPrerequisites\n\n\nThis guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n - i.e., the email address identified by the GPG key is the same as the one in your \n~/.gitconfig\n \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n - \norigin\n pointing to your GitHub fork\n - \nupstream\n pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n - push the signed tag\n - create a new release\n- \nComposer\n and \nPandoc\n need to be installed\n\n\nGitHub release draft and \nCHANGELOG.md\n\n\nSee http://keepachangelog.com/en/0.3.0/ for changelog formatting.\n\n\nGitHub release draft\n\n\nGitHub allows drafting the release note for the upcoming release, from the \nReleases\n page. This way, the release note can be drafted while contributions are merged to \nmaster\n.\n\n\nCHANGELOG.md\n\n\nThis file should contain the same information as the release note draft for the upcoming version.\n\n\nUpdate it to:\n- add new entries (additions, fixes, etc.)\n- mark the current version as released by setting its date and link\n- add a new section for the future unreleased version\n\n\n$ cd /path/to/shaarli\n\n$ nano CHANGELOG.md\n\n[...]\n## vA.B.C - UNRELEASED\nTBA\n\n## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD\n[...]\n\n\n\n\nIncrement the version code, updated docs, create and push a signed tag\n\n\nGenerate documentation\n\n\n$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the documentation from the wiki\n$ make htmldoc\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0\n\n\n\n\nCreate and merge a Pull Request\n\n\nThis one is pretty straightforward ;-)\n\n\nBump Shaarli version to v0.x branch\n\n\n$ git checkout master\n$ git fetch upstream\n$ git pull upstream master\n\n# IF the branch doesn't exists\n$ git checkout -b v0.5\n# OR if the branch already exists\n$ git checkout v0.5\n$ git rebase upstream/master\n\n# Bump shaarli version from dev to 0.5.0, **without the `v`**\n$ vim shaarli_version.php\n$ git add shaarli_version\n$ git commit -s -m \"Bump Shaarli version to v0.5.0\"\n$ git push upstream v0.5\n\n\n\n\nCreate and push a signed tag\n\n\n# update your local copy\n$ git checkout v0.5\n$ git fetch upstream\n$ git pull upstream v0.5\n\n# create a signed tag\n$ git tag -s -m \"Release v0.5.0\" v0.5.0\n\n# push it to \"upstream\"\n$ git push --tags upstream\n\n\n\n\nVerify a signed tag\n\n\nv0.5.0\n is the first GPG-signed tag pushed on the Community Shaarli.\n\n\nLet's have a look at its signature!\n\n\n$ cd /path/to/shaarli\n$ git fetch upstream\n\n# get the SHA1 reference of the tag\n$ git show-ref tags/v0.5.0\nf7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0\n\n# verify the tag signature information\n$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1\ngpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F\ngpg: Good signature from \"VirtualTam \" [ultimate]\n\n\n\n\nPublish the GitHub release\n\n\nUpdate release badges\n\n\nUpdate \nREADME.md\n so version badges display and point to the newly released Shaarli version(s), in the \nmaster\n branch.\n\n\nCreate a GitHub release from a Git tag\n\n\nFrom the previously drafted release:\n- edit the release notes (if needed)\n- specify the appropriate Git tag\n- publish the release\n- profit!\n\n\nGenerate and upload all-in-one release archives\n\n\nUsers with a shared hosting may have:\n- no SSH access\n- no possibility to install PHP packages or server extensions\n- no possibility to run scripts\n\n\nTo ease Shaarli installations, it is possible to generate and upload additional release archives,\nthat will contain Shaarli code plus all required third-party libraries.\n\n\nFrom the \nv0.5\n branch:\n\n\n$ make release_archive\n\n\n\n\nThis will create the following archives:\n- \nshaarli-vX.Y.Z-full.tar\n\n- \nshaarli-vX.Y.Z-full.zip\n\n\nThe archives need to be manually uploaded on the previously created GitHub release.\n\n\nUpdate \nstable\n and \nlatest\n branches\n\n\n$ git checkout latest\n# latest release\n$ git merge v0.5.0\n# fix eventual conflicts\n$ make test\n$ git push upstream latest\n$ git checkout stable\n# latest previous major\n$ git merge v0.4.5 \n# fix eventual conflicts\n$ make test\n$ git push upstream stable",
+ "title": "Release Shaarli"
+ },
+ {
+ "location": "/Release-Shaarli/#prerequisites",
+ "text": "This guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n - i.e., the email address identified by the GPG key is the same as the one in your ~/.gitconfig \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n - origin pointing to your GitHub fork\n - upstream pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n - push the signed tag\n - create a new release\n- Composer and Pandoc need to be installed",
+ "title": "Prerequisites"
+ },
+ {
+ "location": "/Release-Shaarli/#github-release-draft-and-changelogmd",
+ "text": "See http://keepachangelog.com/en/0.3.0/ for changelog formatting.",
+ "title": "GitHub release draft and CHANGELOG.md"
+ },
+ {
+ "location": "/Release-Shaarli/#github-release-draft",
+ "text": "GitHub allows drafting the release note for the upcoming release, from the Releases page. This way, the release note can be drafted while contributions are merged to master .",
+ "title": "GitHub release draft"
+ },
+ {
+ "location": "/Release-Shaarli/#changelogmd",
+ "text": "This file should contain the same information as the release note draft for the upcoming version. Update it to:\n- add new entries (additions, fixes, etc.)\n- mark the current version as released by setting its date and link\n- add a new section for the future unreleased version $ cd /path/to/shaarli\n\n$ nano CHANGELOG.md\n\n[...]\n## vA.B.C - UNRELEASED\nTBA\n\n## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD\n[...]",
+ "title": "CHANGELOG.md"
+ },
+ {
+ "location": "/Release-Shaarli/#increment-the-version-code-updated-docs-create-and-push-a-signed-tag",
+ "text": "",
+ "title": "Increment the version code, updated docs, create and push a signed tag"
+ },
+ {
+ "location": "/Release-Shaarli/#generate-documentation",
+ "text": "$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the documentation from the wiki\n$ make htmldoc\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0",
+ "title": "Generate documentation"
+ },
+ {
+ "location": "/Release-Shaarli/#create-and-merge-a-pull-request",
+ "text": "This one is pretty straightforward ;-)",
+ "title": "Create and merge a Pull Request"
+ },
+ {
+ "location": "/Release-Shaarli/#bump-shaarli-version-to-v0x-branch",
+ "text": "$ git checkout master\n$ git fetch upstream\n$ git pull upstream master\n\n# IF the branch doesn't exists\n$ git checkout -b v0.5\n# OR if the branch already exists\n$ git checkout v0.5\n$ git rebase upstream/master\n\n# Bump shaarli version from dev to 0.5.0, **without the `v`**\n$ vim shaarli_version.php\n$ git add shaarli_version\n$ git commit -s -m \"Bump Shaarli version to v0.5.0\"\n$ git push upstream v0.5",
+ "title": "Bump Shaarli version to v0.x branch"
+ },
+ {
+ "location": "/Release-Shaarli/#create-and-push-a-signed-tag",
+ "text": "# update your local copy\n$ git checkout v0.5\n$ git fetch upstream\n$ git pull upstream v0.5\n\n# create a signed tag\n$ git tag -s -m \"Release v0.5.0\" v0.5.0\n\n# push it to \"upstream\"\n$ git push --tags upstream",
+ "title": "Create and push a signed tag"
+ },
+ {
+ "location": "/Release-Shaarli/#verify-a-signed-tag",
+ "text": "v0.5.0 is the first GPG-signed tag pushed on the Community Shaarli. Let's have a look at its signature! $ cd /path/to/shaarli\n$ git fetch upstream\n\n# get the SHA1 reference of the tag\n$ git show-ref tags/v0.5.0\nf7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0\n\n# verify the tag signature information\n$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1\ngpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F\ngpg: Good signature from \"VirtualTam \" [ultimate]",
+ "title": "Verify a signed tag"
+ },
+ {
+ "location": "/Release-Shaarli/#publish-the-github-release",
+ "text": "",
+ "title": "Publish the GitHub release"
+ },
+ {
+ "location": "/Release-Shaarli/#update-release-badges",
+ "text": "Update README.md so version badges display and point to the newly released Shaarli version(s), in the master branch.",
+ "title": "Update release badges"
+ },
+ {
+ "location": "/Release-Shaarli/#create-a-github-release-from-a-git-tag",
+ "text": "From the previously drafted release:\n- edit the release notes (if needed)\n- specify the appropriate Git tag\n- publish the release\n- profit!",
+ "title": "Create a GitHub release from a Git tag"
+ },
+ {
+ "location": "/Release-Shaarli/#generate-and-upload-all-in-one-release-archives",
+ "text": "Users with a shared hosting may have:\n- no SSH access\n- no possibility to install PHP packages or server extensions\n- no possibility to run scripts To ease Shaarli installations, it is possible to generate and upload additional release archives,\nthat will contain Shaarli code plus all required third-party libraries. From the v0.5 branch: $ make release_archive This will create the following archives:\n- shaarli-vX.Y.Z-full.tar \n- shaarli-vX.Y.Z-full.zip The archives need to be manually uploaded on the previously created GitHub release.",
+ "title": "Generate and upload all-in-one release archives"
+ },
+ {
+ "location": "/Release-Shaarli/#update-stable-and-latest-branches",
+ "text": "$ git checkout latest\n# latest release\n$ git merge v0.5.0\n# fix eventual conflicts\n$ make test\n$ git push upstream latest\n$ git checkout stable\n# latest previous major\n$ git merge v0.4.5 \n# fix eventual conflicts\n$ make test\n$ git push upstream stable",
+ "title": "Update stable and latest branches"
+ },
+ {
+ "location": "/Versioning-and-Branches/",
+ "text": "WORK IN PROGRESS\n\n\nIt's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.\n\n\nmaster\n branch\n\n\nThe \nmaster\n branch is the development branch. Any new change MUST go through this branch using Pull Requests.\n\n\nRemarks:\n\n\n\n\nThis branch shouldn't be used for production as it isn't necessary stable.\n\n\n3rd party aren't required to be compatible with the latest changes.\n\n\nOfficial plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.\n\n\nThe version in this branch is always \ndev\n.\n\n\n\n\nv0.x\n branch\n\n\nThis \nv0.x\n branch, points to the latest \nv0.x.y\n release.\n\n\nExplanation:\n\n\nWhen a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.\n\n\nIn this case, the issue is fixed in the \nmaster\n branch, and the fix is backported the to the \nv0.x\n branch. Then a new release is made from the \nv0.x\n branch.\n\n\nThis workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.\n\n\nlatest\n branch\n\n\nThis branch point the latest release. It recommended to use it to get the latest tested changes.\n\n\nstable\n branch\n\n\nThe \nstable\n branch doesn't contain any major bug, and is one major digit version behind the latest release.\n\n\nFor example, the current latest release is \nv0.8.3\n, the stable branch is an alias to the latest \nv0.7.x\n release. When the \nv0.9.0\n version will be released, the stable will move to the latest \nv0.8.x\n release.\n\n\nRemarks:\n\n\n\n\nShaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.\n\n\n\n\nReleases\n\n\nReleases are always made from the latest \nv0.x\n branch.\n\n\nNote that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.\n\n\nAdvices on 3rd party git repos workflow\n\n\nVersioning\n\n\nAny time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the \nchangelog\n (\nDraft\n means not released yet) and the commit log (like \ntpl\n folder\n for themes)). You can either:\n\n\n\n\nuse the Shaarli version number, with your repo version. For example, if Shaarli \nv0.8.3\n is released, publish a \nv0.8.3-1\n release, where \nv0.8.3\n states Shaarli compatibility and \n-1\n is your own version digit for the current Shaarli version.\n\n\nuse your own versioning scheme, and state Shaarli compatibility in the release description.\n\n\n\n\nUsing this, any user will be able to pick the release matching his own Shaarli version.\n\n\nMajor bugfix backport releases\n\n\nTo be able to support backported fixes, it recommended to use our workflow:\n\n\n# In master, fix the major bug\ngit commit -m \"Katastrophe\"\ngit push origin master\n# Get your commit hash\ngit log --format=\"%H\" -n 1\n# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)\ngit checkout -b katastrophe v0.8.2-1\n# Backport the fix commit to your brand new branch\ngit cherry-pick \ngit push origin katastrophe\n# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`",
+ "title": "Versioning and Branches"
+ },
+ {
+ "location": "/Versioning-and-Branches/#master-branch",
+ "text": "The master branch is the development branch. Any new change MUST go through this branch using Pull Requests. Remarks: This branch shouldn't be used for production as it isn't necessary stable. 3rd party aren't required to be compatible with the latest changes. Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch. The version in this branch is always dev .",
+ "title": "master branch"
+ },
+ {
+ "location": "/Versioning-and-Branches/#v0x-branch",
+ "text": "This v0.x branch, points to the latest v0.x.y release. Explanation: When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli. In this case, the issue is fixed in the master branch, and the fix is backported the to the v0.x branch. Then a new release is made from the v0.x branch. This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.",
+ "title": "v0.x branch"
+ },
+ {
+ "location": "/Versioning-and-Branches/#latest-branch",
+ "text": "This branch point the latest release. It recommended to use it to get the latest tested changes.",
+ "title": "latest branch"
+ },
+ {
+ "location": "/Versioning-and-Branches/#stable-branch",
+ "text": "The stable branch doesn't contain any major bug, and is one major digit version behind the latest release. For example, the current latest release is v0.8.3 , the stable branch is an alias to the latest v0.7.x release. When the v0.9.0 version will be released, the stable will move to the latest v0.8.x release. Remarks: Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.",
+ "title": "stable branch"
+ },
+ {
+ "location": "/Versioning-and-Branches/#releases",
+ "text": "Releases are always made from the latest v0.x branch. Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.",
+ "title": "Releases"
+ },
+ {
+ "location": "/Versioning-and-Branches/#advices-on-3rd-party-git-repos-workflow",
+ "text": "",
+ "title": "Advices on 3rd party git repos workflow"
+ },
+ {
+ "location": "/Versioning-and-Branches/#versioning",
+ "text": "Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the changelog ( Draft means not released yet) and the commit log (like tpl folder for themes)). You can either: use the Shaarli version number, with your repo version. For example, if Shaarli v0.8.3 is released, publish a v0.8.3-1 release, where v0.8.3 states Shaarli compatibility and -1 is your own version digit for the current Shaarli version. use your own versioning scheme, and state Shaarli compatibility in the release description. Using this, any user will be able to pick the release matching his own Shaarli version.",
+ "title": "Versioning"
+ },
+ {
+ "location": "/Versioning-and-Branches/#major-bugfix-backport-releases",
+ "text": "To be able to support backported fixes, it recommended to use our workflow: # In master, fix the major bug\ngit commit -m \"Katastrophe\"\ngit push origin master\n# Get your commit hash\ngit log --format=\"%H\" -n 1\n# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)\ngit checkout -b katastrophe v0.8.2-1\n# Backport the fix commit to your brand new branch\ngit cherry-pick \ngit push origin katastrophe\n# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`",
+ "title": "Major bugfix backport releases"
+ },
+ {
+ "location": "/Security/",
+ "text": "Client browser\n\n\n\n\nShaarli relies on \nHTTP_REFERER\n for some functions (like redirects and clicking on tags). If you have disabled or masqueraded \nHTTP_REFERER\n in your browser, some features of Shaarli may not work\n\n\n\n\nPHP\n\n\n\n\nmagic_quotes\n is an 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 \nmagic_quotes\n on, so you should not be bothered even on crappy hosts.\n\n\n\n\nServer and sessions\n\n\n\n\nDirectories are protected using \n.htaccess\n files\n\n\nForms are protected against XSRF (Cross-site requests forgery):\n\n\nForms which act on data (save,delete\u2026) contain a token generated by the server.\n\n\nAny posted form which does not contain a valid token is rejected.\n\n\nAny token can only be used once.\n\n\nTokens are attached to the session and cannot be reused in another session.\n\n\nSessions automatically expire after 60 minutes.\n\n\nSessions are protected against hijacking: the session ID cannot be used from a different IP address.\n\n\n\n\nShaarli datastore and configuration\n\n\n\n\nThe 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.\n\n\nLinks are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a \n.php\n file.\n\n\nEven if the server does not support \n.htaccess\n files, the data file will still not be readable by URL.\n\n\nThe database looks like this:\n\n\n\n\n\n\n\n\n\n\n\nSmall hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg. \n20110923_150523\n) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only \nA-Z a-z 0-9 - _\n and \n@\n.",
+ "title": "Security"
+ },
+ {
+ "location": "/Security/#client-browser",
+ "text": "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",
+ "title": "Client browser"
+ },
+ {
+ "location": "/Security/#php",
+ "text": "magic_quotes is an 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.",
+ "title": "PHP"
+ },
+ {
+ "location": "/Security/#server-and-sessions",
+ "text": "Directories are protected using .htaccess files Forms are protected against XSRF (Cross-site requests forgery): Forms which act on data (save,delete\u2026) 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. Tokens are attached to the session and cannot be reused in another session. Sessions automatically expire after 60 minutes. Sessions are protected against hijacking: the session ID cannot be used from a different IP address.",
+ "title": "Server and sessions"
+ },
+ {
+ "location": "/Security/#shaarli-datastore-and-configuration",
+ "text": "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. Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a .php file. Even if the server does not support .htaccess files, the data file will still not be readable by URL. The database looks like this: 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 @ .",
+ "title": "Shaarli datastore and configuration"
+ },
+ {
+ "location": "/Static-analysis/",
+ "text": "WIP\n\n\nThis topic is currently being discussed here:\n- \nFix coding style (static analysis)\n (#95)\n- \nContinuous Integration tools & features\n (#130)\n\n\nUsage\n\n\nStatic analysis tools can be installed with Composer, and used through Shaarli's \nMakefile\n.\n\n\nFor an overview of the available features, see:\n- \nCode quality: Makefile to run static code checkers\n (#124)\n- \nRun PHPCS against different coding standards\n (#276)",
+ "title": "Static analysis"
+ },
+ {
+ "location": "/Static-analysis/#wip",
+ "text": "This topic is currently being discussed here:\n- Fix coding style (static analysis) (#95)\n- Continuous Integration tools & features (#130)",
+ "title": "WIP"
+ },
+ {
+ "location": "/Static-analysis/#usage",
+ "text": "Static analysis tools can be installed with Composer, and used through Shaarli's Makefile . For an overview of the available features, see:\n- Code quality: Makefile to run static code checkers (#124)\n- Run PHPCS against different coding standards (#276)",
+ "title": "Usage"
+ },
+ {
+ "location": "/Theming/",
+ "text": "Foreword\n\n\nThere are two ways of customizing how Shaarli looks:\n\n\n\n\nby using a custom CSS to override Shaarli's CSS\n\n\nby using a full theme that provides its own RainTPL templates, CSS and Javascript resources\n\n\n\n\nCustom CSS\n\n\nShaarli's appearance can be modified by adding CSS rules to:\n- Shaarli < \nv0.9.0\n: \ninc/user.css\n\n- Shaarli >= \nv0.9.0\n: \ndata/user.css\n\n\nThis file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.\n\n\nNote\n: Do not edit \ntpl/default/css/shaarli.css\n! Your changes would be overridden when updating Shaarli.\n\n\nSee also \nDownload CSS styles from an OPML list\n\n\nThemes\n\n\nWARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.\n\n\nInstallation:\n- find a theme you'd like to install\n- copy or clone the theme folder under \ntpl/\n\n- enable the theme:\n - Shaarli < \nv0.9.0\n: edit \ndata/config.json.php\n and set the value of \nraintpl_tpl\n to the new theme name:\n \n\"raintpl_tpl\": \"tpl\\/my-template\\/\"\n\n - Shaarli >= \nv0.9.0\n: select the theme through the \nTools\n page\n\n\nCommunity CSS & themes\n\n\nCustom CSS\n\n\n\n\nmrjovanovic/serious-theme-shaarli\n - A serious theme for Shaarli\n\n\nshaarli/shaarli-themes\n\n\n\n\nThemes\n\n\n\n\nAkibaTech/Shaarli Superhero Theme\n - A template/theme for Shaarli\n\n\nalexisju/albinomouse-template\n - A full template for Shaarli\n\n\nArthurHoaro/shaarli-launch\n - Customizable Shaarli theme\n\n\ndhoko/ShaarliTemplate\n - A template/theme for Shaarli\n\n\nkalvn/shaarli-blocks\n - A template/theme for Shaarli\n\n\nkalvn/Shaarli-Material\n - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone\n\n\nManufacturaInd/shaarli-2004licious-theme\n - A template/theme as a humble homage to the early looks of the del.icio.us site\n\n\n\n\nShaarli forks\n\n\n\n\nmisterair/Limonade\n - A fork of (legacy) Shaarli with a new template\n\n\nvivienhaese/shaarlitheme\n - A Shaarli fork meant to be run in an openshift instance\n\n\n\n\nExample installation: AlbinoMouse theme\n\n\nWith the following configuration:\n- Apache 2 / PHP 5.6\n- user sites are enabled, e.g. \n/home/user/public_html/somedir\n is served as \nhttp://localhost/~user/somedir\n\n- \nhttp\n is the name of the Apache user\n\n\n$ cd ~/public_html\n\n# clone repositories\n$ git clone https://github.com/shaarli/Shaarli.git shaarli\n$ pushd shaarli/tpl\n$ git clone https://github.com/alexisju/albinomouse-template.git\n$ popd\n\n# set access rights for Apache\n$ chgrp -R http shaarli\n$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp\n\n\n\n\nGet config written:\n- go to the freshly installed site\n- fill the install form\n- log in to Shaarli\n\n\nEdit Shaarli's \nconfiguration|Shaarli configuration\n:\n\n\n# the file should be owned by Apache, thus not writeable => sudo\n$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php",
+ "title": "Theming"
+ },
+ {
+ "location": "/Theming/#foreword",
+ "text": "There are two ways of customizing how Shaarli looks: by using a custom CSS to override Shaarli's CSS by using a full theme that provides its own RainTPL templates, CSS and Javascript resources",
+ "title": "Foreword"
+ },
+ {
+ "location": "/Theming/#custom-css",
+ "text": "Shaarli's appearance can be modified by adding CSS rules to:\n- Shaarli < v0.9.0 : inc/user.css \n- Shaarli >= v0.9.0 : data/user.css This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme. Note : Do not edit tpl/default/css/shaarli.css ! Your changes would be overridden when updating Shaarli. See also Download CSS styles from an OPML list",
+ "title": "Custom CSS"
+ },
+ {
+ "location": "/Theming/#themes",
+ "text": "WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental. Installation:\n- find a theme you'd like to install\n- copy or clone the theme folder under tpl/ \n- enable the theme:\n - Shaarli < v0.9.0 : edit data/config.json.php and set the value of raintpl_tpl to the new theme name:\n \"raintpl_tpl\": \"tpl\\/my-template\\/\" \n - Shaarli >= v0.9.0 : select the theme through the Tools page",
+ "title": "Themes"
+ },
+ {
+ "location": "/Theming/#community-css-themes",
+ "text": "",
+ "title": "Community CSS & themes"
+ },
+ {
+ "location": "/Theming/#custom-css_1",
+ "text": "mrjovanovic/serious-theme-shaarli - A serious theme for Shaarli shaarli/shaarli-themes",
+ "title": "Custom CSS"
+ },
+ {
+ "location": "/Theming/#themes_1",
+ "text": "AkibaTech/Shaarli Superhero Theme - A template/theme for Shaarli alexisju/albinomouse-template - A full template for Shaarli ArthurHoaro/shaarli-launch - Customizable Shaarli theme dhoko/ShaarliTemplate - A template/theme for Shaarli kalvn/shaarli-blocks - A template/theme for Shaarli kalvn/Shaarli-Material - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone ManufacturaInd/shaarli-2004licious-theme - A template/theme as a humble homage to the early looks of the del.icio.us site",
+ "title": "Themes"
+ },
+ {
+ "location": "/Theming/#shaarli-forks",
+ "text": "misterair/Limonade - A fork of (legacy) Shaarli with a new template vivienhaese/shaarlitheme - A Shaarli fork meant to be run in an openshift instance",
+ "title": "Shaarli forks"
+ },
+ {
+ "location": "/Theming/#example-installation-albinomouse-theme",
+ "text": "With the following configuration:\n- Apache 2 / PHP 5.6\n- user sites are enabled, e.g. /home/user/public_html/somedir is served as http://localhost/~user/somedir \n- http is the name of the Apache user $ cd ~/public_html\n\n# clone repositories\n$ git clone https://github.com/shaarli/Shaarli.git shaarli\n$ pushd shaarli/tpl\n$ git clone https://github.com/alexisju/albinomouse-template.git\n$ popd\n\n# set access rights for Apache\n$ chgrp -R http shaarli\n$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp Get config written:\n- go to the freshly installed site\n- fill the install form\n- log in to Shaarli Edit Shaarli's configuration|Shaarli configuration : # the file should be owned by Apache, thus not writeable => sudo\n$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php",
+ "title": "Example installation: AlbinoMouse theme"
+ },
+ {
+ "location": "/Unit-tests/",
+ "text": "Setup your environment for tests\n\n\nThe framework used is \nPHPUnit\n; it can be installed with \nComposer\n, which is a dependency management tool.\n\n\nRegarding Composer, you can either use:\n\n a system-wide version, e.g. installed through your distro's package manager\n\n a local version, downloadable \nhere\n\n\nSample usage\n\n\n# system-wide version\n$ composer install\n$ composer update\n\n# local version\n$ php composer.phar self-update\n$ php composer.phar install\n$ php composer.phar update\n\n\n\n\nInstall Shaarli dev dependencies\n\n\n$ cd /path/to/shaarli\n$ composer update\n\n\n\n\nInstall and enable Xdebug to generate PHPUnit coverage reports\n\n\nFor Debian-based distros:\n\n\n$ aptitude install php5-xdebug\n\n\n\n\nFor ArchLinux:\n\n\n$ pacman -S xdebug\n\n\n\n\nThen add the following line to \n/etc/php/php.ini\n:\n\n\nzend_extension=xdebug.so\n\n\n\n\nRun unit tests\n\n\nSuccessful test suite:\n\n\n$ make test\n\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\n....................................\n\nTime: 759 ms, Memory: 8.25Mb\n\nOK (36 tests, 65 assertions)\n\n\n\n\nTest suite with failures and errors:\n\n\n$ make test\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\nE..FF...............................\n\nTime: 802 ms, Memory: 8.25Mb\n\nThere was 1 error:\n\n1) LinkDBTest::testConstructLoggedIn\nMissing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\\\nDBTest.php on line 79 and defined\n\n/home/virtualtam/public_html/shaarli/application/LinkDB.php:58\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79\n\n--\n\nThere were 2 failures:\n\n1) LinkDBTest::testCheckDBNew\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121\n\n2) LinkDBTest::testCheckDBLoad\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133\n\nFAILURES!\nTests: 36, Assertions: 63, Errors: 1, Failures: 2.\n\n\n\n\nTest results and coverage\n\n\nBy default, PHPUnit will run all suitable tests found under the \ntests\n directory.\n\n\nEach test has 3 possible outcomes:\n\n \n.\n - success\n\n \nF\n - failure: the test was run but its results are invalid\n * the code does not behave as expected\n * dependencies to external elements: globals, session, cache...\n* \nE\n - error: something went wrong and the tested code has crashed\n * typos in the code, or in the test code\n * dependencies to missing external elements\n\n\nIf Xdebug has been installed and activated, two coverage reports will be generated:\n\n a summary in the console\n\n a detailed HTML report with metrics for tested code\n * to open it in a web browser: \nfirefox coverage/index.html &\n\n\nExecuting specific tests\n\n\nAdd a \n@group\n annotation in a test class or method comment:\n\n\n/**\n * Netscape bookmark import\n * @group WIP\n */\nclass BookmarkImportTest extends PHPUnit_Framework_TestCase\n{\n [...]\n}\n\n\n\n\nTo run all tests annotated with \n@group WIP\n:\n\n\n$ vendor/bin/phpunit --group WIP tests/",
+ "title": "Unit tests"
+ },
+ {
+ "location": "/Unit-tests/#setup-your-environment-for-tests",
+ "text": "The framework used is PHPUnit ; it can be installed with Composer , which is a dependency management tool. Regarding Composer, you can either use: a system-wide version, e.g. installed through your distro's package manager a local version, downloadable here",
+ "title": "Setup your environment for tests"
+ },
+ {
+ "location": "/Unit-tests/#sample-usage",
+ "text": "# system-wide version\n$ composer install\n$ composer update\n\n# local version\n$ php composer.phar self-update\n$ php composer.phar install\n$ php composer.phar update",
+ "title": "Sample usage"
+ },
+ {
+ "location": "/Unit-tests/#install-shaarli-dev-dependencies",
+ "text": "$ cd /path/to/shaarli\n$ composer update",
+ "title": "Install Shaarli dev dependencies"
+ },
+ {
+ "location": "/Unit-tests/#install-and-enable-xdebug-to-generate-phpunit-coverage-reports",
+ "text": "For Debian-based distros: $ aptitude install php5-xdebug For ArchLinux: $ pacman -S xdebug Then add the following line to /etc/php/php.ini : zend_extension=xdebug.so",
+ "title": "Install and enable Xdebug to generate PHPUnit coverage reports"
+ },
+ {
+ "location": "/Unit-tests/#run-unit-tests",
+ "text": "Successful test suite: $ make test\n\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\n....................................\n\nTime: 759 ms, Memory: 8.25Mb\n\nOK (36 tests, 65 assertions) Test suite with failures and errors: $ make test\n-------\nPHPUNIT\n-------\nPHPUnit 4.6.9 by Sebastian Bergmann and contributors.\n\nConfiguration read from /home/virtualtam/public_html/shaarli/phpunit.xml\n\nE..FF...............................\n\nTime: 802 ms, Memory: 8.25Mb\n\nThere was 1 error:\n\n1) LinkDBTest::testConstructLoggedIn\nMissing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\\\nDBTest.php on line 79 and defined\n\n/home/virtualtam/public_html/shaarli/application/LinkDB.php:58\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79\n\n--\n\nThere were 2 failures:\n\n1) LinkDBTest::testCheckDBNew\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121\n\n2) LinkDBTest::testCheckDBLoad\nFailed asserting that two strings are equal.\n--- Expected\n+++ Actual\n@@ @@\n-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'\n+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'\n\n/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133\n\nFAILURES!\nTests: 36, Assertions: 63, Errors: 1, Failures: 2.",
+ "title": "Run unit tests"
+ },
+ {
+ "location": "/Unit-tests/#test-results-and-coverage",
+ "text": "By default, PHPUnit will run all suitable tests found under the tests directory. Each test has 3 possible outcomes: . - success F - failure: the test was run but its results are invalid\n * the code does not behave as expected\n * dependencies to external elements: globals, session, cache...\n* E - error: something went wrong and the tested code has crashed\n * typos in the code, or in the test code\n * dependencies to missing external elements If Xdebug has been installed and activated, two coverage reports will be generated: a summary in the console a detailed HTML report with metrics for tested code\n * to open it in a web browser: firefox coverage/index.html &",
+ "title": "Test results and coverage"
+ },
+ {
+ "location": "/Unit-tests/#executing-specific-tests",
+ "text": "Add a @group annotation in a test class or method comment: /**\n * Netscape bookmark import\n * @group WIP\n */\nclass BookmarkImportTest extends PHPUnit_Framework_TestCase\n{\n [...]\n} To run all tests annotated with @group WIP : $ vendor/bin/phpunit --group WIP tests/",
+ "title": "Executing specific tests"
+ },
+ {
+ "location": "/FAQ/",
+ "text": "Why did you create Shaarli ?\n\n\nI 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\u2026 oh\u2026 \ntheir Firefox addon sends to Diigo every single URL you visit\n (Don't believe me ? Use \nTamper Data\n and open any page).\n\n\nEnough 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.\n\n\nWhy use Shaarli and not Delicious/Diigo ?\n\n\nWith Shaarli:\n\n\n\n\nThe data is yours: It's hosted on your server.\n\n\nNever fear of having your data locked-in.\n\n\nNever fear to have your data sold to third party.\n\n\nYour private links are not hosted on a third party server.\n\n\nYou are not tracked by browser addons (like Diigo does)\n\n\nYou can change the look and feel of the pages if you want.\n\n\nYou can change the behaviour of the program.\n\n\nIt's magnitude faster than most bookmarking services.\n\n\n\n\nWhat does Shaarli mean?\n\n\nShaarli is for shaaring your links.\n\n\nMy Shaarli is broken!\n\n\nFirst of all, ensure that both the \nweb server\n and \nShaarli\n are correctly configured, and that your installation is \nsupported\n.\n\n\nIf everything looks right but the issue(s) remain(s), please:\n- take a look at the \ntroubleshooting\n section\n- come \nchat with us\n on Gitter, we'll be happy to help ;-)\n- browse active \nissues\n and \nPull Requests\n\n - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)\n - else, \nopen a new issue\n, and provide information about the problem:\n - \nwhat happens?\n - display glitches, invalid data, security flaws...\n - \nwhat is your configuration?\n - OS, server version, activated extensions, web browser...\n - \nis it reproducible?\n\n\nWhy not use a real database? Files are slow!\n\n\nDoes browsing \nthis page\n feel slow? Try browsing older pages, too.\n\n\nIt'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?\n\n\nThe 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.",
+ "title": "FAQ"
+ },
+ {
+ "location": "/FAQ/#why-did-you-create-shaarli",
+ "text": "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\u2026 oh\u2026 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.",
+ "title": "Why did you create Shaarli ?"
+ },
+ {
+ "location": "/FAQ/#why-use-shaarli-and-not-deliciousdiigo",
+ "text": "With Shaarli: The data is yours: It's hosted on your server. Never fear of having your data locked-in. Never fear to have your data sold to third party. Your private links are not hosted on a third party server. You are not tracked by browser addons (like Diigo does) You can change the look and feel of the pages if you want. You can change the behaviour of the program. It's magnitude faster than most bookmarking services.",
+ "title": "Why use Shaarli and not Delicious/Diigo ?"
+ },
+ {
+ "location": "/FAQ/#what-does-shaarli-mean",
+ "text": "Shaarli is for shaaring your links.",
+ "title": "What does Shaarli mean?"
+ },
+ {
+ "location": "/FAQ/#my-shaarli-is-broken",
+ "text": "First of all, ensure that both the web server and Shaarli are correctly configured, and that your installation is supported . If everything looks right but the issue(s) remain(s), please:\n- take a look at the troubleshooting section\n- come chat with us on Gitter, we'll be happy to help ;-)\n- browse active issues and Pull Requests \n - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)\n - else, open a new issue , and provide information about the problem:\n - what happens? - display glitches, invalid data, security flaws...\n - what is your configuration? - OS, server version, activated extensions, web browser...\n - is it reproducible?",
+ "title": "My Shaarli is broken!"
+ },
+ {
+ "location": "/FAQ/#why-not-use-a-real-database-files-are-slow",
+ "text": "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.",
+ "title": "Why not use a real database? Files are slow!"
+ },
+ {
+ "location": "/Community-&-Related-software/",
+ "text": "Unofficial but related 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.\n\n\nTODO: contact repos owners to see if they'd like to standardize their work with the community fork.\n\n\nCommunity\n\n\n\n\nLiens en vrac de sebsauvage\n - the original Shaarli\n\n\nA large list of Shaarlis\n\n\nA list of working Shaarli aggregators\n\n\nA list of some known Shaarlis\n\n\nAdieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net\n (fr) \n16/09/2011 - the original post about Shaarli\n\n\nOriginal ideas/fixme/TODO page\n\n\nOriginal discussion page\n (fr)\n\n\nOriginal revisions history\n\n\nShaarli.fr/my\n - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of \nDMeloni\n\n\n\n\nArticles and social media discussions\n\n\n\n\n2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176\n\n\n2015-08-15 - Reddit - \nQuestion about migrating from WordPress to Shaarli.\n\n\n2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366\n\n\n2015-05-12 - Reddit - \nshaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)\n\n\n\n\nThird party plugins\n\n\n\n\nautosave\n by \n@kalvn\n: Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.\n\n\nCode Coloration\n by \n@ArthurHoaro\n: client side code syntax highlighter.\n\n\nDisqus\n by \n@kalvn\n: Adds Disqus comment system to your Shaarli.\n\n\nemojione\n by \n@NerosTie\n: Add colorful emojis to your Shaarli.\n\n\ngoogle analytics\n by \n@ericjuden\n: Adds Google Analytics tracking support\n\n\nlaunch\n - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.\n\n\nrelated\n by \n@ilesinge\n - Show related links based on the number of identical tags.\n\n\nsocial\n by \n@alexisju\n: share links to social networks.\n\n\nshaarli2twitter\n by \n@ArthurHoaro\n - Automatically tweet your shared links from Shaarli\n\n\n\n\nThemes\n\n\nSee \nTheming\n for the list of community-contributed themes, and an installation guide.\n\n\nServer apps\n\n\n\n\nshaarchiver\n - Archive your Shaarli bookmarks and their content\n\n\nshaarli-river\n - An aggregator for shaarlis with many features \n\n\nShaarlo\n - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: \nshaarli.fr\n)\n\n\nShaarlimages\n - An image-oriented aggregator for Shaarlis\n\n\nmknexen/shaarli-api\n - A REST API for Shaarli\n\n\nSelf dead link\n - Detect dead links on shaarli. This version use the database of shaarli. \nAnother version\n, can be used for other shaarli instances (but is more resource consuming).\n\n\nBookmark Archiver\n - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html. \n\n\n\n\nMobile Apps\n\n\n\n\nShaarliOS\n iOS share extension - see \n#308\n for some promo codes,\n\n\nShaarli for Android\n - Android application that adds Shaarli as a sharing provider\n\n\nShaarlier for Android\n - Android application to simply add links directly into your Shaarli\n\n\n\n\nIntegration with other platforms\n\n\n\n\ntt-rss-shaarli\n - \nTiny-Tiny RSS\n plugin that adds support for sharing articles with Shaarli\n\n\noctopress-shaarli\n - Octopress plugin to retrieve Shaarli links on the sidebar\n\n\nScuttle to Shaarli\n - Import bookmarks from Scuttle\n\n\n\n\nAlternatives to Shaarli\n\n\nSee the \nbookmarks & link sharing\n section on \nawesome-selfhosted\n.",
+ "title": "Community & Related software"
+ },
+ {
+ "location": "/Community-&-Related-software/#community",
+ "text": "Liens en vrac de sebsauvage - the original Shaarli A large list of Shaarlis A list of working Shaarli aggregators A list of some known Shaarlis Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net (fr) 16/09/2011 - the original post about Shaarli Original ideas/fixme/TODO page Original discussion page (fr) Original revisions history Shaarli.fr/my - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of DMeloni",
+ "title": "Community"
+ },
+ {
+ "location": "/Community-&-Related-software/#articles-and-social-media-discussions",
+ "text": "2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176 2015-08-15 - Reddit - Question about migrating from WordPress to Shaarli. 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366 2015-05-12 - Reddit - shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)",
+ "title": "Articles and social media discussions"
+ },
+ {
+ "location": "/Community-&-Related-software/#third-party-plugins",
+ "text": "autosave by @kalvn : Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown. Code Coloration by @ArthurHoaro : client side code syntax highlighter. Disqus by @kalvn : Adds Disqus comment system to your Shaarli. emojione by @NerosTie : Add colorful emojis to your Shaarli. google analytics by @ericjuden : Adds Google Analytics tracking support launch - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli. related by @ilesinge - Show related links based on the number of identical tags. social by @alexisju : share links to social networks. shaarli2twitter by @ArthurHoaro - Automatically tweet your shared links from Shaarli",
+ "title": "Third party plugins"
+ },
+ {
+ "location": "/Community-&-Related-software/#themes",
+ "text": "See Theming for the list of community-contributed themes, and an installation guide.",
+ "title": "Themes"
+ },
+ {
+ "location": "/Community-&-Related-software/#server-apps",
+ "text": "shaarchiver - Archive your Shaarli bookmarks and their content shaarli-river - An aggregator for shaarlis with many features Shaarlo - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: shaarli.fr ) Shaarlimages - An image-oriented aggregator for Shaarlis mknexen/shaarli-api - A REST API for Shaarli Self dead link - Detect dead links on shaarli. This version use the database of shaarli. Another version , can be used for other shaarli instances (but is more resource consuming). Bookmark Archiver - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.",
+ "title": "Server apps"
+ },
+ {
+ "location": "/Community-&-Related-software/#mobile-apps",
+ "text": "ShaarliOS iOS share extension - see #308 for some promo codes, Shaarli for Android - Android application that adds Shaarli as a sharing provider Shaarlier for Android - Android application to simply add links directly into your Shaarli",
+ "title": "Mobile Apps"
+ },
+ {
+ "location": "/Community-&-Related-software/#integration-with-other-platforms",
+ "text": "tt-rss-shaarli - Tiny-Tiny RSS plugin that adds support for sharing articles with Shaarli octopress-shaarli - Octopress plugin to retrieve Shaarli links on the sidebar Scuttle to Shaarli - Import bookmarks from Scuttle",
+ "title": "Integration with other platforms"
+ },
+ {
+ "location": "/Community-&-Related-software/#alternatives-to-shaarli",
+ "text": "See the bookmarks & link sharing section on awesome-selfhosted .",
+ "title": "Alternatives to Shaarli"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/doc/html/search.html b/doc/html/search.html
new file mode 100644
index 00000000..b492b8bd
--- /dev/null
+++ b/doc/html/search.html
@@ -0,0 +1,324 @@
+
+
+
+
+
+
+
+
+
+
+ Shaarli Documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/html/sitemap.xml b/doc/html/sitemap.xml
new file mode 100644
index 00000000..534f02b5
--- /dev/null
+++ b/doc/html/sitemap.xml
@@ -0,0 +1,266 @@
+
+
+
+
+
+ /
+ 2017-06-18
+ daily
+
+
+
+
+
+
+ /Download-and-Installation/
+ 2017-06-18
+ daily
+
+
+
+ /Upgrade-and-migration/
+ 2017-06-18
+ daily
+
+
+
+ /Server-requirements/
+ 2017-06-18
+ daily
+
+
+
+ /Server-configuration/
+ 2017-06-18
+ daily
+
+
+
+ /Server-security/
+ 2017-06-18
+ daily
+
+
+
+ /Shaarli-configuration/
+ 2017-06-18
+ daily
+
+
+
+ /Plugins/
+ 2017-06-18
+ daily
+
+
+
+
+
+
+
+ /Docker-101/
+ 2017-06-18
+ daily
+
+
+
+ /Shaarli-images/
+ 2017-06-18
+ daily
+
+
+
+ /Reverse-proxy-configuration/
+ 2017-06-18
+ daily
+
+
+
+ /Docker-resources/
+ 2017-06-18
+ daily
+
+
+
+
+
+
+
+ /Features/
+ 2017-06-18
+ daily
+
+
+
+ /Bookmarklet/
+ 2017-06-18
+ daily
+
+
+
+ /Browsing-and-searching/
+ 2017-06-18
+ daily
+
+
+
+ /Firefox-share/
+ 2017-06-18
+ daily
+
+
+
+ /RSS-feeds/
+ 2017-06-18
+ daily
+
+
+
+ /REST-API/
+ 2017-06-18
+ daily
+
+
+
+
+
+
+
+ /Backup,-restore,-import-and-export/
+ 2017-06-18
+ daily
+
+
+
+ /Copy-an-existing-installation-over-SSH-and-serve-it-locally/
+ 2017-06-18
+ daily
+
+
+
+ /Create-and-serve-multiple-Shaarlis-(farm)/
+ 2017-06-18
+ daily
+
+
+
+ /Download-CSS-styles-from-an-OPML-list/
+ 2017-06-18
+ daily
+
+
+
+ /Datastore-hacks/
+ 2017-06-18
+ daily
+
+
+
+
+
+
+ /Troubleshooting/
+ 2017-06-18
+ daily
+
+
+
+
+
+
+ /Development-guidelines/
+ 2017-06-18
+ daily
+
+
+
+ /Continuous-integration-tools/
+ 2017-06-18
+ daily
+
+
+
+ /GnuPG-signature/
+ 2017-06-18
+ daily
+
+
+
+ /Coding-guidelines/
+ 2017-06-18
+ daily
+
+
+
+ /Directory-structure/
+ 2017-06-18
+ daily
+
+
+
+ /3rd-party-libraries/
+ 2017-06-18
+ daily
+
+
+
+ /Plugin-System/
+ 2017-06-18
+ daily
+
+
+
+ /Release-Shaarli/
+ 2017-06-18
+ daily
+
+
+
+ /Versioning-and-Branches/
+ 2017-06-18
+ daily
+
+
+
+ /Security/
+ 2017-06-18
+ daily
+
+
+
+ /Static-analysis/
+ 2017-06-18
+ daily
+
+
+
+ /Theming/
+ 2017-06-18
+ daily
+
+
+
+ /Unit-tests/
+ 2017-06-18
+ daily
+
+
+
+
+
+
+
+ /FAQ/
+ 2017-06-18
+ daily
+
+
+
+ /Community-&-Related-software/
+ 2017-06-18
+ daily
+
+
+
+
+
\ No newline at end of file
diff --git a/doc/3rd-party-libraries.md b/doc/md/3rd-party-libraries.md
similarity index 73%
rename from doc/3rd-party-libraries.md
rename to doc/md/3rd-party-libraries.md
index e6370549..ebab7a46 100644
--- a/doc/3rd-party-libraries.md
+++ b/doc/md/3rd-party-libraries.md
@@ -1,14 +1,13 @@
-#3rd party libraries
## CSS
-- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/)[](.html)
+- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/)
- resets default CSS properties for all HTML elements (overriding browsers' default values)
- ensures custom CSS stylessheets will provide the same results on all browsers
## Javascript
-- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms[](.html)
-- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails[](.html)
-- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation[](.html)
+- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
+- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
+- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
## PHP
-- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser[](.html)
-- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP[](.html)
+- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser
+- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP
diff --git a/doc/Backup,-restore,-import-and-export.md b/doc/md/Backup,-restore,-import-and-export.md
similarity index 87%
rename from doc/Backup,-restore,-import-and-export.md
rename to doc/md/Backup,-restore,-import-and-export.md
index 9f5598ef..d3252226 100644
--- a/doc/Backup,-restore,-import-and-export.md
+++ b/doc/md/Backup,-restore,-import-and-export.md
@@ -1,9 +1,8 @@
-#Backup, restore, import and export
- * [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)[](.html)
- * [Export links as...](#export-links-as)[](.html)
- * [Import links from...](#import-links-from)[](.html)
- * [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)[](.html)
+ * [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)
+ * [Export links as...](#export-links-as)
+ * [Import links from...](#import-links-from)
+ * [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)
----------------------
@@ -24,7 +23,7 @@ To export links as an HTML file, under _Tools > Export_, choose:
- _Export private_ to export private links only
Restore by using the `Import` feature.
-* This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.[](.html)
+* This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
Example command:
```bash
@@ -33,23 +32,21 @@ Example command:
## Import links from...
-
### Diigo
If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)
-
### Mister Wong
-See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.[](.html)
+See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.
### SemanticScuttle
-To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).[](.html)
+To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).
### Scuttle
-Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.[](.html)
+Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
## Import Shaarli links to Firefox
@@ -62,5 +59,5 @@ Your bookmarks will be imported in Firefox, ready to use, with tags and descript
You may be interested in these Firefox addons to manage links imported from Shaarli
- * [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks[](.html)
- * [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags[](.html)
+ * [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
+ * [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
diff --git a/doc/Sharing-button.md b/doc/md/Bookmarklet.md
similarity index 76%
rename from doc/Sharing-button.md
rename to doc/md/Bookmarklet.md
index e4388863..265ced44 100644
--- a/doc/Sharing-button.md
+++ b/doc/md/Bookmarklet.md
@@ -1,4 +1,3 @@
-#Sharing button
### Add the sharing button (_bookmarklet_) to your browser
* Open your Shaarli and `Login`
@@ -7,14 +6,14 @@
_This bookmarklet button is 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._
-.html)
+
### Share links using the _bookmarklet_
* When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
* A window opens.
* You can freely edit title, description, tags... to find it later using the text search or tag filtering.
- * You will be able to edit this link later using the -edit-button..html)
+ * You will be able to edit this link later using the  edit button.
* You can also check the “Private” box so that the link is saved but only visible to you.
* Click `Save`.**Voilà! Your link is now shared.**
@@ -22,7 +21,7 @@ _This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. U
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
-See [#196](https://github.com/shaarli/Shaarli#196).[](.html)
+See [#196](https://github.com/shaarli/Shaarli#196).
There is an open bug for both Firefox and Chromium:
diff --git a/doc/Browsing-and-searching.md b/doc/md/Browsing-and-searching.md
similarity index 83%
rename from doc/Browsing-and-searching.md
rename to doc/md/Browsing-and-searching.md
index 854b6b60..ad62c2f0 100644
--- a/doc/Browsing-and-searching.md
+++ b/doc/md/Browsing-and-searching.md
@@ -1,8 +1,3 @@
-#Browsing and searching
-# Browsing and Searching
-
-.html)
-
## Plain text search
Use the `Search text` field to search in _any_ of the fields of all links (Title, URL, Description...)
@@ -25,4 +20,4 @@ To search for links that are not tagged, enter `""` in the tag search field.
## Filtering RSS feeds/Picture wall
-RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS-feeds.html).
+RSS feeds can also be restricted to only return items matching a text/tag search: see [[RSS feeds]].
diff --git a/doc/Coding-guidelines.md b/doc/md/Coding-guidelines.md
similarity index 64%
rename from doc/Coding-guidelines.md
rename to doc/md/Coding-guidelines.md
index 1fb28a5b..da47c498 100644
--- a/doc/Coding-guidelines.md
+++ b/doc/md/Coding-guidelines.md
@@ -1,5 +1,5 @@
-#Coding guidelines
## WIP
+
This topic is currently being discussed here:
-- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)[](.html)
-- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)[](.html)
+- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
+- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
diff --git a/doc/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
similarity index 64%
rename from doc/Community-&-Related-software.md
rename to doc/md/Community-&-Related-software.md
index 52123a1e..6ff7ed45 100644
--- a/doc/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -1,61 +1,60 @@
-#Community & Related software
_Unofficial but related 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 with the community fork._
## Community
-- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli[](.html)
-- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)[](.html)
-- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)[](.html)
-- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)[](.html)
-- [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_[](.html)
-- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)[](.html)
-- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)[](.html)
-- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)[](.html)
-- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)[](.html)
+- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
+- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
+- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
+- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
+- [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_
+- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
+- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
+- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
+- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
### Articles and social media discussions
- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176
-- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)[](.html)
+- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)
- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366
-- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)[](.html)
+- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)
### Third party plugins
- * [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.[](.html)
- * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.[](.html)
- * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.[](.html)
- * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.[](.html)
- * [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support[](.html)
- * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.[](.html)
- * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.[](.html)
- * [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli[](.html)
+ * [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
+ * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
+ * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
+ * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
+ * [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
+ * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
+ * [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
+ * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
+ * [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
### Themes
-See [Theming](Theming.html) for the list of community-contributed themes, and an installation guide.
+See [[Theming]] for the list of community-contributed themes, and an installation guide.
### Server apps
-- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content[](.html)
-- [shaarli-river](https://github.com/mknexen/shaarli-river) - An aggregator for shaarlis with many features [](.html)
-- [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among french shaarliers: [shaarli.fr](http://shaarli.fr/))[](.html)
-- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis[](.html)
-- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli[](.html)
-- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).[](.html)
+- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
+- [shaarli-river](https://github.com/mknexen/shaarli-river) - An aggregator for shaarlis with many features
+- [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/))
+- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
+- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
+- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
+- [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
### Mobile Apps
-- [Shaarli💫](http://app.mro.name/Shaarli💫) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes,[](.html)
-- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider[](.html)
-- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli[](.html)
+- [ShaarliOS](https://github.com/mro/ShaarliOS) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes,
+- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
+- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
## Integration with other platforms
-- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [TinyTiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli[](.html)
-- [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar[](.html)
-- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle[](.html)
+- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
+- [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar
+- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle
## Alternatives to Shaarli
-- [Shaarli alternatives](http://alternativeto.net/software/shaarli/) (alternativeto.net)[](.html)
-- [Bookie](https://github.com/bookieio/bookie) - Another self-hostable, free bookmark sharing software, written in Python[](.html)
-- [Unmark](https://github.com/plainmade/unmark) - An open source todo app for bookmarks ([Homepage](https://unmark.it/))[](.html)
-- [Wordpress bookmarks](https://wordpress.org/plugins/wp-bookmarks/)[](.html)
+
+See the [bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing) section on [awesome-selfhosted](https://github.com/Kickball/awesome-selfhosted/).
diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md
new file mode 100644
index 00000000..30dc474d
--- /dev/null
+++ b/doc/md/Continuous-integration-tools.md
@@ -0,0 +1,24 @@
+## Local development
+A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
+- Documentation - generate a local HTML copy of the GitHub wiki
+- [[Static analysis]] - check that the code is compliant to PHP conventions
+- [[Unit tests]] - ensure there are no regressions introduced by new commits
+
+## Automatic builds
+[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
+- each time a commit is merged to the mainline (`master` branch)
+- each time a Pull Request is submitted or updated
+
+A build is composed of several jobs: one for each supported PHP version (see [[Server requirements]]).
+
+Each build job:
+- updates Composer
+- installs 3rd-party test dependencies with Composer
+- runs [[Unit tests]]
+
+After all jobs have finished, Travis returns the results to GitHub:
+- a status icon represents the result for the `master` branch: [](https://travis-ci.org/shaarli/Shaarli)
+- Pull Requests are updated with the Travis result
+ - Green: all tests have passed
+ - Red: some tests failed
+ - Orange: tests are pending
diff --git a/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.md b/doc/md/Copy-an-existing-installation-over-SSH-and-serve-it-locally.md
similarity index 88%
rename from doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.md
rename to doc/md/Copy-an-existing-installation-over-SSH-and-serve-it-locally.md
index 88d191da..7583c9ea 100644
--- a/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.md
+++ b/doc/md/Copy-an-existing-installation-over-SSH-and-serve-it-locally.md
@@ -1,4 +1,3 @@
-#Copy an existing installation over SSH and serve it locally
Example bash script:
```bash
@@ -61,7 +60,7 @@ Listening on http://localhost:7431
Document root is /home/user/local-shaarli/shaarli
Press Ctrl-C to quit.
-[Mon Sep 1 21:56:27 2014] ::1:57868 [200]: /[](.html)
-[Mon Sep 1 21:56:27 2014] ::1:57869 [200]: /index.html[](.html)
-[Mon Sep 1 21:56:37 2014] ::1:57881 [200]: /...[](.html)
+[Mon Sep 1 21:56:27 2014] ::1:57868 [200]: /
+[Mon Sep 1 21:56:27 2014] ::1:57869 [200]: /index.html
+[Mon Sep 1 21:56:37 2014] ::1:57881 [200]: /...
```
diff --git a/doc/Create-and-serve-multiple-Shaarlis-(farm).md b/doc/md/Create-and-serve-multiple-Shaarlis-(farm).md
similarity index 77%
rename from doc/Create-and-serve-multiple-Shaarlis-(farm).md
rename to doc/md/Create-and-serve-multiple-Shaarlis-(farm).md
index a71f6520..d0d812a3 100644
--- a/doc/Create-and-serve-multiple-Shaarlis-(farm).md
+++ b/doc/md/Create-and-serve-multiple-Shaarlis-(farm).md
@@ -1,4 +1,3 @@
-#Create and serve multiple Shaarlis (farm)
Example bash script (creates multiple shaarli instances and generates an HTML index of them)
```bash
@@ -13,12 +12,12 @@ shaarli_repo_url='https://github.com/shaarli/Shaarli'
ref="master"
#clone multiple shaarli instances
-if [ ! -d "$shaarli_base_dir" ]; then mkdir "$shaarli_base_dir"; fi[](.html)
+if [ ! -d "$shaarli_base_dir" ]; then mkdir "$shaarli_base_dir"; fi
for account in $accounts; do
- if [ -d "$shaarli_base_dir/$account" ];[](.html)
- then echo "[info] account $account already exists, skipping";[](.html)
- else echo "[info] creating new account $account ..."; git clone --quiet "$shaarli_repo_url" -b "$ref" "$shaarli_base_dir/$account"; fi[](.html)
+ if [ -d "$shaarli_base_dir/$account" ];
+ then echo "[info] account $account already exists, skipping";
+ else echo "[info] creating new account $account ..."; git clone --quiet "$shaarli_repo_url" -b "$ref" "$shaarli_base_dir/$account"; fi
done
#generate html index of shaarlis
@@ -46,13 +45,13 @@ htmlfooter='
for account in $accounts; do accountlinks="$accountlinks\n
"; done
-if [ -d "$shaarli_base_dir/index.html" ]; then echo "[removing old index.html]"; rm "$shaarli_base_dir/index.html" ]; fi[](.html)
-echo "[info] generating new index of shaarlis"[](.html)
+if [ -d "$shaarli_base_dir/index.html" ]; then echo "[removing old index.html]"; rm "$shaarli_base_dir/index.html" ]; fi
+echo "[info] generating new index of shaarlis"
echo -e "$htmlhead $accountlinks $htmlfooter" > "$shaarli_base_dir/index.html"
-echo '[info] done.'[](.html)
-echo "[info] list of accounts: $accounts"[](.html)
-echo "[info] contents of $shaarli_base_dir:"[](.html)
+echo '[info] done.'
+echo "[info] list of accounts: $accounts"
+echo "[info] contents of $shaarli_base_dir:"
tree -a -L 1 "$shaarli_base_dir"
```
-This script just serves as an example. More precise or complex (applying custom configuration, etc) automation is possible using configuration management software like [Ansible](https://www.ansible.com/)[](.html)
+This script just serves as an example. More precise or complex (applying custom configuration, etc) automation is possible using configuration management software like [Ansible](https://www.ansible.com/)
\ No newline at end of file
diff --git a/doc/Datastore-hacks.md b/doc/md/Datastore-hacks.md
similarity index 98%
rename from doc/Datastore-hacks.md
rename to doc/md/Datastore-hacks.md
index ef6f6d50..78baa005 100644
--- a/doc/Datastore-hacks.md
+++ b/doc/md/Datastore-hacks.md
@@ -1,5 +1,5 @@
-#Datastore hacks
### Decode datastore content
+
To display the array representing the data saved in `data/datastore.php`, use the following snippet:
```php
@@ -18,6 +18,7 @@ php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/
```
### Changing the timestamp for a link
+
* Look for `` in `tpl/editlink.tpl` (line 14)
* Replace `type="hidden"` with `type="text"` from this line
* A new date/time field becomes available in the edit/new link dialog.
diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md
new file mode 100644
index 00000000..1480ec89
--- /dev/null
+++ b/doc/md/Development-guidelines.md
@@ -0,0 +1,9 @@
+## Development guidelines
+
+Please have a look at the following pages:
+- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
+- [[Static analysis]] - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
+ - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
+ - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
+- [[Unit tests]]
+- [[GnuPG signature]] for tags/releases
diff --git a/doc/Directory-structure.md b/doc/md/Directory-structure.md
similarity index 98%
rename from doc/Directory-structure.md
rename to doc/md/Directory-structure.md
index 3a1c4309..eb50965b 100644
--- a/doc/Directory-structure.md
+++ b/doc/md/Directory-structure.md
@@ -1,4 +1,5 @@
-#Directory structure
+TODO: This page is out of date
+
Here is the directory structure of Shaarli and the purpose of the different files:
```bash
diff --git a/doc/md/Docker-101.md b/doc/md/Docker-101.md
new file mode 100644
index 00000000..b02dd149
--- /dev/null
+++ b/doc/md/Docker-101.md
@@ -0,0 +1,62 @@
+## Basics
+Install [Docker](https://www.docker.com/), by following the instructions relevant
+to your OS / distribution, and start the service.
+
+### Search an image on [DockerHub](https://hub.docker.com/)
+
+```bash
+$ docker search debian
+
+NAME DESCRIPTION STARS OFFICIAL AUTOMATED
+ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]
+debian Debian is a Linux distribution that's comp... 603 [OK]
+google/debian 47 [OK]
+```
+
+### Show available tags for a repository
+```bash
+$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
+
+% Total % Received % Xferd Average Speed Time Time Time Current
+Dload Upload Total Spent Left Speed
+100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
+```
+
+Sample output:
+```json
+[
+ {
+ "layer": "85a02782",
+ "name": "stretch"
+ },
+ {
+ "layer": "59abecbc",
+ "name": "testing"
+ },
+ {
+ "layer": "bf0fd686",
+ "name": "unstable"
+ },
+ {
+ "layer": "60c52dbe",
+ "name": "wheezy"
+ },
+ {
+ "layer": "c5b806fe",
+ "name": "wheezy-backports"
+ }
+]
+
+```
+
+### Pull an image from DockerHub
+```bash
+$ docker pull repository[:tag]
+
+$ docker pull debian:wheezy
+wheezy: Pulling from debian
+4c8cbfd2973e: Pull complete
+60c52dbe9d91: Pull complete
+Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
+Status: Downloaded newer image for debian:wheezy
+```
diff --git a/doc/md/Docker-resources.md b/doc/md/Docker-resources.md
new file mode 100644
index 00000000..082d4a46
--- /dev/null
+++ b/doc/md/Docker-resources.md
@@ -0,0 +1,19 @@
+### Docker
+
+- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
+- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)
+- [Dockerfile reference](https://docs.docker.com/reference/builder/)
+- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
+- [Volumes](https://docs.docker.com/userguide/dockervolumes/)
+
+### DockerHub
+
+- [Repositories](https://docs.docker.com/userguide/dockerrepos/)
+- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/)
+- [GitHub automated build](https://docs.docker.com/docker-hub/github/)
+
+### Service management
+
+- [Using supervisord](https://docs.docker.com/articles/using_supervisord/)
+- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
+- [supervisord](http://supervisord.org/)
diff --git a/doc/Download-CSS-styles-from-an-OPML-list.md b/doc/md/Download-CSS-styles-from-an-OPML-list.md
similarity index 92%
rename from doc/Download-CSS-styles-from-an-OPML-list.md
rename to doc/md/Download-CSS-styles-from-an-OPML-list.md
index eb66f955..26b7fb3e 100644
--- a/doc/Download-CSS-styles-from-an-OPML-list.md
+++ b/doc/md/Download-CSS-styles-from-an-OPML-list.md
@@ -1,4 +1,3 @@
-#Download CSS styles from an OPML list
###Download CSS styles for shaarlis listed in an opml file
Example php script:
@@ -34,8 +33,8 @@ function createShaarliHashFromOPMLL($opmlFile) {
$opmlXml = simplexml_load_string($opml);
$outlineElements = $opmlXml->xpath("body/outline");
foreach($outlineElements as $site) {
- $siteUrl = siteUrl((string) $site['htmlUrl']);[](.html)
- $result[$siteUrl]=((string) $site['text']);[](.html)
+ $siteUrl = siteUrl((string) $site['htmlUrl']);
+ $result[$siteUrl]=((string) $site['text']);
}
return $result;
}
@@ -47,7 +46,7 @@ function getSiteFolder($url) {
function get_http_response_code($theURL) {
$headers = get_headers($theURL);
- return substr($headers[0], 9, 3);[](.html)
+ return substr($headers[0], 9, 3);
}
/**
@@ -122,7 +121,7 @@ function getDirectoryList ($directory) {
while ($file = readdir($handler)) {
// if file isn't this directory or its parent, add it to the results
if ($file != "." && $file != "..") {
- $results[ = realpath($realPath . "/" . $file);](-=-realpath($realPath-.-"/"-.-$file);.html)
+ $results[] = realpath($realPath . "/" . $file);
}
}
// tidy up: close the handler
@@ -142,7 +141,7 @@ function findKnownStyles() {
$configFile = $folder."/config.ini";
if(file_exists($configFile)) {
$iniParameters = parse_ini_file($configFile);
- array_push($result, $iniParameters['site_url']);[](.html)
+ array_push($result, $iniParameters['site_url']);
}
}
return $result;
@@ -152,4 +151,4 @@ $knownStyles = findKnownStyles();
copyUserStylesFrom(createShaarliHashFromOPMLL(SHAARLI_RSS_OPML), $knownStyles);
-```
+```
\ No newline at end of file
diff --git a/doc/Download-and-Installation.md b/doc/md/Download-and-Installation.md
similarity index 88%
rename from doc/Download-and-Installation.md
rename to doc/md/Download-and-Installation.md
index 970144a5..7880aef4 100644
--- a/doc/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -1,7 +1,4 @@
-#Download and Installation
-# Get Shaarli!
-
-To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your [server](Server-requirements) is properly [configured](Server-configuration).[](.html)
+To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your [server](Server-requirements) is properly [configured](Server-configuration).
Several releases are available:
@@ -9,7 +6,7 @@ Several releases are available:
## Latest release (recommended)
### Download as an archive
-Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
+Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.
**Download our *shaarli-full* archive** to include dependencies.
@@ -23,7 +20,7 @@ $ unzip shaarli-v0.8.4-full.zip
$ mv Shaarli /path/to/shaarli/
```
-| ! |In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|[](.html)
+| ! |In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
|-----|--------------------------|
### Using git
@@ -60,7 +57,7 @@ $ mv Shaarli-stable /path/to/shaarli/
### Clone with Git
-[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.[](.html)
+[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.
```bash
$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
@@ -91,7 +88,7 @@ $ composer install --no-dev
Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
-[](.html)
+
Setup your Shaarli installation, and it's ready to use!
@@ -99,4 +96,4 @@ Setup your Shaarli installation, and it's ready to use!
## Updating Shaarli
-See [Upgrade and Migration](Upgrade-and-migration)[](.html)
+See [Upgrade and Migration](Upgrade-and-migration)
diff --git a/doc/Example-patch---add-new-via-field-for-links.md b/doc/md/Example-patch---add-new-via-field-for-links.md
similarity index 80%
rename from doc/Example-patch---add-new-via-field-for-links.md
rename to doc/md/Example-patch---add-new-via-field-for-links.md
index 883adf40..d84ef25a 100644
--- a/doc/Example-patch---add-new-via-field-for-links.md
+++ b/doc/md/Example-patch---add-new-via-field-for-links.md
@@ -1,4 +1,3 @@
-#Example patch add new via field for links
Example patch to add a new field ("via") for links, an input field to set the "via" property from the "edit link" dialog, and display the "via" field in the link list display. **Untested, use at your own risk**
Thanks to @Knah-Tsaeb in https://github.com/sebsauvage/Shaarli/pull/158
@@ -7,7 +6,7 @@ Thanks to @Knah-Tsaeb in https://github.com/sebsauvage/Shaarli/pull/158
From e0f363c18e8fe67990ed2bb1a08652e24e70bbcb Mon Sep 17 00:00:00 2001
From: Knah Tsaeb
Date: Fri, 11 Oct 2013 15:18:37 +0200
-Subject: [PATCH] Add a "via"/origin property for links, add new input in "edit link" dialog[](.html)
+Subject: [PATCH] Add a "via"/origin property for links, add new input in "edit link" dialog
Thanks to:
* https://github.com/Knah-Tsaeb/Shaarli/commit/040eb18ec8cdabd5ea855e108f81f97fbf0478c4
* https://github.com/Knah-Tsaeb/Shaarli/commit/4123658eae44d7564d1128ce52ddd5689efee813
@@ -23,27 +22,27 @@ diff --git a/index.php b/index.php
index 6fae2f8..53f798e 100644
--- a/index.php
+++ b/index.php
-@@ -436,6 +436,12 @@ if (isset($_POST['login']))[](.html)
+@@ -436,6 +436,12 @@ if (isset($_POST['login']))
// ------------------------------------------------------------------------------------------
// Misc utility functions:
+// Try to get just domain for @via
+function getJustDomain($url){
+ $parts = parse_url($url);
-+ return trim($parts['host']);[](.html)
++ return trim($parts['host']);
+ }
+
// Returns the server URL (including port and http/https), without path.
// e.g. "http://myserver.com:8080"
- // You can append $_SERVER['SCRIPT_NAME'] to get the current script URL.[](.html)
+ // You can append $_SERVER['SCRIPT_NAME'] to get the current script URL.
@@ -799,7 +805,8 @@ class linkdb implements Iterator, Countable, ArrayAccess
- $found= (strpos(strtolower($l['title']),$s)!==false)[](.html)
- || (strpos(strtolower($l['description']),$s)!==false)[](.html)
- || (strpos(strtolower($l['url']),$s)!==false)[](.html)
-- || (strpos(strtolower($l['tags']),$s)!==false);[](.html)
-+ || (strpos(strtolower($l['tags']),$s)!==false)[](.html)
-+ || (!empty($l['via']) && (strpos(strtolower($l['via']),$s)!==false));[](.html)
- if ($found) $filtered[$l['linkdate'[ = $l;](-=-$l;.html)
+ $found= (strpos(strtolower($l['title']),$s)!==false)
+ || (strpos(strtolower($l['description']),$s)!==false)
+ || (strpos(strtolower($l['url']),$s)!==false)
+- || (strpos(strtolower($l['tags']),$s)!==false);
++ || (strpos(strtolower($l['tags']),$s)!==false)
++ || (!empty($l['via']) && (strpos(strtolower($l['via']),$s)!==false));
+ if ($found) $filtered[$l['linkdate']] = $l;
}
krsort($filtered);
@@ -814,7 +821,7 @@ class linkdb implements Iterator, Countable, ArrayAccess
@@ -53,74 +52,74 @@ index 6fae2f8..53f798e 100644
- foreach($this->links as $l)
+ foreach($this-> links as $l)
{
- $linktags = explode(' ',($casesensitive?$l['tags']:strtolower($l['tags'])));[](.html)
+ $linktags = explode(' ',($casesensitive?$l['tags']:strtolower($l['tags'])));
if (count(array_intersect($linktags,$searchtags)) == count($searchtags))
@@ -905,7 +912,7 @@ function showRSS()
else $linksToDisplay = $LINKSDB;
$nblinksToDisplay = 50; // Number of links to display.
- if (!empty($_GET['nb'])) // In URL, you can specificy the number of links. Example: nb=200 or nb=all for all links.[](.html)
+ if (!empty($_GET['nb'])) // In URL, you can specificy the number of links. Example: nb=200 or nb=all for all links.
- {
+ {
- $nblinksToDisplay = $_GET['nb']=='all' ? count($linksToDisplay) : max($_GET['nb']+0,1) ;[](.html)
+ $nblinksToDisplay = $_GET['nb']=='all' ? count($linksToDisplay) : max($_GET['nb']+0,1) ;
}
@@ -944,7 +951,12 @@ function showRSS()
// If user wants permalinks first, put the final link in description
if ($usepermalinks===true) $descriptionlink = '(Link)';
- if (strlen($link['description'])>0) $descriptionlink = ' '.$descriptionlink;[](.html)
-- echo ''."\n\n";](>'."\n\n";.html)
-+ if(!empty($link['via'])){[](.html)
-+ $via = ' Origine => '.htmlspecialchars(getJustDomain($link['via'])).'';[](.html)
+ if (strlen($link['description'])>0) $descriptionlink = ' '.$descriptionlink;
+- echo ''."\n\n";
++ if(!empty($link['via'])){
++ $via = ' Origine => '.htmlspecialchars(getJustDomain($link['via'])).'';
+ } else {
+ $via = '';
+ }
-+ echo ''."\n\n";](>'."\n\n";.html)
++ echo ''."\n\n";
$i++;
}
echo '';
@@ -980,7 +992,7 @@ function showATOM()
else $linksToDisplay = $LINKSDB;
$nblinksToDisplay = 50; // Number of links to display.
- if (!empty($_GET['nb'])) // In URL, you can specificy the number of links. Example: nb=200 or nb=all for all links.[](.html)
+ if (!empty($_GET['nb'])) // In URL, you can specificy the number of links. Example: nb=200 or nb=all for all links.
- {
+ {
- $nblinksToDisplay = $_GET['nb']=='all' ? count($linksToDisplay) : max($_GET['nb']+0,1) ;[](.html)
+ $nblinksToDisplay = $_GET['nb']=='all' ? count($linksToDisplay) : max($_GET['nb']+0,1) ;
}
@@ -1006,11 +1018,16 @@ function showATOM()
// Add permalink in description
$descriptionlink = htmlspecialchars('(Permalink)');
-+ if(isset($link['via']) && !empty($link['via'])){[](.html)
-+ $via = htmlspecialchars(' Origine => '.getJustDomain($link['via']).'');[](.html)
++ if(isset($link['via']) && !empty($link['via'])){
++ $via = htmlspecialchars(' Origine => '.getJustDomain($link['via']).'');
+ } else {
+ $via = '';
+ }
// If user wants permalinks first, put the final link in description
if ($usepermalinks===true) $descriptionlink = htmlspecialchars('(Link)');
- if (strlen($link['description'])>0) $descriptionlink = '<br>'.$descriptionlink;[](.html)
+ if (strlen($link['description'])>0) $descriptionlink = '<br>'.$descriptionlink;
-- $entries.=''.htmlspecialchars(nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link['description']))))).$descriptionlink."\n";[](.html)
-+ $entries.=''.htmlspecialchars(nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link['description']))))).$descriptionlink.$via."\n";[](.html)
- if ($link['tags']!='') // Adding tags to each ATOM entry (as mentioned in ATOM specification)[](.html)
+- $entries.=''.htmlspecialchars(nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link['description']))))).$descriptionlink."\n";
++ $entries.=''.htmlspecialchars(nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link['description']))))).$descriptionlink.$via."\n";
+ if ($link['tags']!='') // Adding tags to each ATOM entry (as mentioned in ATOM specification)
{
- foreach(explode(' ',$link['tags']) as $tag)[](.html)
+ foreach(explode(' ',$link['tags']) as $tag)
@@ -1478,7 +1495,7 @@ function renderPage()
if (!startsWith($url,'http:') && !startsWith($url,'https:') && !startsWith($url,'ftp:') && !startsWith($url,'magnet:') && !startsWith($url,'?'))
$url = 'http://'.$url;
- $link = array('title'=>trim($_POST['lf_title']),'url'=>$url,'description'=>trim($_POST['lf_description']),'private'=>(isset($_POST['lf_private']) ? 1 : 0),[](.html)
+ $link = array('title'=>trim($_POST['lf_title']),'url'=>$url,'description'=>trim($_POST['lf_description']),'private'=>(isset($_POST['lf_private']) ? 1 : 0),
- 'linkdate'=>$linkdate,'tags'=>str_replace(',',' ',$tags));
-+ 'linkdate'=>$linkdate,'tags'=>str_replace(',',' ',$tags), 'via'=>trim($_POST['lf_via']));[](.html)
- if ($link['title']=='') $link['title']=$link['url']; // If title is empty, use the URL as title.[](.html)
- $LINKSDB[$linkdate] = $link;[](.html)
++ 'linkdate'=>$linkdate,'tags'=>str_replace(',',' ',$tags), 'via'=>trim($_POST['lf_via']));
+ if ($link['title']=='') $link['title']=$link['url']; // If title is empty, use the URL as title.
+ $LINKSDB[$linkdate] = $link;
$LINKSDB->savedb(); // Save to disk.
@@ -1556,7 +1573,8 @@ function renderPage()
- $title = (empty($_GET['title']) ? '' : $_GET['title'] ); // Get title if it was provided in URL (by the bookmarklet).[](.html)
- $description = (empty($_GET['description']) ? '' : $_GET['description']); // Get description if it was provided in URL (by the bookmarklet). [Bronco added that][](.html)
- $tags = (empty($_GET['tags']) ? '' : $_GET['tags'] ); // Get tags if it was provided in URL[](.html)
-- $private = (!empty($_GET['private']) && $_GET['private'] === "1" ? 1 : 0); // Get private if it was provided in URL [](.html)
-+ $via = (empty($_GET['via']) ? '' : $_GET['via'] );[](.html)
-+ $private = (!empty($_GET['private']) && $_GET['private'] === "1" ? 1 : 0); // Get private if it was provided in URL[](.html)
+ $title = (empty($_GET['title']) ? '' : $_GET['title'] ); // Get title if it was provided in URL (by the bookmarklet).
+ $description = (empty($_GET['description']) ? '' : $_GET['description']); // Get description if it was provided in URL (by the bookmarklet). [Bronco added that]
+ $tags = (empty($_GET['tags']) ? '' : $_GET['tags'] ); // Get tags if it was provided in URL
+- $private = (!empty($_GET['private']) && $_GET['private'] === "1" ? 1 : 0); // Get private if it was provided in URL
++ $via = (empty($_GET['via']) ? '' : $_GET['via'] );
++ $private = (!empty($_GET['private']) && $_GET['private'] === "1" ? 1 : 0); // Get private if it was provided in URL
if (($url!='') && parse_url($url,PHP_URL_SCHEME)=='') $url = 'http://'.$url;
// 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.)
if (empty($title) && parse_url($url,PHP_URL_SCHEME)=='http')
@@ -131,10 +130,10 @@ index 6fae2f8..53f798e 100644
-
+
// If found, extract encoding.
- if (!empty($meta[0]))[](.html)
+ if (!empty($meta[0]))
{
@@ -1577,7 +1595,7 @@ function renderPage()
- $html_charset = (!empty($enc[1])) ? strtolower($enc[1]) : 'utf-8';[](.html)
+ $html_charset = (!empty($enc[1])) ? strtolower($enc[1]) : 'utf-8';
}
else { $html_charset = 'utf-8'; }
-
@@ -152,13 +151,13 @@ index 6fae2f8..53f798e 100644
$PAGE = new pageBuilder;
@@ -1842,6 +1860,9 @@ function buildLinkList($PAGE,$LINKSDB)
- $taglist = explode(' ',$link['tags']);[](.html)
+ $taglist = explode(' ',$link['tags']);
uasort($taglist, 'strcasecmp');
- $link['taglist']=$taglist;[](.html)
-+ if(!empty($link['via'])){[](.html)
-+ $link['via']=htmlspecialchars($link['via']);[](.html)
+ $link['taglist']=$taglist;
++ if(!empty($link['via'])){
++ $link['via']=htmlspecialchars($link['via']);
+ }
- $linkDisp[$keys[$i[ = $link;](-=-$link;.html)
+ $linkDisp[$keys[$i]] = $link;
$i++;
}
diff --git a/tpl/editlink.html b/tpl/editlink.html
@@ -170,7 +169,7 @@ index 4a2c30c..14d4f9c 100644
Description
{/if}
- {if="!$GLOBALS['config'['HIDE_TIMESTAMPS'] || isLoggedIn()"}]('HIDE_TIMESTAMPS']-||-isLoggedIn()"}.html)
+ {if="!$GLOBALS['config']['HIDE_TIMESTAMPS'] || isLoggedIn()"}
{$value.localdate|htmlspecialchars} - permalink -
{else}
--
2.1.1
-```
+```
\ No newline at end of file
diff --git a/doc/FAQ.md b/doc/md/FAQ.md
similarity index 89%
rename from doc/FAQ.md
rename to doc/md/FAQ.md
index 4c69763f..151dcef5 100644
--- a/doc/FAQ.md
+++ b/doc/md/FAQ.md
@@ -1,7 +1,6 @@
-#FAQ
### 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](https://addons.mozilla.org/en-US/firefox/addon/tamper-data/) and open any page).[](.html)
+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](https://addons.mozilla.org/en-US/firefox/addon/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.
@@ -23,21 +22,21 @@ With Shaarli:
Shaarli is for shaaring your links.
### My Shaarli is broken!
-First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).[](.html)
+First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
If everything looks right but the issue(s) remain(s), please:
-- take a look at the [troubleshooting](Troubleshooting) section[](.html)
-- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)[](.html)
-- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)[](.html)
+- take a look at the [troubleshooting](Troubleshooting) section
+- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
+- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
- if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)
- - else, [open a new issue](https://github.com/shaarli/Shaarli/issues/new), and provide information about the problem:[](.html)
+ - else, [open a new issue](https://github.com/shaarli/Shaarli/issues/new), and provide information about the problem:
- _what happens?_ - display glitches, invalid data, security flaws...
- _what is your configuration?_ - OS, server version, activated extensions, web browser...
- _is it reproducible?_
### Why not use a real database? Files are slow!
-Does browsing [this page](http://sebsauvage.net/links/) feel slow? Try browsing older pages, too.[](.html)
+Does browsing [this page](http://sebsauvage.net/links/) 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?
diff --git a/doc/Usage.md b/doc/md/Features.md
similarity index 96%
rename from doc/Usage.md
rename to doc/md/Features.md
index 30ad1466..116b1c9c 100644
--- a/doc/Usage.md
+++ b/doc/md/Features.md
@@ -1,4 +1,3 @@
-#Usage
### Main features
Shaarli is intended:
* to share, comment and save interesting links and news
@@ -13,7 +12,7 @@ Shaarli is intended:
* to store playlists (e.g. with the `music` or `video` tags)
* to keep extracts/comments from webpages that may disappear
* to keep track of ongoing discussions (for example items tagged `discussion`)
- * [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags[](.html)
+ * [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
* to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
### Using Shaarli as a blog, notepad, pastebin...
diff --git a/doc/Firefox-share.md b/doc/md/Firefox-share.md
similarity index 86%
rename from doc/Firefox-share.md
rename to doc/md/Firefox-share.md
index 58adc58f..9ba57b04 100644
--- a/doc/Firefox-share.md
+++ b/doc/md/Firefox-share.md
@@ -1,4 +1,3 @@
-#Firefox share
### Add Shaarli as a sharing service to Firefox
* Open your Shaarli and `Login`
@@ -9,7 +8,7 @@
### Sharing links using Firefox share
* Add the sharing service as described above
- * When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png.html)
+ * When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [[images/firefoxshare.png]]
* You can edit your link before and after saving, just like the bookmarklet above.
| | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections. |
diff --git a/doc/GnuPG-signature.md b/doc/md/GnuPG-signature.md
similarity index 87%
rename from doc/GnuPG-signature.md
rename to doc/md/GnuPG-signature.md
index b0028d55..1fb3b42f 100644
--- a/doc/GnuPG-signature.md
+++ b/doc/md/GnuPG-signature.md
@@ -1,27 +1,26 @@
-#GnuPG signature
## Introduction
### PGP and GPG
-[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good [](.html)
+[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good
Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication,
signature and encryption.
-It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:[](.html)
-- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master [](.html)
+It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
+- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
Keys](https://www.archlinux.org/master-keys/)
-- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity[](.html)
+- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
### Trust
-To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/):[](.html)
+To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/):
> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
-Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:[](.html)
-- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)[](.html)
-- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)[](.html)
+Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:
+- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
+- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)
## Generate a GPG key
-- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)[](.html)
-- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)[](.html)
+- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)
+- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)
### gpg - provide identity information
```bash
@@ -62,7 +61,7 @@ gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
pub rsa2048/A9D53A3E 2015-07-31
Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
-uid [ultimate] Marvin the Paranoid Android [](.html)
+uid [ultimate] Marvin the Paranoid Android
sub rsa2048/8C0EACF1 2015-07-31
```
@@ -74,4 +73,4 @@ gpg: sending key A9D53A3E to hkp server pgp.mit.edu
## Create and push a GPG-signed tag
-See [Release Shaarli](Release-Shaarli.html).
+See [[Release Shaarli]].
diff --git a/doc/Plugin-System.md b/doc/md/Plugin-System.md
similarity index 88%
rename from doc/Plugin-System.md
rename to doc/md/Plugin-System.md
index addd792d..d55ffe7e 100644
--- a/doc/Plugin-System.md
+++ b/doc/md/Plugin-System.md
@@ -1,7 +1,6 @@
-#Plugin System
-[**I am a developer.** Developer API.](#developer-api)[](.html)
+[**I am a developer.** Developer API.](#developer-api)
-[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html)
+[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)
## Developer API
@@ -48,7 +47,7 @@ hook__($data, $conf)
Parameters:
- - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)[](.html)
+ - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
- conf: the `ConfigManager` instance.
For exemple, if my plugin want to add data to the header, this function is needed:
@@ -76,9 +75,9 @@ RainTPL displays every element contained in the placeholder's array. These eleme
For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
```php
-$data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
+$data['top_placeholder'][] = 'My content';
# OR
-array_push($data['top_placeholder'], 'My', 'content');[](.html)
+array_push($data['top_placeholder'], 'My', 'content');
return $data;
```
@@ -93,9 +92,9 @@ For exemple, in linklist, it is possible to alter every title:
```php
// mind the reference if you want $data to be altered
-foreach ($data['links'] as &$value) {[](.html)
+foreach ($data['links'] as &$value) {
// String reverse every title.
- $value['title'] = strrev($value['title']);[](.html)
+ $value['title'] = strrev($value['title']);
}
return $data;
@@ -117,25 +116,25 @@ Each file contain two keys:
Use `demo_plugin` as a functional example. It covers most of the plugin system features.
-If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).[](.html)
+If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
### Hooks
| Hooks | Description |
| ------------- |:-------------:|
-| [render_header](#render_header) | Allow plugin to add content in page headers. |[](.html)
-| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |[](.html)
-| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. | [](.html)
-| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |[](.html)
-| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html)
-| [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html)
-| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html)
-| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html)
-| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html)
-| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |[](.html)
-| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |[](.html)
-| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |[](.html)
-| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |[](.html)
+| [render_header](#render_header) | Allow plugin to add content in page headers. |
+| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
+| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
+| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |
+| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
+| [render_tools](#render_tools) | Allow to add content at the end of the page. |
+| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
+| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
+| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
+| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |
+| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
+| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
+| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
@@ -154,19 +153,19 @@ Allow plugin to add content in page headers.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
* `buttons_toolbar`: after the list of buttons in the header.
-[](.html)
+
* `fields_toolbar`: after search fields in the header.
> Note: This will only be called in linklist.
-[](.html)
+
#### render_includes
@@ -183,7 +182,7 @@ Allow plugin to include their own CSS files.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
@@ -206,14 +205,14 @@ Allow plugin to add content in page footer and include their own JS files.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
* `text`: called after the end of the footer text.
* `endofpage`: called at the end of the page.
-[](.html)
+
* `js_files`: called at the end of the page, to include custom JS scripts.
@@ -234,25 +233,25 @@ It allows to add content at the begining and end of the page, after every link d
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
* `action_plugin`: next to the button "private only" at the top and bottom of the page.
-[](.html)
+
* `link_plugin`: for every link, between permalink and link URL.
-[](.html)
+
* `plugin_start_zone`: before displaying the template content.
-[](.html)
+
* `plugin_end_zone`: after displaying the template content.
-[](.html)
+
#### render_editlink
@@ -268,13 +267,13 @@ Allow to add fields in the form, or display elements.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
* `edit_link_plugin`: after tags field.
-[](.html)
+
#### render_tools
@@ -290,13 +289,13 @@ Allow to add content at the end of the page.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
* `tools_plugin`: at the end of the page.
-[](.html)
+
#### render_picwall
@@ -313,7 +312,7 @@ Allow to add content at the top and bottom of the page.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
@@ -321,7 +320,7 @@ List of placeholders:
* `plugin_end_zone`: after displaying the template content.
-[](.html)
+
#### render_tagcloud
@@ -338,7 +337,7 @@ Allow to add content at the top and bottom of the page.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
@@ -350,7 +349,7 @@ For each tag, the following placeholder can be used:
* `tag_plugin`: after each tag
-[](.html)
+
#### render_taglist
@@ -368,7 +367,7 @@ Allow to add content at the top and bottom of the page.
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
@@ -395,13 +394,13 @@ Allow to add content at the top and bottom of the page, the bottom of each link
##### Template placeholders
-Items can be displayed in templates by adding an entry in `$data['']` array.[](.html)
+Items can be displayed in templates by adding an entry in `$data['']` array.
List of placeholders:
* `link_plugin`: used at bottom of each link.
-[](.html)
+
* `plugin_start_zone`: before displaying the template content.
@@ -423,7 +422,7 @@ Allow to add tags in the feed, either in the header or for each items. Items (li
##### Template placeholders
-Tags can be added in feeds by adding an entry in `$data['']` array.[](.html)
+Tags can be added in feeds by adding an entry in `$data['']` array.
List of placeholders:
diff --git a/doc/Plugins.md b/doc/md/Plugins.md
similarity index 86%
rename from doc/Plugins.md
rename to doc/md/Plugins.md
index e3192a60..b52b8090 100644
--- a/doc/Plugins.md
+++ b/doc/md/Plugins.md
@@ -1,4 +1,3 @@
-#Plugins
## Plugin installation
There is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them.
@@ -26,7 +25,7 @@ In Shaarli's administration page (`Tools` link), go to `Plugin administration`.
Here you can enable and disable all plugins available, and configure them.
-[](.html)
+
## Plugin order
@@ -41,14 +40,14 @@ This is important in case plugins are depending on each other. Read plugins READ
Enabled plugin are stored in your `config.php` parameters file, under the `array`:
```php
-$GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html)
+$GLOBALS['config']['ENABLED_PLUGINS']
```
You can edit them manually here.
Example:
```php
-$GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html)
+$GLOBALS['config']['ENABLED_PLUGINS'] = array(
'qrcode',
'archiveorg',
'wallabag',
@@ -64,13 +63,13 @@ Usage of each plugin is documented in it's README file:
* `addlink-toolbar`: Adds the addlink input on the linklist page
* `archiveorg`: For each link, add an Archive.org icon
- * [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.[](.html)
- * [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.[](.html)
+ * [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.
+ * [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.
* `qrcode`: For each link, add a QRCode icon.
- * [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.[](.html)
+ * [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.
#### Third party plugins
-See [Community & related software](https://github.com/shaarli/Shaarli/wiki/Community-%26-Related-software#third-party-plugins)[](.html)
+See [Community & related software](https://github.com/shaarli/Shaarli/wiki/Community-%26-Related-software#third-party-plugins)
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
new file mode 100644
index 00000000..8f3f7303
--- /dev/null
+++ b/doc/md/REST-API.md
@@ -0,0 +1,104 @@
+## Usage
+
+See the [REST API documentation](http://shaarli.github.io/api-documentation/).
+
+## Authentication
+
+All requests to Shaarli's API must include a JWT token to verify their authenticity.
+
+This token has to be included as an HTTP header called `Authentication: Bearer `.
+
+JWT resources :
+
+ * [jwt.io](https://jwt.io) (including a list of client per language).
+ * RFC : https://tools.ietf.org/html/rfc7519
+ * https://float-middle.com/json-web-tokens-jwt-vs-sessions/
+ * HackerNews thread: https://news.ycombinator.com/item?id=11929267
+
+
+### Shaarli JWT Token
+
+JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
+
+```
+[header].[payload].[signature]
+```
+
+#### Header
+
+Shaarli only allow one hash algorithm, so the header will always be the same:
+
+```json
+{
+ "typ": "JWT",
+ "alg": "HS512"
+}
+```
+
+Encoded in base64, it gives:
+
+```
+ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
+```
+
+#### Payload
+
+**Validity duration**
+
+To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes.
+
+```json
+{
+ "iat": 1468663519
+}
+```
+
+See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).
+
+
+#### Signature
+
+The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
+
+Signature example with PHP:
+
+```php
+$content = base64_encode($header) . '.' . base64_encode($payload);
+$signature = hash_hmac('sha512', $content, $secret);
+```
+
+
+### Complete example
+
+#### PHP
+
+```php
+function generateToken($secret) {
+ $header = base64_encode('{
+ "typ": "JWT",
+ "alg": "HS512"
+ }');
+ $payload = base64_encode('{
+ "iat": '. time() .'
+ }');
+ $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);
+ return $header .'.'. $payload .'.'. $signature;
+}
+
+$secret = 'mysecret';
+$token = generateToken($secret);
+echo $token;
+```
+
+> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68`
+
+```php
+$options = [
+ 'http' => [
+ 'method' => 'GET',
+ 'jwt' => $token,
+ ],
+];
+$context = stream_context_create($options);
+file_get_contents($apiEndpoint, false, $context);
+```
diff --git a/doc/RSS-feeds.md b/doc/md/RSS-feeds.md
similarity index 93%
rename from doc/RSS-feeds.md
rename to doc/md/RSS-feeds.md
index 757bed9a..9d718172 100644
--- a/doc/RSS-feeds.md
+++ b/doc/md/RSS-feeds.md
@@ -1,4 +1,3 @@
-#RSS feeds
### Feeds options
Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
@@ -24,4 +23,4 @@ For example, if you want to subscribe only to links tagged `photography`:
- `https://my.shaarli.domain/?do=rss&searchtags=nature`
- `https://my.shaarli.domain/links/?do=picwall&searchterm=poney`
--!.html)(images/rss-filter-2.png)
+ 
diff --git a/doc/Release-Shaarli.md b/doc/md/Release-Shaarli.md
similarity index 74%
rename from doc/Release-Shaarli.md
rename to doc/md/Release-Shaarli.md
index ced58853..cce5e209 100644
--- a/doc/Release-Shaarli.md
+++ b/doc/md/Release-Shaarli.md
@@ -1,5 +1,4 @@
-#Release Shaarli
-See [Git - Maintaining a project - Tagging your [](.html)
+See [Git - Maintaining a project - Tagging your
releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases).
## Prerequisites
@@ -13,13 +12,13 @@ This guide assumes that you have:
- maintainer permissions on the main Shaarli repository, to:
- push the signed tag
- create a new release
-- [Composer](https://getcomposer.org/) and [Pandoc](http://pandoc.org/) need to be installed[](.html)
+- [Composer](https://getcomposer.org/) and [Pandoc](http://pandoc.org/) need to be installed
## GitHub release draft and `CHANGELOG.md`
See http://keepachangelog.com/en/0.3.0/ for changelog formatting.
### GitHub release draft
-GitHub allows drafting the release note for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`.[](.html)
+GitHub allows drafting the release note for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`.
### `CHANGELOG.md`
This file should contain the same information as the release note draft for the upcoming version.
@@ -34,17 +33,17 @@ $ cd /path/to/shaarli
$ nano CHANGELOG.md
-[...][](.html)
+[...]
## vA.B.C - UNRELEASED
TBA
-## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD[](.html)
-[...][](.html)
+## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD
+[...]
```
-## Increment the version code, create and push a signed tag
-### Bump Shaarli's version
+## Increment the version code, updated docs, create and push a signed tag
+### Generate documentation
```bash
$ cd /path/to/shaarli
@@ -52,15 +51,12 @@ $ cd /path/to/shaarli
$ git fetch upstream
$ git checkout upstream/master -b v0.5.0
-# bump the version number
-$ vim index.php shaarli_version.php
-
# rebuild the documentation from the wiki
$ make htmldoc
# commit the changes
-$ git add index.php shaarli_version.php doc
-$ git commit -s -m "Bump version to v0.5.0"
+$ git add doc
+$ git commit -s -m "Generate documentation for v0.5.0"
# push the commit on your GitHub fork
$ git push origin v0.5.0
@@ -69,13 +65,33 @@ $ git push origin v0.5.0
### Create and merge a Pull Request
This one is pretty straightforward ;-)
-### Create and push a signed tag
-```bash
-# update your local copy
+### Bump Shaarli version to v0.x branch
+
+```
$ git checkout master
$ git fetch upstream
$ git pull upstream master
+# IF the branch doesn't exists
+$ git checkout -b v0.5
+# OR if the branch already exists
+$ git checkout v0.5
+$ git rebase upstream/master
+
+# Bump shaarli version from dev to 0.5.0, **without the `v`**
+$ vim shaarli_version.php
+$ git add shaarli_version
+$ git commit -s -m "Bump Shaarli version to v0.5.0"
+$ git push upstream v0.5
+```
+
+### Create and push a signed tag
+```bash
+# update your local copy
+$ git checkout v0.5
+$ git fetch upstream
+$ git pull upstream v0.5
+
# create a signed tag
$ git tag -s -m "Release v0.5.0" v0.5.0
@@ -84,7 +100,7 @@ $ git push --tags upstream
```
### Verify a signed tag
-[`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.[](.html)
+[`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.
Let's have a look at its signature!
@@ -99,12 +115,12 @@ f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
# verify the tag signature information
$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
-gpg: Good signature from "VirtualTam " [ultimate][](.html)
+gpg: Good signature from "VirtualTam " [ultimate]
```
## Publish the GitHub release
### Update release badges
-Update `README.md` so version badges display and point to the newly released Shaarli version(s).
+Update `README.md` so version badges display and point to the newly released Shaarli version(s), in the `master` branch.
### Create a GitHub release from a Git tag
From the previously drafted release:
@@ -120,7 +136,9 @@ Users with a shared hosting may have:
- no possibility to run scripts
To ease Shaarli installations, it is possible to generate and upload additional release archives,
-that will contain Shaarli code plus all required third-party libraries:
+that will contain Shaarli code plus all required third-party libraries.
+
+**From the `v0.5` branch:**
```bash
$ make release_archive
@@ -131,3 +149,20 @@ This will create the following archives:
- `shaarli-vX.Y.Z-full.zip`
The archives need to be manually uploaded on the previously created GitHub release.
+
+### Update `stable` and `latest` branches
+
+```
+$ git checkout latest
+# latest release
+$ git merge v0.5.0
+# fix eventual conflicts
+$ make test
+$ git push upstream latest
+$ git checkout stable
+# latest previous major
+$ git merge v0.4.5
+# fix eventual conflicts
+$ make test
+$ git push upstream stable
+```
diff --git a/doc/md/Reverse-proxy-configuration.md b/doc/md/Reverse-proxy-configuration.md
new file mode 100644
index 00000000..91ffecff
--- /dev/null
+++ b/doc/md/Reverse-proxy-configuration.md
@@ -0,0 +1,6 @@
+
+TODO, see https://github.com/shaarli/Shaarli/issues/888
+
+## HAProxy
+
+## Nginx
diff --git a/doc/Security.md b/doc/md/Security.md
similarity index 99%
rename from doc/Security.md
rename to doc/md/Security.md
index 7947460c..aec37fa0 100644
--- a/doc/Security.md
+++ b/doc/md/Security.md
@@ -1,4 +1,3 @@
-#Security
## Client browser
* 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
diff --git a/doc/Server-configuration.md b/doc/md/Server-configuration.md
similarity index 92%
rename from doc/Server-configuration.md
rename to doc/md/Server-configuration.md
index 81cc1a72..23fdbc8b 100644
--- a/doc/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -1,8 +1,7 @@
-#Server configuration
*Example virtual host configurations for popular web servers*
-- [Apache](#apache)[](.html)
-- [Nginx](#nginx)[](.html)
+- [Apache](#apache)
+- [Nginx](#nginx)
## Prerequisites
### Shaarli
@@ -14,8 +13,8 @@
### HTTPS, TLS and self-signed certificates
Related guides:
-* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)[](.html)
-* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)[](.html)
+* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
+* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
* Generate a self-signed certificate (will trigger browser warnings) with apache2: `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
### Proxies
@@ -24,7 +23,7 @@ If Shaarli is served behind a proxy (i.e. there is a proxy server between client
- `X-Forwarded-Host`;
- `X-Forwarded-For`.
-See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.[](.html)
+See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
## Apache
### Minimal
@@ -38,8 +37,8 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9
This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
See:
-* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)[](.html)
-* [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)[](.html)
+* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
+* [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
```apache
@@ -70,7 +69,7 @@ See:
```
### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
-See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).[](.html)
+See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).
```apache
@@ -106,7 +105,7 @@ See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
-**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.[](.html)
+**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.
Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
@@ -114,20 +113,20 @@ Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriti
## Nginx
### Foreword
-Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.[](.html)
+Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
Required packages:
-- [nginx](http://nginx.org)[](.html)
-- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)
+- [nginx](http://nginx.org)
+- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
Official documentation:
-- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)[](.html)
-- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)[](.html)
-- [Pitfalls](http://wiki.nginx.org/Pitfalls)[](.html)
+- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
+- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
+- [Pitfalls](http://wiki.nginx.org/Pitfalls)
Community resources:
-- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)[](.html)
-- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)[](.html)
+- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
+- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
### Common setup
Once Nginx and PHP-FPM are installed, we need to ensure:
@@ -154,7 +153,7 @@ which corresponds to the following service configuration:
user = john
group = users
-[...][](.html)
+[...]
listen.owner = john
listen.group = users
```
@@ -164,7 +163,7 @@ listen.group = users
user john users;
http {
- [...][](.html)
+ [...]
}
```
@@ -177,20 +176,20 @@ To increase upload size, you will need to modify both nginx and PHP configuratio
# /etc/nginx/nginx.conf
http {
- [...][](.html)
+ [...]
client_max_body_size 10m;
- [...][](.html)
+ [...]
}
```
```ini
# /etc/php5/fpm/php.ini
-[...][](.html)
+[...]
post_max_size = 10M
-[...][](.html)
+[...]
upload_max_filesize = 10M
```
@@ -293,10 +292,10 @@ location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
```nginx
# /etc/nginx/nginx.conf
-[...][](.html)
+[...]
http {
- [...][](.html)
+ [...]
root /home/john/web;
access_log /var/log/nginx/access.log;
@@ -347,10 +346,10 @@ Assuming you have generated a (self-signed) key and certificate, and they are lo
```nginx
# /etc/nginx/nginx.conf
-[...][](.html)
+[...]
http {
- [...][](.html)
+ [...]
index index.html index.php;
diff --git a/doc/Server-requirements.md b/doc/md/Server-requirements.md
similarity index 73%
rename from doc/Server-requirements.md
rename to doc/md/Server-requirements.md
index 07e70ab3..b6bbd66a 100644
--- a/doc/Server-requirements.md
+++ b/doc/md/Server-requirements.md
@@ -1,11 +1,11 @@
-#Server requirements
## PHP
+
### Release information
-- [PHP: Supported versions](http://php.net/supported-versions.php)[](.html)
-- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_[](.html)
-- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)[](.html)
-- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)[](.html)
-- [PHP: Bugs](https://bugs.php.net/)[](.html)
+- [PHP: Supported versions](http://php.net/supported-versions.php)
+- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
+- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
+- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
+- [PHP: Bugs](https://bugs.php.net/)
### Supported versions
Version | Status | Shaarli compatibility
@@ -18,23 +18,23 @@ Version | Status | Shaarli compatibility
5.3 | EOL: 2014-08-14 | :white_check_mark: (up to Shaarli 0.8.x)
See also:
-- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)[](.html)
+- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
### Dependency management
-Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,[](.html)
+Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,
download and install third-party PHP dependencies.
Library | Required? | Usage
---|:---:|---
-[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files[](.html)
-[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin[](.html)
-[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API[](.html)
+[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files
+[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin
+[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API
### Extensions
Extension | Required? | Usage
---|:---:|---
-[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS[](.html)
-[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows | multibyte (Unicode) string support[](.html)
-[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing[](.html)
-[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)[](.html)
-[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way[](.html)
+[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
+[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows | multibyte (Unicode) string support
+[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
+[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
+[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
diff --git a/doc/Server-security.md b/doc/md/Server-security.md
similarity index 93%
rename from doc/Server-security.md
rename to doc/md/Server-security.md
index 50549a21..8df36f46 100644
--- a/doc/Server-security.md
+++ b/doc/md/Server-security.md
@@ -1,4 +1,3 @@
-#Server security
## php.ini
PHP settings are defined in:
- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
@@ -31,8 +30,8 @@ Additional .ini files parsed: /etc/php/conf.d/xdebug.ini
## fail2ban
`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
-- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)[](.html)
-- [Source code](https://github.com/fail2ban/fail2ban)[](.html)
+- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
+- [Source code](https://github.com/fail2ban/fail2ban)
### Read Shaarli logs to ban IPs
Example configuration:
@@ -41,7 +40,7 @@ Example configuration:
`/etc/fail2ban/jail.local`
```ini
-[shaarli-auth][](.html)
+[shaarli-auth]
enabled = true
port = https,http
filter = shaarli-auth
@@ -52,9 +51,9 @@ bantime = -1
`/etc/fail2ban/filter.d/shaarli-auth.conf`
```ini
-[INCLUDES][](.html)
+[INCLUDES]
before = common.conf
-[Definition][](.html)
+[Definition]
failregex = \s-\s\s-\sLogin failed for user.*$
ignoreregex =
```
diff --git a/doc/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
similarity index 90%
rename from doc/Shaarli-configuration.md
rename to doc/md/Shaarli-configuration.md
index 25647cb7..933f5245 100644
--- a/doc/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -1,13 +1,10 @@
-#Shaarli configuration
-# Shaarli configuration
-
## Foreword
**Do not edit configuration options in index.php! Your changes would be lost.**
Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
* it contains all settings in JSON format, and can be edited to customize values
-* it defines which [plugins](Plugin-System) are enabled[(.html)]((.html).html)
+* it defines which [plugins](Plugin-System) are enabled[](.html)
* its values override those defined in `index.php`
* it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
@@ -33,13 +30,13 @@ On a Linux distribution:
- to give it access to Shaarli, either:
- unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
- put users in the same group as the web server, and set the appropriate access rights
-- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[(.html)]((.html).html)
+- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html)
## Configuration
In `data/config.json.php`.
-See also [Plugin System](Plugin-System.html).[](.html)
+See also [Plugin System](Plugin-System.html).
### Credentials
@@ -54,7 +51,7 @@ See also [Plugin System](Plugin-System.html).[](.html)
**title**: Shaarli's instance title.
**header_link**: Link to the homepage.
**links_per_page**: Number of shaares displayed per page.
-**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). [](.html)
+**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
**enabled_plugins**: List of enabled plugins.
### Security
@@ -64,7 +61,8 @@ It might be useful if your IP adress often changes.
**ban_after**: Failed login attempts before being IP banned.
**ban_duration**: IP ban duration in seconds.
**open_shaarli**: Anyone can add a new link while logged out if enabled.
-**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
+**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
+**allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
### Resources
@@ -121,9 +119,14 @@ It might be useful if your IP adress often changes.
"ban_after": 4,
"session_protection_disabled": false,
"ban_duration": 1800,
- "trusted_proxies": [[](.html)
+ "trusted_proxies": [
"1.2.3.4",
"5.6.7.8"
+ ],
+ "allowed_protocols": [
+ "ftp",
+ "ftps",
+ "magnet"
]
},
"resources": {
@@ -148,7 +151,7 @@ It might be useful if your IP adress often changes.
"enable_localcache": true,
"check_updates_branch": "stable",
"check_updates_interval": 86400,
- "enabled_plugins": [[](.html)
+ "enabled_plugins": [
"markdown",
"wallabag",
"archiveorg"
@@ -168,7 +171,7 @@ It might be useful if your IP adress often changes.
"general": {
"header_link": "?",
"links_per_page": 20,
- "enabled_plugins": [[](.html)
+ "enabled_plugins": [
"markdown",
"wallabag"
],
@@ -207,6 +210,6 @@ It might be useful if your IP adress often changes.
## Additional configuration
The playvideos plugin may require that you adapt your server's
-[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) [](.html)
-configuration to work properly.[(.html)]((.html).html)
+[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
+configuration to work properly.[](.html)
diff --git a/doc/md/Shaarli-images.md b/doc/md/Shaarli-images.md
new file mode 100644
index 00000000..25f6cfdd
--- /dev/null
+++ b/doc/md/Shaarli-images.md
@@ -0,0 +1,72 @@
+## Get and run a Shaarli image
+
+### DockerHub repository
+The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/)
+repository.
+
+### Available image tags
+- `latest`: master branch (tarball release)
+- `stable`: stable branch (tarball release)
+- `dev`: master branch (Git clone)
+
+All images rely on:
+- [Debian 8 Jessie](https://hub.docker.com/_/debian/)
+- [PHP5-FPM](http://php-fpm.org/)
+- [Nginx](http://nginx.org/)
+
+### Download from DockerHub
+```bash
+$ docker pull shaarli/shaarli
+latest: Pulling from shaarli/shaarli
+32716d9fcddb: Pull complete
+84899d045435: Pull complete
+4b6ad7444763: Pull complete
+e0345ef7a3e0: Pull complete
+5c1dd344094f: Pull complete
+6422305a200b: Pull complete
+7d63f861dbef: Pull complete
+3eb97210645c: Pull complete
+869319d746ff: Already exists
+869319d746ff: Pulling fs layer
+902b87aaaec9: Already exists
+Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98
+Status: Downloaded newer image for shaarli/shaarli:latest
+```
+
+### Create and start a new container from the image
+```bash
+# map the host's :8000 port to the container's :80 port
+$ docker create -p 8000:80 shaarli/shaarli
+d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+
+# launch the container in the background
+$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
+
+# list active containers
+$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo
+```
+
+### Stop and destroy a container
+```bash
+$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
+backstabbing_galileo
+
+# check the container is stopped
+$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+
+# list ALL containers
+$ docker ps -a
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo
+
+# destroy the container
+$ docker rm backstabbing_galileo # let's put an end to these barbarian practices
+backstabbing_galileo
+
+$ docker ps -a
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+```
diff --git a/doc/Static-analysis.md b/doc/md/Static-analysis.md
similarity index 68%
rename from doc/Static-analysis.md
rename to doc/md/Static-analysis.md
index 5781e055..ee4f5978 100644
--- a/doc/Static-analysis.md
+++ b/doc/md/Static-analysis.md
@@ -1,12 +1,11 @@
-#Static analysis
## WIP
This topic is currently being discussed here:
-- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)[](.html)
-- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)[](.html)
+- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
+- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
### Usage
-Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).[](.html)
+Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
For an overview of the available features, see:
-- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)[](.html)
-- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)[](.html)
+- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
+- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)
diff --git a/doc/Theming.md b/doc/md/Theming.md
similarity index 79%
rename from doc/Theming.md
rename to doc/md/Theming.md
index 23877e5d..ae68db38 100644
--- a/doc/Theming.md
+++ b/doc/md/Theming.md
@@ -1,11 +1,12 @@
-#Theming
## Foreword
+
There are two ways of customizing how Shaarli looks:
1. by using a custom CSS to override Shaarli's CSS
2. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
## Custom CSS
+
Shaarli's appearance can be modified by adding CSS rules to:
- Shaarli < `v0.9.0`: `inc/user.css`
- Shaarli >= `v0.9.0`: `data/user.css`
@@ -14,9 +15,10 @@ This file allows overriding rules defined in the template CSS files (only add ch
**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli.
-See also [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html)
+See also [[Download CSS styles from an OPML list]]
## Themes
+
_WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._
Installation:
@@ -28,24 +30,29 @@ Installation:
- Shaarli >= `v0.9.0`: select the theme through the _Tools_ page
## Community CSS & themes
+
### Custom CSS
-- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli[](.html)
-- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)[](.html)
+
+- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli
+- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)
### Themes
-- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli[](.html)
-- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli[](.html)
-- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme[](.html)
-- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli[](.html)
-- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli[](.html)
-- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone[](.html)
-- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site[](.html)
+
+- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
+- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
+- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
+- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
+- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
+- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone
+- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site
### Shaarli forks
-- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template[](.html)
-- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance[](.html)
+
+- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
+- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
## Example installation: AlbinoMouse theme
+
With the following configuration:
- Apache 2 / PHP 5.6
- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
@@ -70,7 +77,7 @@ Get config written:
- fill the install form
- log in to Shaarli
-Edit Shaarli's [configuration|Shaarli configuration](configuration|Shaarli-configuration.html):
+Edit Shaarli's [[configuration|Shaarli configuration]]:
```bash
# the file should be owned by Apache, thus not writeable => sudo
$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
diff --git a/doc/Troubleshooting.md b/doc/md/Troubleshooting.md
similarity index 92%
rename from doc/Troubleshooting.md
rename to doc/md/Troubleshooting.md
index 8e30fce5..13005526 100644
--- a/doc/Troubleshooting.md
+++ b/doc/md/Troubleshooting.md
@@ -1,14 +1,18 @@
-#Troubleshooting
+# Troubleshooting
+
## Browser
+
### Redirection issues (HTTP Referer)
+
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
See:
-- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)[](.html)
-- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)[](.html)
-- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)[](.html)
+- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
+- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
+- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
### Firefox HTTP Referer options
+
HTTP settings are available by browsing `about:config`, here are the available settings and their values.
`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
@@ -33,6 +37,7 @@ HTTP settings are available by browsing `about:config`, here are the available s
- 2: scheme+host+port
### Firefox, localhost and redirections
+
`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
To solve this, assign a local domain to your host, e.g.
@@ -44,25 +49,31 @@ To solve this, assign a local domain to your host, e.g.
and browse Shaarli at http://localhost.lan/.
Related threads:
-- [What is localhost.localdomain for?](https://bbs.archlinux.org/viewtopic.php?id=156064)[](.html)
-- [Stop returning to the first page after editing a bookmark from another page](https://github.com/shaarli/Shaarli/issues/311)[](.html)
+- [What is localhost.localdomain for?](https://bbs.archlinux.org/viewtopic.php?id=156064)
+- [Stop returning to the first page after editing a bookmark from another page](https://github.com/shaarli/Shaarli/issues/311)
## Login
+
### 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.
## Hosting problems
+
### Old PHP versions
- * On **free.fr** : free.fr now support php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:[](.html)
+
+ * On **free.fr** : free.fr now support php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
```ini
@@ -72,7 +83,7 @@ php56 1
* If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
* On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
- * If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:[](.html)
+ * 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:
```php
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
@@ -84,24 +95,29 @@ php56 1
* On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : ``. To fix this, remove this message from `php-include/prepend.php`
### 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 sebsauvage.net :-( )
### 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:
* 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.
-* 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 !)[](.html)
+* 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 !)
* 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).
* Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
* You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
* If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
## 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](http://curl.haxx.se/rfc/cookie_spec.html)).[](.html)
+
+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](http://curl.haxx.se/rfc/cookie_spec.html)).
### pubsubhubbub support
-Download [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`]('PUBSUBHUB_URL']`-in-your-`config.php`.html)
+
+Download [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`
diff --git a/doc/Unit-tests.md b/doc/md/Unit-tests.md
similarity index 96%
rename from doc/Unit-tests.md
rename to doc/md/Unit-tests.md
index 0942ad38..19838721 100644
--- a/doc/Unit-tests.md
+++ b/doc/md/Unit-tests.md
@@ -1,13 +1,13 @@
-#Unit tests
-
### Setup your environment for tests
-The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.[](.html)
+
+The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
Regarding Composer, you can either use:
* a system-wide version, e.g. installed through your distro's package manager
-* a local version, downloadable [here](https://getcomposer.org/download/)[](.html)
+* a local version, downloadable [here](https://getcomposer.org/download/)
#### Sample usage
+
```bash
# system-wide version
$ composer install
@@ -20,12 +20,14 @@ $ php composer.phar update
```
#### Install Shaarli dev dependencies
+
```bash
$ cd /path/to/shaarli
$ composer update
```
#### Install and enable Xdebug to generate PHPUnit coverage reports
+
For Debian-based distros:
```bash
$ aptitude install php5-xdebug
@@ -41,6 +43,7 @@ zend_extension=xdebug.so
```
#### Run unit tests
+
Successful test suite:
```bash
$ make test
@@ -111,6 +114,7 @@ Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
```
#### Test results and coverage
+
By default, PHPUnit will run all suitable tests found under the `tests` directory.
Each test has 3 possible outcomes:
@@ -128,7 +132,8 @@ If Xdebug has been installed and activated, two coverage reports will be generat
* to open it in a web browser: `firefox coverage/index.html &`
### Executing specific tests
-Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:[](.html)
+
+Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
```php
/**
@@ -137,7 +142,7 @@ Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.htm
*/
class BookmarkImportTest extends PHPUnit_Framework_TestCase
{
- [...][](.html)
+ [...]
}
```
diff --git a/doc/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
similarity index 83%
rename from doc/Upgrade-and-migration.md
rename to doc/md/Upgrade-and-migration.md
index d36eb862..7348891f 100644
--- a/doc/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -1,5 +1,5 @@
-#Upgrade and migration
## Preparation
+
### Note your current version
If anything goes wrong, it's important for us to know which version you're upgrading from.
@@ -13,33 +13,37 @@ Shaarli stores all user data under the `data` directory:
- `data/ipbans.php` - banned IP addresses
- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
-See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources.
+See [[Shaarli configuration]] for more information about Shaarli resources.
It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
- users with SSH access: copy or archive the directory to a temporary location
- users with FTP access: download a local copy of your Shaarli installation using your favourite client
### Migrating data from a previous installation
+
As all user data is kept under `data`, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:
- backup the `data` directory
- install or update Shaarli:
- - fresh installation - see [Download and installation](Download-and-installation.html)
+ - fresh installation - see [[Download and installation]]
- update - see the following sections
- check or restore the `data` directory
## Recommended : Upgrading from release archives
-All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
-We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation.html) for `git` complete instructions.
+All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
+
+We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [[Download and installation]] for `git` complete instructions.
Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
-After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
+After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [[Shaarli configuration]] for more details).
## Upgrading with Git
+
### Updating a community Shaarli
-If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:[](.html)
+
+If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:
```bash
$ cd /path/to/shaarli
@@ -55,7 +59,7 @@ Fast-forward
3 files changed, 3 insertions(+), 1 deletion(-)
```
-Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
+Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
```bash
$ composer install --no-dev
@@ -67,18 +71,20 @@ Updating dependencies
```
### Migrating and upgrading from Sebsauvage's repository
-If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.[](.html)
+
+If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
The following guide assumes that:
-- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)[](.html)
+- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
- the default remote is named `origin` and points to Sebsauvage's repository
- the current branch is `master`
- - if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break
+ - if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break!
- the working copy is clean:
- no versioned file has been locally modified
- no untracked files are present
#### Step 0: show repository information
+
```bash
$ cd /path/to/shaarli
@@ -87,7 +93,7 @@ origin https://github.com/sebsauvage/Shaarli (fetch)
origin https://github.com/sebsauvage/Shaarli (push)
$ git branch -vv
-* master 029f75f [origin/master] Update README.md[](.html)
+* master 029f75f [origin/master] Update README.md
$ git status
On branch master
@@ -96,6 +102,7 @@ nothing to commit, working directory clean
```
#### Step 1: update Git remotes
+
```
$ git remote rename origin sebsauvage
$ git remote -v
@@ -111,11 +118,11 @@ remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
Resolving deltas: 100% (1899/1899), completed with 48 local objects.
From https://github.com/shaarli/Shaarli
- * [new branch] master -> origin/master[](.html)
- * [new branch] stable -> origin/stable[](.html)
-[...][](.html)
- * [new tag] v0.6.4 -> v0.6.4[](.html)
- * [new tag] v0.7.0 -> v0.7.0[](.html)
+ * [new branch] master -> origin/master
+ * [new branch] stable -> origin/stable
+[...]
+ * [new tag] v0.6.4 -> v0.6.4
+ * [new tag] v0.7.0 -> v0.7.0
```
#### Step 2: use the stable community branch
@@ -126,11 +133,11 @@ Branch stable set up to track remote branch stable from origin.
Switched to a new branch 'stable'
$ git branch -vv
- master 029f75f [sebsauvage/master] Update README.md[](.html)
-* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html)
+ master 029f75f [sebsauvage/master] Update README.md
+* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5
```
-Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
+Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
```bash
$ composer install --no-dev
@@ -162,7 +169,8 @@ Total 3317 (delta 2050), reused 3301 (delta 2034)to
```
#### Step 3: configuration
-After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
+
+After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [[Shaarli configuration]] for more details).
## Troubleshooting
diff --git a/doc/md/Versioning-and-Branches.md b/doc/md/Versioning-and-Branches.md
new file mode 100644
index 00000000..e1d998e0
--- /dev/null
+++ b/doc/md/Versioning-and-Branches.md
@@ -0,0 +1,75 @@
+**WORK IN PROGRESS**
+
+It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
+
+## `master` branch
+
+The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
+
+Remarks:
+
+ * This branch shouldn't be used for production as it isn't necessary stable.
+ * 3rd party aren't required to be compatible with the latest changes.
+ * Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
+ * The version in this branch is always `dev`.
+
+## `v0.x` branch
+
+This `v0.x` branch, points to the latest `v0.x.y` release.
+
+Explanation:
+
+When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
+
+In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch.
+
+This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
+
+## `latest` branch
+
+This branch point the latest release. It recommended to use it to get the latest tested changes.
+
+## `stable` branch
+
+The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release.
+
+For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release.
+
+Remarks:
+
+ * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
+
+## Releases
+
+Releases are always made from the latest `v0.x` branch.
+
+Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
+
+## Advices on 3rd party git repos workflow
+
+### Versioning
+
+Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:
+
+ - use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
+ - use your own versioning scheme, and state Shaarli compatibility in the release description.
+
+Using this, any user will be able to pick the release matching his own Shaarli version.
+
+### Major bugfix backport releases
+
+To be able to support backported fixes, it recommended to use our workflow:
+
+```bash
+# In master, fix the major bug
+git commit -m "Katastrophe"
+git push origin master
+# Get your commit hash
+git log --format="%H" -n 1
+# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
+git checkout -b katastrophe v0.8.2-1
+# Backport the fix commit to your brand new branch
+git cherry-pick
+git push origin katastrophe
+# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
+```
diff --git a/doc/_Footer.md b/doc/md/_Footer.md
similarity index 69%
rename from doc/_Footer.md
rename to doc/md/_Footer.md
index 50fa4f56..648b1298 100644
--- a/doc/_Footer.md
+++ b/doc/md/_Footer.md
@@ -1,2 +1 @@
-#_Footer
-_Shaarli, the personal, minimalist, super-fast, database-free bookmarking service_
+_Shaarli, the personal, minimalist, super-fast, database-free bookmarking service_
\ No newline at end of file
diff --git a/doc/md/_Sidebar.md b/doc/md/_Sidebar.md
new file mode 100644
index 00000000..fe0e4229
--- /dev/null
+++ b/doc/md/_Sidebar.md
@@ -0,0 +1,45 @@
+- [[Home]]
+- Setup
+ - [[Download and Installation]]
+ - [[Upgrade and migration]]
+ - [[Server requirements]]
+ - [[Server configuration]]
+ - [[Server security]]
+ - [[Shaarli configuration]]
+ - [[Plugins]]
+- Docker
+ - [[Docker 101]]
+ - [[Shaarli images]]
+ - [[Reverse proxy configuration]]
+ - [[Docker resources]]
+- Usage
+ - [[Features]]
+ - [[Bookmarklet]]
+ - [[Browsing and Searching]]
+ - [[Firefox share]]
+ - [[RSS feeds]]
+ - [[REST API]]
+- How To
+ - [[Backup, restore, import and export]]
+ - [[Copy an existing installation over SSH and serve it locally]]
+ - [[Create and serve multiple Shaarlis (farm)]]
+ - [[Download CSS styles from an OPML list]]
+ - [[Datastore hacks]]
+- [[Troubleshooting]]
+- Development:
+ - [[Development guidelines]]
+ - [[Continuous integration tools]]
+ - [[GnuPG signature]]
+ - [[Coding guidelines]]
+ - [[Directory structure]]
+ - [[3rd party libraries]]
+ - [[Plugin System]]
+ - [[Release Shaarli]]
+ - [[Versioning and Branches]]
+ - [[Security]]
+ - [[Static analysis]]
+ - [[Theming]]
+ - [[Unit tests]]
+- About
+ - [[FAQ]]
+ - [[Community & Related software]]
diff --git a/doc/md/config.json b/doc/md/config.json
new file mode 100644
index 00000000..cc4de307
--- /dev/null
+++ b/doc/md/config.json
@@ -0,0 +1,6 @@
+{
+ "useSideMenu": true,
+ "lineBreaks": "gfm",
+ "additionalFooterText": "",
+ "title": "Shaarli documentation"
+}
\ No newline at end of file
diff --git a/doc/md/github-markdown.css b/doc/md/github-markdown.css
new file mode 100644
index 00000000..581350ae
--- /dev/null
+++ b/doc/md/github-markdown.css
@@ -0,0 +1,287 @@
+#local-sidebar {
+ width: 230px;
+ float: right;
+ position: relative;
+ z-index: 4;
+ background-color: #fff;
+ border: 1px solid #e2e2e2;
+ border-radius: 3px;
+}
+
+body {
+ font-family: Helvetica, arial, sans-serif;
+ font-size: 14px;
+ line-height: 1.6;
+ padding-top: 10px;
+ padding-bottom: 10px;
+ background-color: white;
+ padding: 10px 20%; }
+
+body > *:first-child {
+ margin-top: 0 !important; }
+body > *:last-child {
+ margin-bottom: 0 !important; }
+
+a {
+ color: #4183C4; }
+a.absent {
+ color: #cc0000; }
+a.anchor {
+ display: block;
+ padding-left: 30px;
+ margin-left: -30px;
+ cursor: pointer;
+ position: absolute;
+ top: 0;
+ left: 0;
+ bottom: 0; }
+
+h1, h2, h3, h4, h5, h6 {
+ margin: 20px 0 10px;
+ padding: 0;
+ font-weight: bold;
+ -webkit-font-smoothing: antialiased;
+ cursor: text;
+ position: relative; }
+
+h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, h5:hover a.anchor, h6:hover a.anchor {
+ background: url("../../images/modules/styleguide/para.png") no-repeat 10px center;
+ text-decoration: none; }
+
+h1 tt, h1 code {
+ font-size: inherit; }
+
+h2 tt, h2 code {
+ font-size: inherit; }
+
+h3 tt, h3 code {
+ font-size: inherit; }
+
+h4 tt, h4 code {
+ font-size: inherit; }
+
+h5 tt, h5 code {
+ font-size: inherit; }
+
+h6 tt, h6 code {
+ font-size: inherit; }
+
+h1 {
+ font-size: 28px;
+ color: black; }
+
+h2 {
+ font-size: 24px;
+ border-bottom: 1px solid #cccccc;
+ color: black; }
+
+h3 {
+ font-size: 18px; }
+
+h4 {
+ font-size: 16px; }
+
+h5 {
+ font-size: 14px; }
+
+h6 {
+ color: #777777;
+ font-size: 14px; }
+
+p, blockquote, ol, dl, table, pre {
+ margin: 15px 0; }
+
+hr {
+ background: transparent url("../../images/modules/pulls/dirty-shade.png") repeat-x 0 0;
+ border: 0 none;
+ color: #cccccc;
+ height: 4px;
+ padding: 0; }
+
+body > h2:first-child {
+ margin-top: 0;
+ padding-top: 0; }
+body > h1:first-child {
+ margin-top: 0;
+ padding-top: 0; }
+ body > h1:first-child + h2 {
+ margin-top: 0;
+ padding-top: 0; }
+body > h3:first-child, body > h4:first-child, body > h5:first-child, body > h6:first-child {
+ margin-top: 0;
+ padding-top: 0; }
+
+a:first-child h1, a:first-child h2, a:first-child h3, a:first-child h4, a:first-child h5, a:first-child h6 {
+ margin-top: 0;
+ padding-top: 0; }
+
+h1 p, h2 p, h3 p, h4 p, h5 p, h6 p {
+ margin-top: 0; }
+
+li p.first {
+ display: inline-block; }
+
+ul, ol {
+ padding-left: 30px; }
+
+ul :first-child, ol :first-child {
+ margin-top: 0; }
+
+ul :last-child, ol :last-child {
+ margin-bottom: 0; }
+
+dl {
+ padding: 0; }
+ dl dt {
+ font-size: 14px;
+ font-weight: bold;
+ font-style: italic;
+ padding: 0;
+ margin: 15px 0 5px; }
+ dl dt:first-child {
+ padding: 0; }
+ dl dt > :first-child {
+ margin-top: 0; }
+ dl dt > :last-child {
+ margin-bottom: 0; }
+ dl dd {
+ margin: 0 0 15px;
+ padding: 0 15px; }
+ dl dd > :first-child {
+ margin-top: 0; }
+ dl dd > :last-child {
+ margin-bottom: 0; }
+
+blockquote {
+ border-left: 4px solid #dddddd;
+ padding: 0 15px;
+ color: #777777; }
+ blockquote > :first-child {
+ margin-top: 0; }
+ blockquote > :last-child {
+ margin-bottom: 0; }
+
+table {
+ padding: 0; }
+ table tr {
+ border-top: 1px solid #cccccc;
+ background-color: white;
+ margin: 0;
+ padding: 0; }
+ table tr:nth-child(2n) {
+ background-color: #f8f8f8; }
+ table tr th {
+ font-weight: bold;
+ border: 1px solid #cccccc;
+ text-align: left;
+ margin: 0;
+ padding: 6px 13px; }
+ table tr td {
+ border: 1px solid #cccccc;
+ text-align: left;
+ margin: 0;
+ padding: 6px 13px; }
+ table tr th :first-child, table tr td :first-child {
+ margin-top: 0; }
+ table tr th :last-child, table tr td :last-child {
+ margin-bottom: 0; }
+
+img {
+ max-width: 100%; }
+
+span.frame {
+ display: block;
+ overflow: hidden; }
+ span.frame > span {
+ border: 1px solid #dddddd;
+ display: block;
+ float: left;
+ overflow: hidden;
+ margin: 13px 0 0;
+ padding: 7px;
+ width: auto; }
+ span.frame span img {
+ display: block;
+ float: left; }
+ span.frame span span {
+ clear: both;
+ color: #333333;
+ display: block;
+ padding: 5px 0 0; }
+span.align-center {
+ display: block;
+ overflow: hidden;
+ clear: both; }
+ span.align-center > span {
+ display: block;
+ overflow: hidden;
+ margin: 13px auto 0;
+ text-align: center; }
+ span.align-center span img {
+ margin: 0 auto;
+ text-align: center; }
+span.align-right {
+ display: block;
+ overflow: hidden;
+ clear: both; }
+ span.align-right > span {
+ display: block;
+ overflow: hidden;
+ margin: 13px 0 0;
+ text-align: right; }
+ span.align-right span img {
+ margin: 0;
+ text-align: right; }
+span.float-left {
+ display: block;
+ margin-right: 13px;
+ overflow: hidden;
+ float: left; }
+ span.float-left span {
+ margin: 13px 0 0; }
+span.float-right {
+ display: block;
+ margin-left: 13px;
+ overflow: hidden;
+ float: right; }
+ span.float-right > span {
+ display: block;
+ overflow: hidden;
+ margin: 13px auto 0;
+ text-align: right; }
+
+code, tt {
+ margin: 0 2px;
+ padding: 0 5px;
+ white-space: nowrap;
+ border: 1px solid #eaeaea;
+ background-color: #f8f8f8;
+ border-radius: 3px; }
+
+pre code {
+ margin: 0;
+ padding: 0;
+ white-space: pre;
+ border: none;
+ background: transparent; }
+
+.highlight pre {
+ background-color: #f8f8f8;
+ border: 1px solid #cccccc;
+ font-size: 13px;
+ line-height: 19px;
+ overflow: auto;
+ padding: 6px 10px;
+ border-radius: 3px; }
+
+pre {
+ background-color: #f8f8f8;
+ border: 1px solid #cccccc;
+ font-size: 13px;
+ line-height: 19px;
+ overflow: auto;
+ padding: 6px 10px;
+ border-radius: 3px; }
+ pre code, pre tt {
+ background-color: transparent;
+ border: none; }
diff --git a/doc/md/images/bookmarklet.png b/doc/md/images/bookmarklet.png
new file mode 100644
index 00000000..0262578e
Binary files /dev/null and b/doc/md/images/bookmarklet.png differ
diff --git a/doc/md/images/doc-logo.png b/doc/md/images/doc-logo.png
new file mode 100644
index 00000000..3d8d1787
Binary files /dev/null and b/doc/md/images/doc-logo.png differ
diff --git a/doc/md/images/doc-logo.svg b/doc/md/images/doc-logo.svg
new file mode 100644
index 00000000..37fc6658
--- /dev/null
+++ b/doc/md/images/doc-logo.svg
@@ -0,0 +1,522 @@
+
+
diff --git a/doc/md/images/firefoxshare.png b/doc/md/images/firefoxshare.png
new file mode 100644
index 00000000..98c2fdd3
Binary files /dev/null and b/doc/md/images/firefoxshare.png differ
diff --git a/doc/md/images/rss-filter-1.png b/doc/md/images/rss-filter-1.png
new file mode 100644
index 00000000..d2a03f67
Binary files /dev/null and b/doc/md/images/rss-filter-1.png differ
diff --git a/doc/md/images/rss-filter-2.png b/doc/md/images/rss-filter-2.png
new file mode 100644
index 00000000..538b126e
Binary files /dev/null and b/doc/md/images/rss-filter-2.png differ
diff --git a/doc/Home.md b/doc/md/index.md
similarity index 89%
rename from doc/Home.md
rename to doc/md/index.md
index 38413f24..37a9c1fc 100644
--- a/doc/Home.md
+++ b/doc/md/index.md
@@ -1,14 +1,11 @@
-#Home
-# Shaarli wiki
-
-Welcome to the [Shaarli](https://github.com/shaarli/Shaarli/) wiki
+Welcome 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).[](.html)
+For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
-If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) ([archive](https://github.com/shaarli/Shaarli/issues/44)) or read the current [issues](https://github.com/shaarli/Shaarli/issues). If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).[](.html)
+If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) ([archive](https://github.com/shaarli/Shaarli/issues/44)) or read the current [issues](https://github.com/shaarli/Shaarli/issues). If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
-If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).[](.html)
+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).
_Note: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the `doc/` directory of your Shaarli installation._
diff --git a/doc/sidebar.html b/doc/sidebar.html
deleted file mode 100644
index 478840d1..00000000
--- a/doc/sidebar.html
+++ /dev/null
@@ -1,52 +0,0 @@
-
%5D(https://travis-ci.org/shaarli/Shaarli).html)
edit button.
