aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md')
-rw-r--r--doc/md/Backup,-restore,-import-and-export.md29
-rw-r--r--doc/md/Bookmarklet.md29
-rw-r--r--doc/md/Coding-guidelines.md5
-rw-r--r--doc/md/Community-&-Related-software.md18
-rw-r--r--doc/md/Continuous-integration-tools.md4
-rw-r--r--doc/md/Development-guidelines.md1
-rw-r--r--doc/md/Download-and-Installation.md39
-rw-r--r--doc/md/FAQ.md19
-rw-r--r--doc/md/Features.md39
-rw-r--r--doc/md/Firefox-share.md18
-rw-r--r--doc/md/GnuPG-signature.md8
-rw-r--r--doc/md/Plugin-System.md160
-rw-r--r--doc/md/Plugins.md6
-rw-r--r--doc/md/REST-API.md100
-rw-r--r--doc/md/RSS-feeds.md2
-rw-r--r--doc/md/Release-Shaarli.md27
-rw-r--r--doc/md/Security.md31
-rw-r--r--doc/md/Server-configuration.md42
-rw-r--r--doc/md/Server-requirements.md13
-rw-r--r--doc/md/Server-security.md5
-rw-r--r--doc/md/Shaarli-configuration.md82
-rw-r--r--doc/md/Static-analysis.md2
-rw-r--r--doc/md/Theming.md7
-rw-r--r--doc/md/Troubleshooting.md63
-rw-r--r--doc/md/Unit-tests.md27
-rw-r--r--doc/md/Upgrade-and-migration.md17
-rw-r--r--doc/md/Various-hacks.md16
-rw-r--r--doc/md/Versioning-and-Branches.md10
-rw-r--r--doc/md/index.md3
29 files changed, 445 insertions, 377 deletions
diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/Backup,-restore,-import-and-export.md
index d3252226..89724857 100644
--- a/doc/md/Backup,-restore,-import-and-export.md
+++ b/doc/md/Backup,-restore,-import-and-export.md
@@ -1,11 +1,3 @@
1
2 * [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)
3 * [Export links as...](#export-links-as)
4 * [Import links from...](#import-links-from)
5 * [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)
6
7----------------------
8
9## Backup and restore the datastore file 1## Backup and restore the datastore file
10 2
11Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place. 3Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place.
@@ -18,12 +10,14 @@ rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +
18## Export links as... 10## Export links as...
19 11
20To export links as an HTML file, under _Tools > Export_, choose: 12To export links as an HTML file, under _Tools > Export_, choose:
13
21- _Export all_ to export both public and private links 14- _Export all_ to export both public and private links
22- _Export public_ to export public links only 15- _Export public_ to export public links only
23- _Export private_ to export private links only 16- _Export private_ to export private links only
24 17
25Restore by using the `Import` feature. 18Restore by using the `Import` feature.
26* This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool. 19
20- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
27 21
28Example command: 22Example command:
29```bash 23```bash
@@ -46,18 +40,21 @@ To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sou
46 40
47### Scuttle 41### Scuttle
48 42
49Shaarli 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. 43Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
44
45However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
46tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
50 47
51## Import Shaarli links to Firefox 48## Import Shaarli links to Firefox
52 49
53 * Export your Shaarli links as described above. 50- Export your Shaarli links as described above.
54 * For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)` 51 - For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
55 * In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`) 52- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
56 * Select `Import and Backup > Import bookmarks in HTML format` 53- Select `Import and Backup > Import bookmarks in HTML format`
57 54
58Your 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. 55Your 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.
59 56
60You may be interested in these Firefox addons to manage links imported from Shaarli 57You may be interested in these Firefox addons to manage links imported from Shaarli
61 58
62 * [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks 59- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
63 * [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags 60- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
diff --git a/doc/md/Bookmarklet.md b/doc/md/Bookmarklet.md
index 265ced44..e53e3261 100644
--- a/doc/md/Bookmarklet.md
+++ b/doc/md/Bookmarklet.md
@@ -1,23 +1,23 @@
1### Add the sharing button (_bookmarklet_) to your browser 1## Add the sharing button (_bookmarklet_) to your browser
2 2
3 * Open your Shaarli and `Login` 3- Open your Shaarli and `Login`
4 * Click the `Tools` button in the top bar 4- Click the `Tools` button in the top bar
5 * Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar. 5- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
6 6
7_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._ 7_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._
8 8
9![](images/bookmarklet.png) 9![](images/bookmarklet.png)
10 10
11### Share links using the _bookmarklet_ 11## Share links using the _bookmarklet_
12 12
13 * When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added. 13- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
14 * A window opens. 14- A window opens.
15 * You can freely edit title, description, tags... to find it later using the text search or tag filtering. 15 - You can freely edit title, description, tags... to find it later using the text search or tag filtering.
16 * You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button. 16 - You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.
17 * You can also check the “Private” box so that the link is saved but only visible to you. 17 - You can also check the “Private” box so that the link is saved but only visible to you.
18 * Click `Save`.**Voilà! Your link is now shared.** 18- Click `Save`.**Voilà! Your link is now shared.**
19 19
20### Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com) 20## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
21 21
22Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it. 22Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
23 23
@@ -25,6 +25,5 @@ See [#196](https://github.com/shaarli/Shaarli#196).
25 25
26There is an open bug for both Firefox and Chromium: 26There is an open bug for both Firefox and Chromium:
27 27
28 * https://bugzilla.mozilla.org/show_bug.cgi?id=866522 28- https://bugzilla.mozilla.org/show_bug.cgi?id=866522
29 * https://code.google.com/p/chromium/issues/detail?id=233903 29- https://code.google.com/p/chromium/issues/detail?id=233903
30
diff --git a/doc/md/Coding-guidelines.md b/doc/md/Coding-guidelines.md
deleted file mode 100644
index da47c498..00000000
--- a/doc/md/Coding-guidelines.md
+++ /dev/null
@@ -1,5 +0,0 @@
1## WIP
2
3This topic is currently being discussed here:
4- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
5- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index b8b7cccd..13b07b6f 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -22,15 +22,15 @@ _TODO: contact repos owners to see if they'd like to standardize their work with
22### Third party plugins 22### Third party plugins
23 23
24 24
25 * [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. 25- [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.
26 * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter. 26- [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
27 * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli. 27- [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
28 * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli. 28- [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
29 * [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support 29- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
30 * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli. 30- [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
31 * [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags. 31- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
32 * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks. 32- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
33 * [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli 33- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
34 34
35 35
36### Themes 36### Themes
diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md
index 849257f7..4bd7a0ba 100644
--- a/doc/md/Continuous-integration-tools.md
+++ b/doc/md/Continuous-integration-tools.md
@@ -1,22 +1,26 @@
1## Local development 1## Local development
2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations: 2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
3
3- Documentation - generate a local HTML copy of the GitHub wiki 4- Documentation - generate a local HTML copy of the GitHub wiki
4- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions 5- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions
5- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits 6- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits
6 7
7## Automatic builds 8## Automatic builds
8[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build: 9[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
10
9- each time a commit is merged to the mainline (`master` branch) 11- each time a commit is merged to the mainline (`master` branch)
10- each time a Pull Request is submitted or updated 12- each time a Pull Request is submitted or updated
11 13
12A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)). 14A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
13 15
14Each build job: 16Each build job:
17
15- updates Composer 18- updates Composer
16- installs 3rd-party test dependencies with Composer 19- installs 3rd-party test dependencies with Composer
17- runs [Unit tests](Unit tests) 20- runs [Unit tests](Unit tests)
18 21
19After all jobs have finished, Travis returns the results to GitHub: 22After all jobs have finished, Travis returns the results to GitHub:
23
20- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli) 24- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
21- Pull Requests are updated with the Travis result 25- Pull Requests are updated with the Travis result
22 - Green: all tests have passed 26 - Green: all tests have passed
diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md
index 3a248767..532ec2e4 100644
--- a/doc/md/Development-guidelines.md
+++ b/doc/md/Development-guidelines.md
@@ -1,6 +1,7 @@
1## Development guidelines 1## Development guidelines
2 2
3Please have a look at the following pages: 3Please have a look at the following pages:
4
4- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) 5- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
5- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: 6- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
6 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard 7 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index 7880aef4..135f0633 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -1,8 +1,16 @@
1To 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). 1To install Shaarli, simply place the files in a directory under your webserver's
2Document Root (or directly at the document root).
3
4Also, please make sure your server meets the [requirements](Server-requirements)
5and is properly [configured](Server-configuration).
2 6
3Several releases are available: 7Several releases are available:
4 8
5-------------------------------------------------------- 9- by downloading full release archives including all dependencies
10- by downloading Github archives
11- by cloning the Git repository
12
13---
6 14
7## Latest release (recommended) 15## Latest release (recommended)
8### Download as an archive 16### Download as an archive
@@ -10,29 +18,26 @@ Get the latest released version from the [releases](https://github.com/shaarli/S
10 18
11**Download our *shaarli-full* archive** to include dependencies. 19**Download our *shaarli-full* archive** to include dependencies.
12 20
13The current latest released version is `v0.8.4` 21The current latest released version is `v0.9.0`
14 22
15Or in command lines: 23Or in command lines:
16 24
17```bash 25```bash
18$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip 26$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.0/shaarli-v0.9.0-full.zip
19$ unzip shaarli-v0.8.4-full.zip 27$ unzip shaarli-v0.9.0-full.zip
20$ mv Shaarli /path/to/shaarli/ 28$ mv Shaarli /path/to/shaarli/
21``` 29```
22 30
23| ! |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).| 31In 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).|
24|-----|--------------------------|
25 32
26### Using git 33### Using git
27 34
28``` 35```
29mkdir -p /path/to/shaarli && cd /path/to/shaarli/ 36$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
30git clone -b v0.8 https://github.com/shaarli/Shaarli.git . 37$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
31composer install --no-dev 38$ composer install --no-dev --prefer-dist
32``` 39```
33 40
34--------------------------------------------------------
35
36## Stable version 41## Stable version
37 42
38The stable version has been experienced by Shaarli users, and will receive security updates. 43The stable version has been experienced by Shaarli users, and will receive security updates.
@@ -63,11 +68,9 @@ $ mv Shaarli-stable /path/to/shaarli/
63$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/ 68$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
64# install/update third-party dependencies 69# install/update third-party dependencies
65$ cd /path/to/shaarli/ 70$ cd /path/to/shaarli/
66$ composer install --no-dev 71$ composer install --no-dev --prefer-dist
67``` 72```
68 73
69--------------------------------------------------------
70
71## Development version (mainline) 74## Development version (mainline)
72 75
73_Use at your own risk!_ 76_Use at your own risk!_
@@ -79,11 +82,9 @@ To get the latest changes from the `master` branch:
79$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/ 82$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
80# install/update third-party dependencies 83# install/update third-party dependencies
81$ cd /path/to/shaarli 84$ cd /path/to/shaarli
82$ composer install --no-dev 85$ composer install --no-dev --prefer-dist
83``` 86```
84 87
85--------------------------------------------------------
86
87## Finish Installation 88## Finish Installation
88 89
89Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser. 90Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
@@ -92,8 +93,6 @@ Once Shaarli is downloaded and files have been placed at the correct location, o
92 93
93Setup your Shaarli installation, and it's ready to use! 94Setup your Shaarli installation, and it's ready to use!
94 95
95--------------------------------------------------------
96
97## Updating Shaarli 96## Updating Shaarli
98 97
99See [Upgrade and Migration](Upgrade-and-migration) 98See [Upgrade and Migration](Upgrade-and-migration)
diff --git a/doc/md/FAQ.md b/doc/md/FAQ.md
index 151dcef5..77faf117 100644
--- a/doc/md/FAQ.md
+++ b/doc/md/FAQ.md
@@ -8,23 +8,24 @@ Enough is enough. Saving simple links should not be a complicated heavy thing. I
8 8
9With Shaarli: 9With Shaarli:
10 10
11* The data is yours: It's hosted on your server. 11- The data is yours: It's hosted on your server.
12* Never fear of having your data locked-in. 12- Never fear of having your data locked-in.
13* Never fear to have your data sold to third party. 13- Never fear to have your data sold to third party.
14* Your private links are not hosted on a third party server. 14- Your private links are not hosted on a third party server.
15* You are not tracked by browser addons (like Diigo does) 15- You are not tracked by browser addons (like Diigo does)
16* You can change the look and feel of the pages if you want. 16- You can change the look and feel of the pages if you want.
17* You can change the behaviour of the program. 17- You can change the behaviour of the program.
18* It's magnitude faster than most bookmarking services. 18- It's magnitude faster than most bookmarking services.
19 19
20### What does Shaarli mean? 20### What does Shaarli mean?
21 21
22Shaarli is for shaaring your links. 22Shaarli stands for _shaaring_ your _links_.
23 23
24### My Shaarli is broken! 24### My Shaarli is broken!
25First 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). 25First 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).
26 26
27If everything looks right but the issue(s) remain(s), please: 27If everything looks right but the issue(s) remain(s), please:
28
28- take a look at the [troubleshooting](Troubleshooting) section 29- take a look at the [troubleshooting](Troubleshooting) section
29- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-) 30- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
30- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls) 31- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
diff --git a/doc/md/Features.md b/doc/md/Features.md
index 116b1c9c..eef88d03 100644
--- a/doc/md/Features.md
+++ b/doc/md/Features.md
@@ -1,24 +1,25 @@
1### Main features 1### Main features
2Shaarli is intended: 2Shaarli is intended:
3 * to share, comment and save interesting links and news 3
4 * to bookmark useful/frequent personal links (as private links) and share them between computers 4- to share, comment and save interesting links and news
5 * as a minimal blog/microblog/writing platform (no character limit) 5- to bookmark useful/frequent personal links (as private links) and share them between computers
6 * as a read-it-later list (for example items tagged `readlater`) 6- as a minimal blog/microblog/writing platform (no character limit)
7 * to draft and save articles/ideas 7- as a read-it-later list (for example items tagged `readlater`)
8 * to keep code snippets 8- to draft and save articles/ideas
9 * to keep notes and documentation 9- to keep code snippets
10 * as a shared clipboard between machines 10- to keep notes and documentation
11 * as a todo list 11- as a shared clipboard between machines
12 * to store playlists (e.g. with the `music` or `video` tags) 12- as a todo list
13 * to keep extracts/comments from webpages that may disappear 13- to store playlists (e.g. with the `music` or `video` tags)
14 * to keep track of ongoing discussions (for example items tagged `discussion`) 14- to keep extracts/comments from webpages that may disappear
15 * [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags 15- to keep track of ongoing discussions (for example items tagged `discussion`)
16 * to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...) 16- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
17- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
17 18
18### Using Shaarli as a blog, notepad, pastebin... 19### Using Shaarli as a blog, notepad, pastebin...
19 20
20 * Go to your Shaarli setup and log in 21- Go to your Shaarli setup and log in
21 * Click the `Add Link` button 22- Click the `Add Link` button
22 * To share text only, do not enter any URL in the corresponding input field and click `Add Link` 23- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
23 * Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save` 24- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
24 * Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink. 25- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
diff --git a/doc/md/Firefox-share.md b/doc/md/Firefox-share.md
index 595b9400..878884a4 100644
--- a/doc/md/Firefox-share.md
+++ b/doc/md/Firefox-share.md
@@ -1,15 +1,17 @@
1### Add Shaarli as a sharing service to Firefox 1### Add Shaarli as a sharing service to Firefox
2 2
3 * Open your Shaarli and `Login` 3- Open your Shaarli and `Login`
4 * Click the `Tools` button in the top bar 4- Click the `Tools` button in the top bar
5 * Click the `✚Add to Firefox social` button and accept the activation. 5- Click the `✚Add to Firefox social` button and accept the activation.
6 6
7 7
8### Sharing links using Firefox share 8### Sharing links using Firefox share
9 9
10 * Add the sharing service as described above 10- Add the sharing service as described above
11 * When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png) 11- When you are visiting a webpage you would like to share with Shaarli,
12 * You can edit your link before and after saving, just like the bookmarklet above. 12 click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
13- You can edit your link before and after saving, just like the bookmarklet above.
13 14
14|  | 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. | 15_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection)
15|------|-------------------------------------------------------------------------------| 16enabled server for Firefox Share to work. Firefox Share will not work over
17plain HTTP connections._
diff --git a/doc/md/GnuPG-signature.md b/doc/md/GnuPG-signature.md
index 62a17d33..d1fc10a5 100644
--- a/doc/md/GnuPG-signature.md
+++ b/doc/md/GnuPG-signature.md
@@ -1,10 +1,11 @@
1## Introduction 1## Introduction
2### PGP and GPG 2### PGP and GPG
3[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good 3[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the
4Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication, 4[Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
5signature and encryption. 5(OpenPGP) specification. Its main purposes are digital authentication, signature and encryption.
6 6
7It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify: 7It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
8
8- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master 9- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
9Keys](https://www.archlinux.org/master-keys/) 10Keys](https://www.archlinux.org/master-keys/)
10- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity 11- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
@@ -15,6 +16,7 @@ To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserve
15> 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. 16> 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.
16 17
17Trust 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: 18Trust 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:
19
18- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html) 20- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
19- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust) 21- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)
20 22
diff --git a/doc/md/Plugin-System.md b/doc/md/Plugin-System.md
index d55ffe7e..30f0ae74 100644
--- a/doc/md/Plugin-System.md
+++ b/doc/md/Plugin-System.md
@@ -1,6 +1,8 @@
1[**I am a developer.** Developer API.](#developer-api) 1[**I am a developer: ** Developer API](#developer-api)
2 2
3[**I am a template designer.** Guide for template designer.](#guide-for-template-designer) 3[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
4
5---
4 6
5## Developer API 7## Developer API
6 8
@@ -8,9 +10,9 @@
8 10
9The plugin system let you: 11The plugin system let you:
10 12
11 * insert content into specific places across templates. 13- insert content into specific places across templates.
12 * alter data before templates rendering. 14- alter data before templates rendering.
13 * alter data before saving new links. 15- alter data before saving new links.
14 16
15### How can I create a plugin for Shaarli? 17### How can I create a plugin for Shaarli?
16 18
@@ -47,8 +49,8 @@ hook_<plugin_name>_<hook_name>($data, $conf)
47 49
48Parameters: 50Parameters:
49 51
50 - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data) 52- data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
51 - conf: the `ConfigManager` instance. 53- conf: the `ConfigManager` instance.
52 54
53For exemple, if my plugin want to add data to the header, this function is needed: 55For exemple, if my plugin want to add data to the header, this function is needed:
54 56
@@ -106,9 +108,9 @@ Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file
106 108
107Each file contain two keys: 109Each file contain two keys:
108 110
109 * `description`: plugin description 111- `description`: plugin description
110 * `parameters`: user parameter names, separated by a `;`. 112- `parameters`: user parameter names, separated by a `;`.
111 * `parameter.<PARAMETER_NAME>`: add a text description the specified parameter. 113- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
112 114
113> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. 115> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
114 116
@@ -148,8 +150,8 @@ Allow plugin to add content in page headers.
148 150
149`$data` is an array containing: 151`$data` is an array containing:
150 152
151 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). 153- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
152 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 154- `_LOGGEDIN_`: true if user is logged in, false otherwise.
153 155
154##### Template placeholders 156##### Template placeholders
155 157
@@ -157,11 +159,11 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
157 159
158List of placeholders: 160List of placeholders:
159 161
160 * `buttons_toolbar`: after the list of buttons in the header. 162- `buttons_toolbar`: after the list of buttons in the header.
161 163
162![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png) 164![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
163 165
164 * `fields_toolbar`: after search fields in the header. 166- `fields_toolbar`: after search fields in the header.
165 167
166> Note: This will only be called in linklist. 168> Note: This will only be called in linklist.
167 169
@@ -177,8 +179,8 @@ Allow plugin to include their own CSS files.
177 179
178`$data` is an array containing: 180`$data` is an array containing:
179 181
180 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). 182- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
181 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 183- `_LOGGEDIN_`: true if user is logged in, false otherwise.
182 184
183##### Template placeholders 185##### Template placeholders
184 186
@@ -186,7 +188,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
186 188
187List of placeholders: 189List of placeholders:
188 190
189 * `css_files`: called after loading default CSS. 191- `css_files`: called after loading default CSS.
190 192
191> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`. 193> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
192 194
@@ -200,8 +202,8 @@ Allow plugin to add content in page footer and include their own JS files.
200 202
201`$data` is an array containing: 203`$data` is an array containing:
202 204
203 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). 205- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
204 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 206- `_LOGGEDIN_`: true if user is logged in, false otherwise.
205 207
206##### Template placeholders 208##### Template placeholders
207 209
@@ -209,12 +211,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
209 211
210List of placeholders: 212List of placeholders:
211 213
212 * `text`: called after the end of the footer text. 214- `text`: called after the end of the footer text.
213 * `endofpage`: called at the end of the page. 215- `endofpage`: called at the end of the page.
214 216
215![text_example](http://i.imgur.com/L5S2YEH.png) 217![text_example](http://i.imgur.com/L5S2YEH.png)
216 218
217 * `js_files`: called at the end of the page, to include custom JS scripts. 219- `js_files`: called at the end of the page, to include custom JS scripts.
218 220
219> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`. 221> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
220 222
@@ -228,8 +230,8 @@ It allows to add content at the begining and end of the page, after every link d
228 230
229`$data` is an array containing: 231`$data` is an array containing:
230 232
231 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 233- `_LOGGEDIN_`: true if user is logged in, false otherwise.
232 * All templates data, including links. 234- All templates data, including links.
233 235
234##### Template placeholders 236##### Template placeholders
235 237
@@ -237,19 +239,19 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
237 239
238List of placeholders: 240List of placeholders:
239 241
240 * `action_plugin`: next to the button "private only" at the top and bottom of the page. 242- `action_plugin`: next to the button "private only" at the top and bottom of the page.
241 243
242![action_plugin_example](http://i.imgur.com/Q12PWg0.png) 244![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
243 245
244 * `link_plugin`: for every link, between permalink and link URL. 246- `link_plugin`: for every link, between permalink and link URL.
245 247
246![link_plugin_example](http://i.imgur.com/3oDPhWx.png) 248![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
247 249
248 * `plugin_start_zone`: before displaying the template content. 250- `plugin_start_zone`: before displaying the template content.
249 251
250![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png) 252![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
251 253
252 * `plugin_end_zone`: after displaying the template content. 254- `plugin_end_zone`: after displaying the template content.
253 255
254![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png) 256![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
255 257
@@ -263,7 +265,7 @@ Allow to add fields in the form, or display elements.
263 265
264`$data` is an array containing: 266`$data` is an array containing:
265 267
266 * All templates data. 268- All templates data.
267 269
268##### Template placeholders 270##### Template placeholders
269 271
@@ -271,7 +273,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
271 273
272List of placeholders: 274List of placeholders:
273 275
274 * `edit_link_plugin`: after tags field. 276- `edit_link_plugin`: after tags field.
275 277
276![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png) 278![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
277 279
@@ -285,7 +287,7 @@ Allow to add content at the end of the page.
285 287
286`$data` is an array containing: 288`$data` is an array containing:
287 289
288 * All templates data. 290- All templates data.
289 291
290##### Template placeholders 292##### Template placeholders
291 293
@@ -293,7 +295,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
293 295
294List of placeholders: 296List of placeholders:
295 297
296 * `tools_plugin`: at the end of the page. 298- `tools_plugin`: at the end of the page.
297 299
298![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png) 300![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
299 301
@@ -307,8 +309,8 @@ Allow to add content at the top and bottom of the page.
307 309
308`$data` is an array containing: 310`$data` is an array containing:
309 311
310 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 312- `_LOGGEDIN_`: true if user is logged in, false otherwise.
311 * All templates data. 313- All templates data.
312 314
313##### Template placeholders 315##### Template placeholders
314 316
@@ -316,9 +318,8 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
316 318
317List of placeholders: 319List of placeholders:
318 320
319 * `plugin_start_zone`: before displaying the template content. 321- `plugin_start_zone`: before displaying the template content.
320 322- `plugin_end_zone`: after displaying the template content.
321 * `plugin_end_zone`: after displaying the template content.
322 323
323![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png) 324![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
324 325
@@ -332,8 +333,8 @@ Allow to add content at the top and bottom of the page.
332 333
333`$data` is an array containing: 334`$data` is an array containing:
334 335
335 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 336- `_LOGGEDIN_`: true if user is logged in, false otherwise.
336 * All templates data. 337- All templates data.
337 338
338##### Template placeholders 339##### Template placeholders
339 340
@@ -341,13 +342,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
341 342
342List of placeholders: 343List of placeholders:
343 344
344 * `plugin_start_zone`: before displaying the template content. 345- `plugin_start_zone`: before displaying the template content.
345 346- `plugin_end_zone`: after displaying the template content.
346 * `plugin_end_zone`: after displaying the template content.
347 347
348For each tag, the following placeholder can be used: 348For each tag, the following placeholder can be used:
349 349
350 * `tag_plugin`: after each tag 350- `tag_plugin`: after each tag
351 351
352![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png) 352![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
353 353
@@ -362,8 +362,8 @@ Allow to add content at the top and bottom of the page.
362 362
363`$data` is an array containing: 363`$data` is an array containing:
364 364
365 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 365- `_LOGGEDIN_`: true if user is logged in, false otherwise.
366 * All templates data. 366- All templates data.
367 367
368##### Template placeholders 368##### Template placeholders
369 369
@@ -371,13 +371,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
371 371
372List of placeholders: 372List of placeholders:
373 373
374 * `plugin_start_zone`: before displaying the template content. 374- `plugin_start_zone`: before displaying the template content.
375 375- `plugin_end_zone`: after displaying the template content.
376 * `plugin_end_zone`: after displaying the template content.
377 376
378For each tag, the following placeholder can be used: 377For each tag, the following placeholder can be used:
379 378
380 * `tag_plugin`: after each tag 379- `tag_plugin`: after each tag
381 380
382#### render_daily 381#### render_daily
383 382
@@ -389,8 +388,8 @@ Allow to add content at the top and bottom of the page, the bottom of each link
389 388
390`$data` is an array containing: 389`$data` is an array containing:
391 390
392 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 391- `_LOGGEDIN_`: true if user is logged in, false otherwise.
393 * All templates data, including links. 392- All templates data, including links.
394 393
395##### Template placeholders 394##### Template placeholders
396 395
@@ -398,13 +397,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
398 397
399List of placeholders: 398List of placeholders:
400 399
401 * `link_plugin`: used at bottom of each link. 400- `link_plugin`: used at bottom of each link.
402 401
403![link_plugin_example](http://i.imgur.com/hzhMfSZ.png) 402![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
404 403
405 * `plugin_start_zone`: before displaying the template content. 404- `plugin_start_zone`: before displaying the template content.
406 405- `plugin_end_zone`: after displaying the template content.
407 * `plugin_end_zone`: after displaying the template content.
408 406
409#### render_feed 407#### render_feed
410 408
@@ -416,9 +414,9 @@ Allow to add tags in the feed, either in the header or for each items. Items (li
416 414
417`$data` is an array containing: 415`$data` is an array containing:
418 416
419 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 417- `_LOGGEDIN_`: true if user is logged in, false otherwise.
420 * `_PAGE_`: containing either `rss` or `atom`. 418- `_PAGE_`: containing either `rss` or `atom`.
421 * All templates data, including links. 419- All templates data, including links.
422 420
423##### Template placeholders 421##### Template placeholders
424 422
@@ -426,11 +424,11 @@ Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
426 424
427List of placeholders: 425List of placeholders:
428 426
429 * `feed_plugins_header`: used as a header tag in the feed. 427- `feed_plugins_header`: used as a header tag in the feed.
430 428
431For each links: 429For each links:
432 430
433 * `feed_plugins`: additional tag for every link entry. 431- `feed_plugins`: additional tag for every link entry.
434 432
435#### save_link 433#### save_link
436 434
@@ -442,15 +440,15 @@ Allow to alter the link being saved in the datastore.
442 440
443`$data` is an array containing the link being saved: 441`$data` is an array containing the link being saved:
444 442
445 * id 443- id
446 * title 444- title
447 * url 445- url
448 * shorturl 446- shorturl
449 * description 447- description
450 * private 448- private
451 * tags 449- tags
452 * created 450- created
453 * updated 451- updated
454 452
455 453
456#### delete_link 454#### delete_link
@@ -463,15 +461,15 @@ Allow to execute any action before the link is actually removed from the datasto
463 461
464`$data` is an array containing the link being saved: 462`$data` is an array containing the link being saved:
465 463
466 * id 464- id
467 * title 465- title
468 * url 466- url
469 * shorturl 467- shorturl
470 * description 468- description
471 * private 469- private
472 * tags 470- tags
473 * created 471- created
474 * updated 472- updated
475 473
476## Guide for template designer 474## Guide for template designer
477 475
@@ -485,9 +483,9 @@ Use the default one as an example.
485 483
486Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if: 484Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
487 485
488 * you're using a table. 486- you're using a table.
489 * you call orderUp() and orderUp() onclick on arrows. 487- you call orderUp() and orderUp() onclick on arrows.
490 * you add data-line and data-order to your rows. 488- you add data-line and data-order to your rows.
491 489
492Otherwise, you can use your own JS as long as this field is send by the form: 490Otherwise, you can use your own JS as long as this field is send by the form:
493 491
diff --git a/doc/md/Plugins.md b/doc/md/Plugins.md
index b52b8090..7d40637f 100644
--- a/doc/md/Plugins.md
+++ b/doc/md/Plugins.md
@@ -4,9 +4,9 @@ There is a bunch of plugins shipped with Shaarli, where there is nothing to do t
4 4
5If you want to install a third party plugin: 5If you want to install a third party plugin:
6 6
7 * Download it. 7- Download it.
8 * Put it in the `plugins` directory in Shaarli's installation folder. 8- Put it in the `plugins` directory in Shaarli's installation folder.
9 * Make sure you put it correctly: 9- Make sure you put it correctly:
10 10
11``` 11```
12| index.php 12| index.php
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
index 8f3f7303..0b8aba8a 100644
--- a/doc/md/REST-API.md
+++ b/doc/md/REST-API.md
@@ -1,6 +1,18 @@
1## Usage 1## Usage and Prerequisites
2 2
3See the [REST API documentation](http://shaarli.github.io/api-documentation/). 3See the [REST API documentation](http://shaarli.github.io/api-documentation/)
4for a list of available endpoints and parameters.
5
6Please ensure that your server meets the [requirements](Server-requirements)
7and is properly [configured](Server-configuration):
8
9- URL rewriting is enabled (see specific Apache and Nginx sections)
10- the server's timezone is properly defined
11- the server's clock is synchronized with
12 [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)
13
14The host where the API client is invoked should also be synchronized with NTP,
15see [token expiration](#payload).
4 16
5## Authentication 17## Authentication
6 18
@@ -10,10 +22,10 @@ This token has to be included as an HTTP header called `Authentication: Bearer <
10 22
11JWT resources : 23JWT resources :
12 24
13 * [jwt.io](https://jwt.io) (including a list of client per language). 25- [jwt.io](https://jwt.io) (including a list of client per language).
14 * RFC : https://tools.ietf.org/html/rfc7519 26- RFC : https://tools.ietf.org/html/rfc7519
15 * https://float-middle.com/json-web-tokens-jwt-vs-sessions/ 27- https://float-middle.com/json-web-tokens-jwt-vs-sessions/
16 * HackerNews thread: https://news.ycombinator.com/item?id=11929267 28- HackerNews thread: https://news.ycombinator.com/item?id=11929267
17 29
18 30
19### Shaarli JWT Token 31### Shaarli JWT Token
@@ -43,9 +55,11 @@ ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
43 55
44#### Payload 56#### Payload
45 57
46**Validity duration** 58**Token expiration**
47 59
48To 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. 60To avoid infinite token validity, JWT tokens must include their creation date
61in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at).
62This token will be valid during **9 minutes**.
49 63
50```json 64```json
51{ 65{
@@ -68,37 +82,67 @@ $signature = hash_hmac('sha512', $content, $secret);
68``` 82```
69 83
70 84
71### Complete example 85## Clients and examples
86### Android, Java, Kotlin
87
88- [Android client example with Kotlin](https://gitlab.com/snippets/1665808)
89 by [Braincoke](https://github.com/Braincoke)
90
72 91
73#### PHP 92### PHP
93
94This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library.
74 95
75```php 96```php
97<?php
98$baseUrl = 'https://shaarli.mydomain.net';
99$secret = 'thats_my_api_secret';
100
101function base64url_encode($data) {
102 return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
103}
104
76function generateToken($secret) { 105function generateToken($secret) {
77 $header = base64_encode('{ 106 $header = base64url_encode('{
78 "typ": "JWT", 107 "typ": "JWT",
79 "alg": "HS512" 108 "alg": "HS512"
80 }'); 109 }');
81 $payload = base64_encode('{ 110 $payload = base64url_encode('{
82 "iat": '. time() .' 111 "iat": '. time() .'
83 }'); 112 }');
84 $signature = hash_hmac('sha512', $header .'.'. $payload , $secret); 113 $signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true));
85 return $header .'.'. $payload .'.'. $signature; 114 return $header . '.' . $payload . '.' . $signature;
86} 115}
87 116
88$secret = 'mysecret';
89$token = generateToken($secret);
90echo $token;
91```
92 117
93> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68` 118function getInfo($baseUrl, $secret) {
119 $token = generateToken($secret);
120 $endpoint = rtrim($baseUrl, '/') . '/api/v1/info';
94 121
95```php 122 $headers = [
96$options = [ 123 'Content-Type: text/plain; charset=UTF-8',
97 'http' => [ 124 'Authorization: Bearer ' . $token,
98 'method' => 'GET', 125 ];
99 'jwt' => $token, 126
100 ], 127 $ch = curl_init($endpoint);
101]; 128 curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
102$context = stream_context_create($options); 129 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
103file_get_contents($apiEndpoint, false, $context); 130 curl_setopt($ch, CURLOPT_AUTOREFERER, 1);
131 curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
132
133 $result = curl_exec($ch);
134 curl_close($ch);
135
136 return $result;
137}
138
139var_dump(getInfo($baseUrl, $secret));
104``` 140```
141
142
143### Python
144
145See the reference API client:
146
147- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
148- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github
diff --git a/doc/md/RSS-feeds.md b/doc/md/RSS-feeds.md
index 9d718172..d943218e 100644
--- a/doc/md/RSS-feeds.md
+++ b/doc/md/RSS-feeds.md
@@ -3,6 +3,7 @@
3Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`. 3Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
4 4
5Options: 5Options:
6
6- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL. 7- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
7 - E.G. `https://my.shaarli.domain/?do=atom&permalinks`. 8 - E.G. `https://my.shaarli.domain/?do=atom&permalinks`.
8- 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. 9- 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.
@@ -14,6 +15,7 @@ Options:
14It 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**. 15It 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**.
15 16
16For example, if you want to subscribe only to links tagged `photography`: 17For example, if you want to subscribe only to links tagged `photography`:
18
17- Go to the desired Shaarli instance. 19- Go to the desired Shaarli instance.
18- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed. 20- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
19- Click on the `RSS Feed` button. 21- Click on the `RSS Feed` button.
diff --git a/doc/md/Release-Shaarli.md b/doc/md/Release-Shaarli.md
index 0e445272..8ff0a080 100644
--- a/doc/md/Release-Shaarli.md
+++ b/doc/md/Release-Shaarli.md
@@ -3,6 +3,7 @@ releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Ta
3 3
4## Prerequisites 4## Prerequisites
5This guide assumes that you have: 5This guide assumes that you have:
6
6- a GPG key matching your GitHub authentication credentials 7- a GPG key matching your GitHub authentication credentials
7 - i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig` 8 - i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
8- a GitHub fork of Shaarli 9- a GitHub fork of Shaarli
@@ -43,32 +44,13 @@ TBA
43``` 44```
44 45
45 46
46## Increment the version code, updated docs, create and push a signed tag 47## Increment the version code, update docs, create and push a signed tag
47### Generate documentation
48```bash
49$ cd /path/to/shaarli
50
51# create a new branch
52$ git fetch upstream
53$ git checkout upstream/master -b v0.5.0
54
55# rebuild the HTML documentation from Markdown
56$ make htmlpages
57
58# commit the changes
59$ git add doc
60$ git commit -s -m "Generate documentation for v0.5.0"
61
62# push the commit on your GitHub fork
63$ git push origin v0.5.0
64```
65
66### Create and merge a Pull Request 48### Create and merge a Pull Request
67This one is pretty straightforward ;-) 49This one is pretty straightforward ;-)
68 50
69### Bump Shaarli version to v0.x branch 51### Bump Shaarli version to v0.x branch
70 52
71``` 53```bash
72$ git checkout master 54$ git checkout master
73$ git fetch upstream 55$ git fetch upstream
74$ git pull upstream master 56$ git pull upstream master
@@ -125,6 +107,7 @@ Update `README.md` so version badges display and point to the newly released Sha
125 107
126### Create a GitHub release from a Git tag 108### Create a GitHub release from a Git tag
127From the previously drafted release: 109From the previously drafted release:
110
128- edit the release notes (if needed) 111- edit the release notes (if needed)
129- specify the appropriate Git tag 112- specify the appropriate Git tag
130- publish the release 113- publish the release
@@ -132,6 +115,7 @@ From the previously drafted release:
132 115
133### Generate and upload all-in-one release archives 116### Generate and upload all-in-one release archives
134Users with a shared hosting may have: 117Users with a shared hosting may have:
118
135- no SSH access 119- no SSH access
136- no possibility to install PHP packages or server extensions 120- no possibility to install PHP packages or server extensions
137- no possibility to run scripts 121- no possibility to run scripts
@@ -146,6 +130,7 @@ $ make release_archive
146``` 130```
147 131
148This will create the following archives: 132This will create the following archives:
133
149- `shaarli-vX.Y.Z-full.tar` 134- `shaarli-vX.Y.Z-full.tar`
150- `shaarli-vX.Y.Z-full.zip` 135- `shaarli-vX.Y.Z-full.zip`
151 136
diff --git a/doc/md/Security.md b/doc/md/Security.md
index aec37fa0..36f629af 100644
--- a/doc/md/Security.md
+++ b/doc/md/Security.md
@@ -1,27 +1,28 @@
1## Client browser 1## Client browser
2* 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 2- 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
3 3
4## PHP 4## PHP
5* `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. 5- `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.
6 6
7## Server and sessions 7## Server and sessions
8* Directories are protected using `.htaccess` files 8- Directories are protected using `.htaccess` files
9* Forms are protected against XSRF (Cross-site requests forgery): 9- Forms are protected against XSRF (Cross-site requests forgery):
10 * Forms which act on data (save,delete…) contain a token generated by the server. 10 - Forms which act on data (save,delete…) contain a token generated by the server.
11 * Any posted form which does not contain a valid token is rejected. 11 - Any posted form which does not contain a valid token is rejected.
12 * Any token can only be used once. 12 - Any token can only be used once.
13 * Tokens are attached to the session and cannot be reused in another session. 13 - Tokens are attached to the session and cannot be reused in another session.
14* Sessions automatically expire after 60 minutes. 14- Sessions automatically expire after 60 minutes.
15* Sessions are protected against hijacking: the session ID cannot be used from a different IP address. 15- Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
16 16
17## Shaarli datastore and configuration 17## Shaarli datastore and configuration
18* 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. 18- 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.
19* Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file. 19- Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file.
20* Even if the server does not support `.htaccess` files, the data file will still not be readable by URL. 20- Even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
21* The database looks like this: 21- The database looks like this:
22
22```php 23```php
23<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o... 24<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
24...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?> 25...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
25``` 26```
26 27
27* 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 `@`. 28- Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`.
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index 23fdbc8b..25dd49fe 100644
--- a/doc/md/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -5,23 +5,26 @@
5 5
6## Prerequisites 6## Prerequisites
7### Shaarli 7### Shaarli
8* Shaarli is installed in a directory readable/writeable by the user 8- Shaarli is installed in a directory readable/writeable by the user
9* the correct read/write permissions have been granted to the web server _user and/or group_ 9- the correct read/write permissions have been granted to the web server _user and/or group_
10* for HTTPS / SSL: 10- for HTTPS / SSL:
11 * a key pair (public, private) and a certificate have been generated 11 - a key pair (public, private) and a certificate have been generated
12 * the appropriate server SSL extension is installed and active 12 - the appropriate server SSL extension is installed and active
13 13
14### HTTPS, TLS and self-signed certificates 14### HTTPS, TLS and self-signed certificates
15Related guides: 15Related guides:
16* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) 16
17* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) 17- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
18* 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` 18- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
19- Generate a self-signed certificate (will trigger browser warnings) with apache2:
20 `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`
19 21
20### Proxies 22### Proxies
21If 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: 23If 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:
22- `X-Forwarded-Proto`; 24
23- `X-Forwarded-Host`; 25- `X-Forwarded-Proto`
24- `X-Forwarded-For`. 26- `X-Forwarded-Host`
27- `X-Forwarded-For`
25 28
26See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. 29See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
27 30
@@ -37,8 +40,9 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9
37This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors. 40This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
38 41
39See: 42See:
40* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow) 43
41* [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/) 44- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
45- [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/)
42 46
43```apache 47```apache
44<VirtualHost *:80> 48<VirtualHost *:80>
@@ -116,34 +120,41 @@ Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriti
116Nginx 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. 120Nginx 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.
117 121
118Required packages: 122Required packages:
123
119- [nginx](http://nginx.org) 124- [nginx](http://nginx.org)
120- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager 125- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
121 126
122Official documentation: 127Official documentation:
128
123- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) 129- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
124- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) 130- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
125- [Pitfalls](http://wiki.nginx.org/Pitfalls) 131- [Pitfalls](http://wiki.nginx.org/Pitfalls)
126 132
127Community resources: 133Community resources:
134
128- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla) 135- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
129- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing) 136- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
130 137
131### Common setup 138### Common setup
132Once Nginx and PHP-FPM are installed, we need to ensure: 139Once Nginx and PHP-FPM are installed, we need to ensure:
140
133- Nginx and PHP-FPM are running using the _same user and group_ 141- Nginx and PHP-FPM are running using the _same user and group_
134- both these user and group have 142- both these user and group have
135 - `read` permissions for Shaarli resources 143 - `read` permissions for Shaarli resources
136 - `execute` permissions for Shaarli directories _AND_ their parent directories 144 - `execute` permissions for Shaarli directories _AND_ their parent directories
137 145
138On a production server: 146On a production server:
147
139- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data` 148- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
140- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx` 149- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
141 150
142On a development server: 151On a development server:
152
143- files may be located in a user's home directory 153- files may be located in a user's home directory
144- in this case, make sure both Nginx and PHP-FPM are running as the local user/group! 154- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
145 155
146For all following configuration examples, this user/group pair will be used: 156For all following configuration examples, this user/group pair will be used:
157
147- `user:group = john:users`, 158- `user:group = john:users`,
148 159
149which corresponds to the following service configuration: 160which corresponds to the following service configuration:
@@ -237,6 +248,7 @@ http {
237 248
238### Modular 249### Modular
239The previous setup is sufficient for development purposes, but has several major caveats: 250The previous setup is sufficient for development purposes, but has several major caveats:
251
240- every content that does not match the PHP rule will be sent to client browsers: 252- every content that does not match the PHP rule will be sent to client browsers:
241 - dotfiles - in our case, `.htaccess` 253 - dotfiles - in our case, `.htaccess`
242 - temporary files, e.g. Vim or Emacs files: `index.php~` 254 - temporary files, e.g. Vim or Emacs files: `index.php~`
@@ -342,7 +354,9 @@ http {
342``` 354```
343 355
344### Redirect HTTP to HTTPS 356### Redirect HTTP to HTTPS
345Assuming 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. 357Assuming you have generated a (self-signed) key and certificate, and they are
358located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
359to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
346 360
347```nginx 361```nginx
348# /etc/nginx/nginx.conf 362# /etc/nginx/nginx.conf
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
index b6bbd66a..707af762 100644
--- a/doc/md/Server-requirements.md
+++ b/doc/md/Server-requirements.md
@@ -10,14 +10,15 @@
10### Supported versions 10### Supported versions
11Version | Status | Shaarli compatibility 11Version | Status | Shaarli compatibility
12:---:|:---:|:---: 12:---:|:---:|:---:
137.1 | Supported (v0.9.x) | :white_check_mark: 137.1 | Supported (v0.9.x) | Yes
147.0 | Supported | :white_check_mark: 147.0 | Supported | Yes
155.6 | Supported | :white_check_mark: 155.6 | Supported | Yes
165.5 | EOL: 2016-07-10 | :white_check_mark: 165.5 | EOL: 2016-07-10 | Yes
175.4 | EOL: 2015-09-14 | :white_check_mark: (up to Shaarli 0.8.x) 175.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
185.3 | EOL: 2014-08-14 | :white_check_mark: (up to Shaarli 0.8.x) 185.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
19 19
20See also: 20See also:
21
21- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml) 22- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
22 23
23### Dependency management 24### Dependency management
diff --git a/doc/md/Server-security.md b/doc/md/Server-security.md
index 8df36f46..700084e2 100644
--- a/doc/md/Server-security.md
+++ b/doc/md/Server-security.md
@@ -1,5 +1,6 @@
1## php.ini 1## php.ini
2PHP settings are defined in: 2PHP settings are defined in:
3
3- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g. 4- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
4 - `/etc/php5/php.ini` - used when running console scripts 5 - `/etc/php5/php.ini` - used when running console scripts
5 - `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache 6 - `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache
@@ -30,6 +31,7 @@ Additional .ini files parsed: /etc/php/conf.d/xdebug.ini
30 31
31## fail2ban 32## fail2ban
32`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts: 33`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
34
33- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page) 35- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
34- [Source code](https://github.com/fail2ban/fail2ban) 36- [Source code](https://github.com/fail2ban/fail2ban)
35 37
@@ -68,6 +70,7 @@ Disallow: /
68``` 70```
69 71
70See: 72See:
71- http://www.robotstxt.org/ 73
74- http://www.robotstxt.org
72- http://www.robotstxt.org/robotstxt.html 75- http://www.robotstxt.org/robotstxt.html
73- http://www.robotstxt.org/meta.html 76- http://www.robotstxt.org/meta.html
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
index 0c605459..188a3c09 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -42,70 +42,70 @@ See also [Plugin System](Plugin-System.html).
42 42
43### Credentials 43### Credentials
44 44
45> You shouldn't edit those. 45_These settings should not be edited_
46 46
47**login**: Login username. 47- **login**: Login username.
48**hash**: Generated password hash. 48- **hash**: Generated password hash.
49**salt**: Password salt. 49- **salt**: Password salt.
50 50
51### General 51### General
52 52
53**title**: Shaarli's instance title. 53- **title**: Shaarli's instance title.
54**header_link**: Link to the homepage. 54- **header_link**: Link to the homepage.
55**links_per_page**: Number of shaares displayed per page. 55- **links_per_page**: Number of shaares displayed per page.
56**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). 56- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
57**enabled_plugins**: List of enabled plugins. 57- **enabled_plugins**: List of enabled plugins.
58 58
59### Security 59### Security
60 60
61**session_protection_disabled**: Disable session cookie hijacking protection (not recommended). 61- **session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
62It might be useful if your IP adress often changes. 62 It might be useful if your IP adress often changes.
63**ban_after**: Failed login attempts before being IP banned. 63- **ban_after**: Failed login attempts before being IP banned.
64**ban_duration**: IP ban duration in seconds. 64- **ban_duration**: IP ban duration in seconds.
65**open_shaarli**: Anyone can add a new link while logged out if enabled. 65- **open_shaarli**: Anyone can add a new link while logged out if enabled.
66**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. 66- **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
67**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"]`). 67- **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"]`).
68 68
69### Resources 69### Resources
70 70
71**data_dir**: Data directory. 71- **data_dir**: Data directory.
72**datastore**: Shaarli's links database file path. 72- **datastore**: Shaarli's links database file path.
73**history**: Shaarli's operation history file path. 73- **history**: Shaarli's operation history file path.
74**updates**: File path for the ran updates file. 74- **updates**: File path for the ran updates file.
75**log**: Log file path. 75- **log**: Log file path.
76**update_check**: Last update check file path. 76- **update_check**: Last update check file path.
77**raintpl_tpl**: Templates directory. 77- **raintpl_tpl**: Templates directory.
78**raintpl_tmp**: Template engine cache directory. 78- **raintpl_tmp**: Template engine cache directory.
79**thumbnails_cache**: Thumbnails cache directory. 79- **thumbnails_cache**: Thumbnails cache directory.
80**page_cache**: Shaarli's internal cache directory. 80- **page_cache**: Shaarli's internal cache directory.
81**ban_file**: Banned IP file path. 81- **ban_file**: Banned IP file path.
82 82
83### Updates 83### Updates
84 84
85**check_updates**: Enable or disable update check to the git repository. 85- **check_updates**: Enable or disable update check to the git repository.
86**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`). 86- **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
87**check_updates_interval**: Look for new version every N seconds (default: every day). 87- **check_updates_interval**: Look for new version every N seconds (default: every day).
88 88
89### Privacy 89### Privacy
90 90
91**default_private_links**: Check the private checkbox by default for every new link. 91- **default_private_links**: Check the private checkbox by default for every new link.
92**hide_public_links**: All links are hidden while logged out. 92- **hide_public_links**: All links are hidden while logged out.
93**hide_timestamps**: Timestamps are hidden. 93- **hide_timestamps**: Timestamps are hidden.
94 94
95### Feed 95### Feed
96 96
97**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL. 97- **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
98**show_atom**: Display ATOM feed button. 98- **show_atom**: Display ATOM feed button.
99 99
100### Thumbnail 100### Thumbnail
101 101
102**enable_thumbnails**: Enable or disable thumbnail display. 102- **enable_thumbnails**: Enable or disable thumbnail display.
103**enable_localcache**: Enable or disable local cache. 103- **enable_localcache**: Enable or disable local cache.
104 104
105### Redirector 105### Redirector
106 106
107**url**: Redirector URL, such as `anonym.to`. 107- **url**: Redirector URL, such as `anonym.to`.
108**encode_url**: Enable this if the redirector needs encoded URL to work properly. 108- **encode_url**: Enable this if the redirector needs encoded URL to work properly.
109 109
110## Configuration file example 110## Configuration file example
111 111
@@ -211,7 +211,7 @@ It might be useful if your IP adress often changes.
211 211
212## Additional configuration 212## Additional configuration
213 213
214The playvideos plugin may require that you adapt your server's 214The `playvideos` plugin may require that you adapt your server's
215[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) 215[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
216configuration to work properly.[](.html) 216configuration to work properly.
217 217
diff --git a/doc/md/Static-analysis.md b/doc/md/Static-analysis.md
index ee4f5978..29d98362 100644
--- a/doc/md/Static-analysis.md
+++ b/doc/md/Static-analysis.md
@@ -1,5 +1,6 @@
1## WIP 1## WIP
2This topic is currently being discussed here: 2This topic is currently being discussed here:
3
3- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95) 4- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
4- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130) 5- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
5 6
@@ -7,5 +8,6 @@ This topic is currently being discussed here:
7Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile). 8Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
8 9
9For an overview of the available features, see: 10For an overview of the available features, see:
11
10- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124) 12- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
11- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276) 13- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)
diff --git a/doc/md/Theming.md b/doc/md/Theming.md
index d72c2ffd..bd400776 100644
--- a/doc/md/Theming.md
+++ b/doc/md/Theming.md
@@ -8,6 +8,7 @@ There are two ways of customizing how Shaarli looks:
8## Custom CSS 8## Custom CSS
9 9
10Shaarli's appearance can be modified by adding CSS rules to: 10Shaarli's appearance can be modified by adding CSS rules to:
11
11- Shaarli < `v0.9.0`: `inc/user.css` 12- Shaarli < `v0.9.0`: `inc/user.css`
12- Shaarli >= `v0.9.0`: `data/user.css` 13- Shaarli >= `v0.9.0`: `data/user.css`
13 14
@@ -19,9 +20,8 @@ See also [Download CSS styles from an OPML list](Download CSS styles from an OPM
19 20
20## Themes 21## Themes
21 22
22_WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._
23
24Installation: 23Installation:
24
25- find a theme you'd like to install 25- find a theme you'd like to install
26- copy or clone the theme folder under `tpl/<a_sweet_theme>` 26- copy or clone the theme folder under `tpl/<a_sweet_theme>`
27- enable the theme: 27- enable the theme:
@@ -54,6 +54,7 @@ Installation:
54## Example installation: AlbinoMouse theme 54## Example installation: AlbinoMouse theme
55 55
56With the following configuration: 56With the following configuration:
57
57- Apache 2 / PHP 5.6 58- Apache 2 / PHP 5.6
58- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir` 59- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
59- `http` is the name of the Apache user 60- `http` is the name of the Apache user
@@ -77,7 +78,7 @@ Get config written:
77- fill the install form 78- fill the install form
78- log in to Shaarli 79- log in to Shaarli
79 80
80Edit Shaarli's [configuration|Shaarli configuration](configuration|Shaarli configuration): 81Edit Shaarli's [configuration](Shaarli-configuration):
81```bash 82```bash
82# the file should be owned by Apache, thus not writeable => sudo 83# the file should be owned by Apache, thus not writeable => sudo
83$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php 84$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
diff --git a/doc/md/Troubleshooting.md b/doc/md/Troubleshooting.md
index 13005526..b2d86d40 100644
--- a/doc/md/Troubleshooting.md
+++ b/doc/md/Troubleshooting.md
@@ -7,6 +7,7 @@
7Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages. 7Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
8 8
9See: 9See:
10
10- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia) 11- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
11- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/) 12- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
12- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/) 13- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
@@ -16,29 +17,35 @@ See:
16HTTP settings are available by browsing `about:config`, here are the available settings and their values. 17HTTP settings are available by browsing `about:config`, here are the available settings and their values.
17 18
18`network.http.sendRefererHeader` - determines when to send the Referer HTTP header 19`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
19- 0: Never send the referring URL 20
21- `0`: Never send the referring URL
20 - not recommended, may break some sites 22 - not recommended, may break some sites
21- 1: Send only on clicked links 23- `1`: Send only on clicked links
22- 2 (default): Send for links and images 24- `2` (default): Send for links and images
23 25
24`network.http.referer.XOriginPolicy` - Cross-domain origin policy 26`network.http.referer.XOriginPolicy` - Cross-domain origin policy
25- 0 (default): Always send 27
26- 1: Send if base domains match 28- `0` (default): Always send
27- 2: Send if hosts match 29- `1`: Send if base domains match
30- `2`: Send if hosts match
28 31
29`network.http.referer.spoofSource` - Referer spoofing (~faking) 32`network.http.referer.spoofSource` - Referer spoofing (~faking)
30- false (default): real referer 33
31- true: spoof referer (use target URI as referer) 34- `false` (default): real referer
32 - known to break some functionality in Shaarli 35- `true`: spoof referer (use target URI as referer)
36 - known to break some functionality in Shaarli
33 37
34`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer 38`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
35- 0 (default): send full URI 39
36- 1: scheme+host+port+path 40- `0`: (default): send full URI
37- 2: scheme+host+port 41- `1`: scheme+host+port+path
42- `2`: scheme+host+port
38 43
39### Firefox, localhost and redirections 44### Firefox, localhost and redirections
40 45
41`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. 46`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
47been set up to spoof referers, or only accept requests from the same base domain/host,
48Shaarli redirections will not work properly.
42 49
43To solve this, assign a local domain to your host, e.g. 50To solve this, assign a local domain to your host, e.g.
44``` 51```
@@ -73,17 +80,20 @@ Search for `failed` in this file to look for unauthorized login attempts.
73 80
74### Old PHP versions 81### Old PHP versions
75 82
76 * 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: 83On **free.fr**: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
84and so support now the tag autocompletion but you have to do the following.
85
86At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
77 87
78```ini 88```xml
79<IfDefine Free> 89<IfDefine Free>
80php56 1 90php56 1
81</IfDefine> 91</IfDefine>
82``` 92```
83 93
84 * 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` 94- 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`
85 * 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). 95- 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).
86 * 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: 96- 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:
87 97
88```php 98```php
89//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive. 99//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
@@ -91,8 +101,8 @@ php56 1
91//if (strpos($status,'200 OK')) $title=html_extract_title($data); 101//if (strpos($status,'200 OK')) $title=html_extract_title($data);
92``` 102```
93 103
94 * On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work. 104- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
95 * 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` 105- 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`
96 106
97### Dates are not properly formatted 107### Dates are not properly formatted
98 108
@@ -102,17 +112,16 @@ Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE h
102 112
103On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package. 113On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
104 114
105
106### My session expires! I can't stay logged in 115### My session expires! I can't stay logged in
107 116
108This can be caused by several things: 117This can be caused by several things:
109 118
110* 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. 119- 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.
111* 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 !) 120- 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 !)
112* 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). 121- 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).
113* Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those. 122- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
114* You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time. 123- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
115* If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions. 124- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
116 125
117## Sessions do not seem to work correctly on your server 126## Sessions do not seem to work correctly on your server
118 127
diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
index 19838721..d200634f 100644
--- a/doc/md/Unit-tests.md
+++ b/doc/md/Unit-tests.md
@@ -3,8 +3,9 @@
3The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool. 3The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
4 4
5Regarding Composer, you can either use: 5Regarding Composer, you can either use:
6* a system-wide version, e.g. installed through your distro's package manager 6
7* a local version, downloadable [here](https://getcomposer.org/download/) 7- a system-wide version, e.g. installed through your distro's package manager
8- a local version, downloadable [here](https://getcomposer.org/download/)
8 9
9#### Sample usage 10#### Sample usage
10 11
@@ -118,18 +119,20 @@ Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
118By default, PHPUnit will run all suitable tests found under the `tests` directory. 119By default, PHPUnit will run all suitable tests found under the `tests` directory.
119 120
120Each test has 3 possible outcomes: 121Each test has 3 possible outcomes:
121* `.` - success 122
122* `F` - failure: the test was run but its results are invalid 123- `.` - success
123 * the code does not behave as expected 124- `F` - failure: the test was run but its results are invalid
124 * dependencies to external elements: globals, session, cache... 125 - the code does not behave as expected
125* `E` - error: something went wrong and the tested code has crashed 126 - dependencies to external elements: globals, session, cache...
126 * typos in the code, or in the test code 127- `E` - error: something went wrong and the tested code has crashed
127 * dependencies to missing external elements 128 - typos in the code, or in the test code
129 - dependencies to missing external elements
128 130
129If Xdebug has been installed and activated, two coverage reports will be generated: 131If Xdebug has been installed and activated, two coverage reports will be generated:
130* a summary in the console 132
131* a detailed HTML report with metrics for tested code 133- a summary in the console
132 * to open it in a web browser: `firefox coverage/index.html &` 134- a detailed HTML report with metrics for tested code
135 - to open it in a web browser: `firefox coverage/index.html &`
133 136
134### Executing specific tests 137### Executing specific tests
135 138
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index 2002a4e2..b3a08764 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -8,6 +8,7 @@ The current version is present in the `version.php` file.
8### Backup your data 8### Backup your data
9 9
10Shaarli stores all user data under the `data` directory: 10Shaarli stores all user data under the `data` directory:
11
11- `data/config.php` - main configuration file 12- `data/config.php` - main configuration file
12- `data/datastore.php` - bookmarked links 13- `data/datastore.php` - bookmarked links
13- `data/ipbans.php` - banned IP addresses 14- `data/ipbans.php` - banned IP addresses
@@ -16,6 +17,7 @@ Shaarli stores all user data under the `data` directory:
16See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources. 17See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
17 18
18It is recommended to backup this repository _before_ starting updating/upgrading Shaarli: 19It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
20
19- users with SSH access: copy or archive the directory to a temporary location 21- users with SSH access: copy or archive the directory to a temporary location
20- users with FTP access: download a local copy of your Shaarli installation using your favourite client 22- users with FTP access: download a local copy of your Shaarli installation using your favourite client
21 23
@@ -75,6 +77,7 @@ Updating dependencies
75If 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. 77If 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.
76 78
77The following guide assumes that: 79The following guide assumes that:
80
78- 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) 81- 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)
79- the default remote is named `origin` and points to Sebsauvage's repository 82- the default remote is named `origin` and points to Sebsauvage's repository
80- the current branch is `master` 83- the current branch is `master`
@@ -174,7 +177,7 @@ After migrating, access your fresh Shaarli installation from a web browser; the
174 177
175## Troubleshooting 178## Troubleshooting
176 179
177If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to. 180If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
178 181
179### You must specify an integer as a key 182### You must specify an integer as a key
180 183
@@ -185,10 +188,10 @@ Take a look at `data/updates.txt` content.
185 188
186Try to delete it and refresh your page while being logged in. 189Try to delete it and refresh your page while being logged in.
187 190
188#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds` 191#### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
189 192
190 1. Create `data/updates.txt` if it doesn't exist. 1931. Create `data/updates.txt` if it doesn't exist
191 2. Paste this string in the update file `;updateMethodRenameDashTags;` 1942. Paste this string in the update file `;updateMethodRenameDashTags;`
192 3. Login to Shaarli. 1953. Login to Shaarli
193 4. Delete the update file. 1964. Delete the update file
194 5. Refresh. 1975. Refresh
diff --git a/doc/md/Various-hacks.md b/doc/md/Various-hacks.md
index a4ae81f4..0074ae9f 100644
--- a/doc/md/Various-hacks.md
+++ b/doc/md/Various-hacks.md
@@ -19,15 +19,15 @@ php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/
19 19
20### Changing the timestamp for a shaare 20### Changing the timestamp for a shaare
21 21
22* Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14) 22- Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
23* Replace `type="hidden"` with `type="text"` from this line 23- Replace `type="hidden"` with `type="text"` from this line
24* A new date/time field becomes available in the edit/new link dialog. 24- A new date/time field becomes available in the edit/new link dialog.
25* You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`. 25- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
26 26
27 27
28### See also 28### See also
29 29
30 * [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c) 30- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
31 * [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012) 31- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
32 * [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77) 32- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
33 * [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20) \ No newline at end of file 33- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)
diff --git a/doc/md/Versioning-and-Branches.md b/doc/md/Versioning-and-Branches.md
index e1d998e0..7097ca0a 100644
--- a/doc/md/Versioning-and-Branches.md
+++ b/doc/md/Versioning-and-Branches.md
@@ -8,10 +8,10 @@ The `master` branch is the development branch. Any new change MUST go through th
8 8
9Remarks: 9Remarks:
10 10
11 * This branch shouldn't be used for production as it isn't necessary stable. 11- This branch shouldn't be used for production as it isn't necessary stable.
12 * 3rd party aren't required to be compatible with the latest changes. 12- 3rd party aren't required to be compatible with the latest changes.
13 * Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch. 13- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
14 * The version in this branch is always `dev`. 14- The version in this branch is always `dev`.
15 15
16## `v0.x` branch 16## `v0.x` branch
17 17
@@ -37,7 +37,7 @@ For example, the current latest release is `v0.8.3`, the stable branch is an ali
37 37
38Remarks: 38Remarks:
39 39
40 * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release. 40- Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
41 41
42## Releases 42## Releases
43 43
diff --git a/doc/md/index.md b/doc/md/index.md
index 1106334b..b10e3cf4 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -80,7 +80,8 @@ See the [API documentation](http://shaarli.github.io/api-documentation/).
80 80
81### Other usages 81### Other usages
82Though Shaarli is primarily a bookmarking application, it can serve other purposes 82Though Shaarli is primarily a bookmarking application, it can serve other purposes
83(see [usage examples](https://github.com/shaarli/Shaarli/wiki#usage-examples)): 83(see [Features](Features)):
84
84- micro-blogging 85- micro-blogging
85- pastebin 86- pastebin
86- online notepad 87- online notepad
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-08 19:43:52 +0000