Knah-Tsaeb/MyShaarli
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

documentation: fix rendering and internal references

Browse source 
This is mainly cleanup after switching from Github-flavoured Markdown
rendered by Github Pages, to standard Markdown rendered by MkDocs.

Changed:
- rephrase some section titles

Fixed:
- list rendering (items, sub-items))
- code rendering
- quotes
- dead links

Removed:
- extraneous navigational elements

Signed-off-by: VirtualTam <virtualtam@flibidi.net>
This commit is contained in:
VirtualTam 2017-08-05 11:56:24 +02:00
parent b4ff0afb24
commit 43ad7c8e82
29 changed files with 373 additions and 323 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
doc/md/Backup,-restore,-import-and-export.md
View file

@ -1,11 +1,3 @@
* [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)
* [Export links as...](#export-links-as)
* [Import links from...](#import-links-from)
* [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)
----------------------
## Backup and restore the datastore file ## Backup and restore the datastore file
Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place. Backup 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 +
## Export links as... ## Export links as...
To export links as an HTML file, under _Tools > Export_, choose: To export links as an HTML file, under _Tools > Export_, choose:
- _Export all_ to export both public and private links - _Export all_ to export both public and private links
- _Export public_ to export public links only - _Export public_ to export public links only
- _Export private_ to export private links only - _Export private_ to export private links only
Restore by using the `Import` feature. Restore by using the `Import` feature.
* This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
Example command: Example command:
```bash ```bash
@ -46,18 +40,21 @@ To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sou
### Scuttle ### Scuttle
Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer. Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
## Import Shaarli links to Firefox ## Import Shaarli links to Firefox
* Export your Shaarli links as described above. - Export your Shaarli links as described above.
* For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)` - For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
* In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`) - In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
* Select `Import and Backup > Import bookmarks in HTML format` - Select `Import and Backup > Import bookmarks in HTML format`
Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time. Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
You may be interested in these Firefox addons to manage links imported from Shaarli You may be interested in these Firefox addons to manage links imported from Shaarli
* [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks - [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
* [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags - [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags

29
doc/md/Bookmarklet.md
View file

@ -1,23 +1,23 @@
### Add the sharing button (_bookmarklet_) to your browser ## Add the sharing button (_bookmarklet_) to your browser
* Open your Shaarli and `Login` - Open your Shaarli and `Login`
* Click the `Tools` button in the top bar - Click the `Tools` button in the top bar
* Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar. - Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._ _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._
![](images/bookmarklet.png) ![](images/bookmarklet.png)
### Share links using the _bookmarklet_ ## Share links using the _bookmarklet_
* When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added. - When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
* A window opens. - A window opens.
* You can freely edit title, description, tags... to find it later using the text search or tag filtering. - You can freely edit title, description, tags... to find it later using the text search or tag filtering.
* You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button. - You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.
* You can also check the “Private” box so that the link is saved but only visible to you. - You can also check the “Private” box so that the link is saved but only visible to you.
* Click `Save`.**Voilà! Your link is now shared.** - Click `Save`.**Voilà! Your link is now shared.**
### Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com) ## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it. Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
@ -25,6 +25,5 @@ See [#196](https://github.com/shaarli/Shaarli#196).
There is an open bug for both Firefox and Chromium: There is an open bug for both Firefox and Chromium:
* https://bugzilla.mozilla.org/show_bug.cgi?id=866522 - https://bugzilla.mozilla.org/show_bug.cgi?id=866522
* https://code.google.com/p/chromium/issues/detail?id=233903 - https://code.google.com/p/chromium/issues/detail?id=233903

1
doc/md/Coding-guidelines.md
View file

@ -1,5 +1,6 @@
## WIP ## WIP
This topic is currently being discussed here: This topic is currently being discussed here:
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95) - [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130) - [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)

18
doc/md/Community-&-Related-software.md
View file

@ -22,15 +22,15 @@ _TODO: contact repos owners to see if they'd like to standardize their work with
### Third party plugins ### Third party plugins
* [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown. - [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
* [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter. - [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
* [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli. - [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
* [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli. - [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
* [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support - [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
* [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli. - [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
* [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags. - [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
* [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks. - [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
* [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli - [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
### Themes ### Themes

4
doc/md/Continuous-integration-tools.md
View file

@ -1,22 +1,26 @@
## Local development ## Local development
A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations: A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
- Documentation - generate a local HTML copy of the GitHub wiki - Documentation - generate a local HTML copy of the GitHub wiki
- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions - [Static analysis](Static analysis) - check that the code is compliant to PHP conventions
- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits - [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits
## Automatic builds ## Automatic builds
[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build: [Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
- each time a commit is merged to the mainline (`master` branch) - each time a commit is merged to the mainline (`master` branch)
- each time a Pull Request is submitted or updated - each time a Pull Request is submitted or updated
A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)). A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
Each build job: Each build job:
- updates Composer - updates Composer
- installs 3rd-party test dependencies with Composer - installs 3rd-party test dependencies with Composer
- runs [Unit tests](Unit tests) - runs [Unit tests](Unit tests)
After all jobs have finished, Travis returns the results to GitHub: After all jobs have finished, Travis returns the results to GitHub:
- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli) - a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
- Pull Requests are updated with the Travis result - Pull Requests are updated with the Travis result
- Green: all tests have passed - Green: all tests have passed

1
doc/md/Development-guidelines.md
View file

@ -1,6 +1,7 @@
## Development guidelines ## Development guidelines
Please have a look at the following pages: Please have a look at the following pages:
- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) - [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: - [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard

33
doc/md/Download-and-Installation.md
View file

@ -1,8 +1,16 @@
To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your [server](Server-requirements) is properly [configured](Server-configuration). To install Shaarli, simply place the files in a directory under your webserver's
Document Root (or directly at the document root).
Also, please make sure your server meets the [requirements](Server-requirements)
and is properly [configured](Server-configuration).
Several releases are available: Several releases are available:
-------------------------------------------------------- - by downloading full release archives including all dependencies
- by downloading Github archives
- by cloning the Git repository
---
## Latest release (recommended) ## Latest release (recommended)
### Download as an archive ### Download as an archive
@ -20,19 +28,16 @@ $ unzip shaarli-v0.8.4-full.zip
$ mv Shaarli /path/to/shaarli/ $ mv Shaarli /path/to/shaarli/
``` ```
| ! |In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).| In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
|-----|--------------------------|
### Using git ### Using git
``` ```
mkdir -p /path/to/shaarli && cd /path/to/shaarli/ $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
git clone -b v0.8 https://github.com/shaarli/Shaarli.git . $ git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
composer install --no-dev $ composer install --no-dev --prefer-dist
``` ```
--------------------------------------------------------
## Stable version ## Stable version
The stable version has been experienced by Shaarli users, and will receive security updates. The stable version has been experienced by Shaarli users, and will receive security updates.
@ -63,11 +68,9 @@ $ mv Shaarli-stable /path/to/shaarli/
$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/ $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
# install/update third-party dependencies # install/update third-party dependencies
$ cd /path/to/shaarli/ $ cd /path/to/shaarli/
$ composer install --no-dev $ composer install --no-dev --prefer-dist
``` ```
--------------------------------------------------------
## Development version (mainline) ## Development version (mainline)
_Use at your own risk!_ _Use at your own risk!_
@ -79,11 +82,9 @@ To get the latest changes from the `master` branch:
$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
# install/update third-party dependencies # install/update third-party dependencies
$ cd /path/to/shaarli $ cd /path/to/shaarli
$ composer install --no-dev $ composer install --no-dev --prefer-dist
``` ```
--------------------------------------------------------
## Finish Installation ## Finish Installation
Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser. Once 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
Setup your Shaarli installation, and it's ready to use! Setup your Shaarli installation, and it's ready to use!
--------------------------------------------------------
## Updating Shaarli ## Updating Shaarli
See [Upgrade and Migration](Upgrade-and-migration) See [Upgrade and Migration](Upgrade-and-migration)

19
doc/md/FAQ.md
View file

@ -8,23 +8,24 @@ Enough is enough. Saving simple links should not be a complicated heavy thing. I
With Shaarli: With Shaarli:
* The data is yours: It's hosted on your server. - The data is yours: It's hosted on your server.
* Never fear of having your data locked-in. - Never fear of having your data locked-in.
* Never fear to have your data sold to third party. - Never fear to have your data sold to third party.
* Your private links are not hosted on a third party server. - Your private links are not hosted on a third party server.
* You are not tracked by browser addons (like Diigo does) - You are not tracked by browser addons (like Diigo does)
* You can change the look and feel of the pages if you want. - You can change the look and feel of the pages if you want.
* You can change the behaviour of the program. - You can change the behaviour of the program.
* It's magnitude faster than most bookmarking services. - It's magnitude faster than most bookmarking services.
### What does Shaarli mean? ### What does Shaarli mean?
Shaarli is for shaaring your links. Shaarli stands for _shaaring_ your _links_.
### My Shaarli is broken! ### My Shaarli is broken!
First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements). First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
If everything looks right but the issue(s) remain(s), please: If everything looks right but the issue(s) remain(s), please:
- take a look at the [troubleshooting](Troubleshooting) section - take a look at the [troubleshooting](Troubleshooting) section
- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-) - come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls) - browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)

39
doc/md/Features.md
View file

@ -1,24 +1,25 @@
### Main features ### Main features
Shaarli is intended: Shaarli is intended:
* to share, comment and save interesting links and news
* to bookmark useful/frequent personal links (as private links) and share them between computers - to share, comment and save interesting links and news
* as a minimal blog/microblog/writing platform (no character limit) - to bookmark useful/frequent personal links (as private links) and share them between computers
* as a read-it-later list (for example items tagged `readlater`) - as a minimal blog/microblog/writing platform (no character limit)
* to draft and save articles/ideas - as a read-it-later list (for example items tagged `readlater`)
* to keep code snippets - to draft and save articles/ideas
* to keep notes and documentation - to keep code snippets
* as a shared clipboard between machines - to keep notes and documentation
* as a todo list - as a shared clipboard between machines
* to store playlists (e.g. with the `music` or `video` tags) - as a todo list
* to keep extracts/comments from webpages that may disappear - to store playlists (e.g. with the `music` or `video` tags)
* to keep track of ongoing discussions (for example items tagged `discussion`) - to keep extracts/comments from webpages that may disappear
* [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags - to keep track of ongoing discussions (for example items tagged `discussion`)
* to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...) - [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
### Using Shaarli as a blog, notepad, pastebin... ### Using Shaarli as a blog, notepad, pastebin...
* Go to your Shaarli setup and log in - Go to your Shaarli setup and log in
* Click the `Add Link` button - Click the `Add Link` button
* To share text only, do not enter any URL in the corresponding input field and click `Add Link` - To share text only, do not enter any URL in the corresponding input field and click `Add Link`
* Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save` - Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
* Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink. - Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.

18
doc/md/Firefox-share.md
View file

@ -1,15 +1,17 @@
### Add Shaarli as a sharing service to Firefox ### Add Shaarli as a sharing service to Firefox
* Open your Shaarli and `Login` - Open your Shaarli and `Login`
* Click the `Tools` button in the top bar - Click the `Tools` button in the top bar
* Click the `✚Add to Firefox social` button and accept the activation. - Click the `✚Add to Firefox social` button and accept the activation.
### Sharing links using Firefox share ### Sharing links using Firefox share
* Add the sharing service as described above - Add the sharing service as described above
* When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png) - When you are visiting a webpage you would like to share with Shaarli,
* You can edit your link before and after saving, just like the bookmarklet above. click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
- You can edit your link before and after saving, just like the bookmarklet above.
|  | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections. | _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._

8
doc/md/GnuPG-signature.md
View file

@ -1,10 +1,11 @@
## Introduction ## Introduction
### PGP and GPG ### PGP and GPG
[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good [Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the
Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication, [Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
signature and encryption. (OpenPGP) specification. Its main purposes are digital authentication, signature and encryption.
It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify: It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master - Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
Keys](https://www.archlinux.org/master-keys/) Keys](https://www.archlinux.org/master-keys/)
- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity - [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
> 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. > You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see: Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:
- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html) - [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust) - [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)

160
doc/md/Plugin-System.md
View file

@ -1,6 +1,8 @@
[**I am a developer.** Developer API.](#developer-api) [**I am a developer: ** Developer API](#developer-api)
[**I am a template designer.** Guide for template designer.](#guide-for-template-designer) [**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
---
## Developer API ## Developer API
@ -8,9 +10,9 @@
The plugin system let you: The plugin system let you:
* insert content into specific places across templates. - insert content into specific places across templates.
* alter data before templates rendering. - alter data before templates rendering.
* alter data before saving new links. - alter data before saving new links.
### How can I create a plugin for Shaarli? ### How can I create a plugin for Shaarli?
@ -47,8 +49,8 @@ hook_<plugin_name>_<hook_name>($data, $conf)
Parameters: Parameters:
- data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data) - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
- conf: the `ConfigManager` instance. - conf: the `ConfigManager` instance.
For exemple, if my plugin want to add data to the header, this function is needed: For exemple, if my plugin want to add data to the header, this function is needed:
@ -106,9 +108,9 @@ Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file
Each file contain two keys: Each file contain two keys:
* `description`: plugin description - `description`: plugin description
* `parameters`: user parameter names, separated by a `;`. - `parameters`: user parameter names, separated by a `;`.
* `parameter.<PARAMETER_NAME>`: add a text description the specified parameter. - `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
@ -148,8 +150,8 @@ Allow plugin to add content in page headers.
`$data` is an array containing: `$data` is an array containing:
* `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). - `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders ##### Template placeholders
@ -157,11 +159,11 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `buttons_toolbar`: after the list of buttons in the header. - `buttons_toolbar`: after the list of buttons in the header.
![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png) ![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
* `fields_toolbar`: after search fields in the header. - `fields_toolbar`: after search fields in the header.
> Note: This will only be called in linklist. > Note: This will only be called in linklist.
@ -177,8 +179,8 @@ Allow plugin to include their own CSS files.
`$data` is an array containing: `$data` is an array containing:
* `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). - `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders ##### Template placeholders
@ -186,7 +188,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `css_files`: called after loading default CSS. - `css_files`: called after loading default CSS.
> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`. > Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
@ -200,8 +202,8 @@ Allow plugin to add content in page footer and include their own JS files.
`$data` is an array containing: `$data` is an array containing:
* `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). - `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
##### Template placeholders ##### Template placeholders
@ -209,12 +211,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `text`: called after the end of the footer text. - `text`: called after the end of the footer text.
* `endofpage`: called at the end of the page. - `endofpage`: called at the end of the page.
![text_example](http://i.imgur.com/L5S2YEH.png) ![text_example](http://i.imgur.com/L5S2YEH.png)
* `js_files`: called at the end of the page, to include custom JS scripts. - `js_files`: called at the end of the page, to include custom JS scripts.
> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`. > Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
@ -228,8 +230,8 @@ It allows to add content at the begining and end of the page, after every link d
`$data` is an array containing: `$data` is an array containing:
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
* All templates data, including links. - All templates data, including links.
##### Template placeholders ##### Template placeholders
@ -237,19 +239,19 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `action_plugin`: next to the button "private only" at the top and bottom of the page. - `action_plugin`: next to the button "private only" at the top and bottom of the page.
![action_plugin_example](http://i.imgur.com/Q12PWg0.png) ![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
* `link_plugin`: for every link, between permalink and link URL. - `link_plugin`: for every link, between permalink and link URL.
![link_plugin_example](http://i.imgur.com/3oDPhWx.png) ![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
* `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png) ![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
* `plugin_end_zone`: after displaying the template content. - `plugin_end_zone`: after displaying the template content.
![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png) ![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
@ -263,7 +265,7 @@ Allow to add fields in the form, or display elements.
`$data` is an array containing: `$data` is an array containing:
* All templates data. - All templates data.
##### Template placeholders ##### Template placeholders
@ -271,7 +273,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `edit_link_plugin`: after tags field. - `edit_link_plugin`: after tags field.
![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png) ![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
@ -285,7 +287,7 @@ Allow to add content at the end of the page.
`$data` is an array containing: `$data` is an array containing:
* All templates data. - All templates data.
##### Template placeholders ##### Template placeholders
@ -293,7 +295,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `tools_plugin`: at the end of the page. - `tools_plugin`: at the end of the page.
![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png) ![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
@ -307,8 +309,8 @@ Allow to add content at the top and bottom of the page.
`$data` is an array containing: `$data` is an array containing:
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
* All templates data. - All templates data.
##### Template placeholders ##### Template placeholders
@ -316,9 +318,8 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
* `plugin_end_zone`: after displaying the template content.
![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png) ![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
@ -332,8 +333,8 @@ Allow to add content at the top and bottom of the page.
`$data` is an array containing: `$data` is an array containing:
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
* All templates data. - All templates data.
##### Template placeholders ##### Template placeholders
@ -341,13 +342,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
* `plugin_end_zone`: after displaying the template content.
For each tag, the following placeholder can be used: For each tag, the following placeholder can be used:
* `tag_plugin`: after each tag - `tag_plugin`: after each tag
![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png) ![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
@ -362,8 +362,8 @@ Allow to add content at the top and bottom of the page.
`$data` is an array containing: `$data` is an array containing:
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
* All templates data. - All templates data.
##### Template placeholders ##### Template placeholders
@ -371,13 +371,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
* `plugin_end_zone`: after displaying the template content.
For each tag, the following placeholder can be used: For each tag, the following placeholder can be used:
* `tag_plugin`: after each tag - `tag_plugin`: after each tag
#### render_daily #### render_daily
@ -389,8 +388,8 @@ Allow to add content at the top and bottom of the page, the bottom of each link
`$data` is an array containing: `$data` is an array containing:
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
* All templates data, including links. - All templates data, including links.
##### Template placeholders ##### Template placeholders
@ -398,13 +397,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
List of placeholders: List of placeholders:
* `link_plugin`: used at bottom of each link. - `link_plugin`: used at bottom of each link.
![link_plugin_example](http://i.imgur.com/hzhMfSZ.png) ![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
* `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content.
* `plugin_end_zone`: after displaying the template content.
#### render_feed #### render_feed
@ -416,9 +414,9 @@ Allow to add tags in the feed, either in the header or for each items. Items (li
`$data` is an array containing: `$data` is an array containing:
* `_LOGGEDIN_`: true if user is logged in, false otherwise. - `_LOGGEDIN_`: true if user is logged in, false otherwise.
* `_PAGE_`: containing either `rss` or `atom`. - `_PAGE_`: containing either `rss` or `atom`.
* All templates data, including links. - All templates data, including links.
##### Template placeholders ##### Template placeholders
@ -426,11 +424,11 @@ Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
List of placeholders: List of placeholders:
* `feed_plugins_header`: used as a header tag in the feed. - `feed_plugins_header`: used as a header tag in the feed.
For each links: For each links:
* `feed_plugins`: additional tag for every link entry. - `feed_plugins`: additional tag for every link entry.
#### save_link #### save_link
@ -442,15 +440,15 @@ Allow to alter the link being saved in the datastore.
`$data` is an array containing the link being saved: `$data` is an array containing the link being saved:
* id - id
* title - title
* url - url
* shorturl - shorturl
* description - description
* private - private
* tags - tags
* created - created
* updated - updated
#### delete_link #### delete_link
@ -463,15 +461,15 @@ Allow to execute any action before the link is actually removed from the datasto
`$data` is an array containing the link being saved: `$data` is an array containing the link being saved:
* id - id
* title - title
* url - url
* shorturl - shorturl
* description - description
* private - private
* tags - tags
* created - created
* updated - updated
## Guide for template designer ## Guide for template designer
@ -485,9 +483,9 @@ Use the default one as an example.
Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if: Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
* you're using a table. - you're using a table.
* you call orderUp() and orderUp() onclick on arrows. - you call orderUp() and orderUp() onclick on arrows.
* you add data-line and data-order to your rows. - you add data-line and data-order to your rows.
Otherwise, you can use your own JS as long as this field is send by the form: Otherwise, you can use your own JS as long as this field is send by the form:

6
doc/md/Plugins.md
View file

@ -4,9 +4,9 @@ There is a bunch of plugins shipped with Shaarli, where there is nothing to do t
If you want to install a third party plugin: If you want to install a third party plugin:
* Download it. - Download it.
* Put it in the `plugins` directory in Shaarli's installation folder. - Put it in the `plugins` directory in Shaarli's installation folder.
* Make sure you put it correctly: - Make sure you put it correctly:
``` ```
| index.php | index.php

8
doc/md/REST-API.md
View file

@ -10,10 +10,10 @@ This token has to be included as an HTTP header called `Authentication: Bearer <
JWT resources : JWT resources :
* [jwt.io](https://jwt.io) (including a list of client per language). - [jwt.io](https://jwt.io) (including a list of client per language).
* RFC : https://tools.ietf.org/html/rfc7519 - RFC : https://tools.ietf.org/html/rfc7519
* https://float-middle.com/json-web-tokens-jwt-vs-sessions/ - https://float-middle.com/json-web-tokens-jwt-vs-sessions/
* HackerNews thread: https://news.ycombinator.com/item?id=11929267 - HackerNews thread: https://news.ycombinator.com/item?id=11929267
### Shaarli JWT Token ### Shaarli JWT Token

2
doc/md/RSS-feeds.md
View file

@ -3,6 +3,7 @@
Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`. Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
Options: Options:
- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL. - You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
- E.G. `https://my.shaarli.domain/?do=atom&permalinks`. - E.G. `https://my.shaarli.domain/?do=atom&permalinks`.
- You can use `nb` parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything. - 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:
It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**. It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**.
For example, if you want to subscribe only to links tagged `photography`: For example, if you want to subscribe only to links tagged `photography`:
- Go to the desired Shaarli instance. - Go to the desired Shaarli instance.
- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed. - Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
- Click on the `RSS Feed` button. - Click on the `RSS Feed` button.

6
doc/md/Release-Shaarli.md
View file

@ -3,6 +3,7 @@ releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Ta
## Prerequisites ## Prerequisites
This guide assumes that you have: This guide assumes that you have:
- a GPG key matching your GitHub authentication credentials - a GPG key matching your GitHub authentication credentials
- i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig` - i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
- a GitHub fork of Shaarli - a GitHub fork of Shaarli
@ -43,7 +44,7 @@ TBA
``` ```
## Increment the version code, updated docs, create and push a signed tag ## Increment the version code, update docs, create and push a signed tag
### Generate documentation ### Generate documentation
```bash ```bash
$ cd /path/to/shaarli $ cd /path/to/shaarli
@ -125,6 +126,7 @@ Update `README.md` so version badges display and point to the newly released Sha
### Create a GitHub release from a Git tag ### Create a GitHub release from a Git tag
From the previously drafted release: From the previously drafted release:
- edit the release notes (if needed) - edit the release notes (if needed)
- specify the appropriate Git tag - specify the appropriate Git tag
- publish the release - publish the release
@ -132,6 +134,7 @@ From the previously drafted release:
### Generate and upload all-in-one release archives ### Generate and upload all-in-one release archives
Users with a shared hosting may have: Users with a shared hosting may have:
- no SSH access - no SSH access
- no possibility to install PHP packages or server extensions - no possibility to install PHP packages or server extensions
- no possibility to run scripts - no possibility to run scripts
@ -146,6 +149,7 @@ $ make release_archive
``` ```
This will create the following archives: This will create the following archives:
- `shaarli-vX.Y.Z-full.tar` - `shaarli-vX.Y.Z-full.tar`
- `shaarli-vX.Y.Z-full.zip` - `shaarli-vX.Y.Z-full.zip`

31
doc/md/Security.md
View file

@ -1,27 +1,28 @@
## Client browser ## Client browser
* Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work - Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
## PHP ## PHP
* `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts. - `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts.
## Server and sessions ## Server and sessions
* Directories are protected using `.htaccess` files - Directories are protected using `.htaccess` files
* Forms are protected against XSRF (Cross-site requests forgery): - Forms are protected against XSRF (Cross-site requests forgery):
* Forms which act on data (save,delete…) contain a token generated by the server. - Forms which act on data (save,delete…) contain a token generated by the server.
* Any posted form which does not contain a valid token is rejected. - Any posted form which does not contain a valid token is rejected.
* Any token can only be used once. - Any token can only be used once.
* Tokens are attached to the session and cannot be reused in another session. - Tokens are attached to the session and cannot be reused in another session.
* Sessions automatically expire after 60 minutes. - Sessions automatically expire after 60 minutes.
* Sessions are protected against hijacking: the session ID cannot be used from a different IP address. - Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
## Shaarli datastore and configuration ## Shaarli datastore and configuration
* The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks. - The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
* Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file. - Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file.
* Even if the server does not support `.htaccess` files, the data file will still not be readable by URL. - Even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
* The database looks like this: - The database looks like this:
```php ```php
<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o... <?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?> ...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
``` ```
* 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 `@`. - 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 `@`.

42
doc/md/Server-configuration.md
View file

@ -5,23 +5,26 @@
## Prerequisites ## Prerequisites
### Shaarli ### Shaarli
* Shaarli is installed in a directory readable/writeable by the user - Shaarli is installed in a directory readable/writeable by the user
* the correct read/write permissions have been granted to the web server _user and/or group_ - the correct read/write permissions have been granted to the web server _user and/or group_
* for HTTPS / SSL: - for HTTPS / SSL:
* a key pair (public, private) and a certificate have been generated - a key pair (public, private) and a certificate have been generated
* the appropriate server SSL extension is installed and active - the appropriate server SSL extension is installed and active
### HTTPS, TLS and self-signed certificates ### HTTPS, TLS and self-signed certificates
Related guides: Related guides:
* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) - [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
* 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` - [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
- Generate a self-signed certificate (will trigger browser warnings) with apache2:
`make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
### Proxies ### Proxies
If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set: If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
- `X-Forwarded-Proto`;
- `X-Forwarded-Host`; - `X-Forwarded-Proto`
- `X-Forwarded-For`. - `X-Forwarded-Host`
- `X-Forwarded-For`
See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
@ -37,8 +40,9 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9
This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors. This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
See: See:
* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
* [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/) - [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
```apache ```apache
<VirtualHost *:80> <VirtualHost *:80>
@ -116,34 +120,41 @@ Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriti
Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources. Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
Required packages: Required packages:
- [nginx](http://nginx.org) - [nginx](http://nginx.org)
- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager - [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
Official documentation: Official documentation:
- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) - [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) - [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
- [Pitfalls](http://wiki.nginx.org/Pitfalls) - [Pitfalls](http://wiki.nginx.org/Pitfalls)
Community resources: Community resources:
- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla) - [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing) - [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
### Common setup ### Common setup
Once Nginx and PHP-FPM are installed, we need to ensure: Once Nginx and PHP-FPM are installed, we need to ensure:
- Nginx and PHP-FPM are running using the _same user and group_ - Nginx and PHP-FPM are running using the _same user and group_
- both these user and group have - both these user and group have
- `read` permissions for Shaarli resources - `read` permissions for Shaarli resources
- `execute` permissions for Shaarli directories _AND_ their parent directories - `execute` permissions for Shaarli directories _AND_ their parent directories
On a production server: On a production server:
- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data` - `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx` - files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
On a development server: On a development server:
- files may be located in a user's home directory - files may be located in a user's home directory
- in this case, make sure both Nginx and PHP-FPM are running as the local user/group! - in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
For all following configuration examples, this user/group pair will be used: For all following configuration examples, this user/group pair will be used:
- `user:group = john:users`, - `user:group = john:users`,
which corresponds to the following service configuration: which corresponds to the following service configuration:
@ -237,6 +248,7 @@ http {
### Modular ### Modular
The previous setup is sufficient for development purposes, but has several major caveats: The previous setup is sufficient for development purposes, but has several major caveats:
- every content that does not match the PHP rule will be sent to client browsers: - every content that does not match the PHP rule will be sent to client browsers:
- dotfiles - in our case, `.htaccess` - dotfiles - in our case, `.htaccess`
- temporary files, e.g. Vim or Emacs files: `index.php~` - temporary files, e.g. Vim or Emacs files: `index.php~`
@ -342,7 +354,9 @@ http {
``` ```
### Redirect HTTP to HTTPS ### Redirect HTTP to HTTPS
Assuming you have generated a (self-signed) key and certificate, and they are located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage. Assuming you have generated a (self-signed) key and certificate, and they are
located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
```nginx ```nginx
# /etc/nginx/nginx.conf # /etc/nginx/nginx.conf

12
doc/md/Server-requirements.md
View file

@ -10,12 +10,12 @@
### Supported versions ### Supported versions
Version | Status | Shaarli compatibility Version | Status | Shaarli compatibility
:---:|:---:|:---: :---:|:---:|:---:
7.1 | Supported (v0.9.x) | :white_check_mark: 7.1 | Supported (v0.9.x) | Yes
7.0 | Supported | :white_check_mark: 7.0 | Supported | Yes
5.6 | Supported | :white_check_mark: 5.6 | Supported | Yes
5.5 | EOL: 2016-07-10 | :white_check_mark: 5.5 | EOL: 2016-07-10 | Yes
5.4 | EOL: 2015-09-14 | :white_check_mark: (up to Shaarli 0.8.x) 5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
5.3 | EOL: 2014-08-14 | :white_check_mark: (up to Shaarli 0.8.x) 5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
See also: See also:
- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml) - [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)

5
doc/md/Server-security.md
View file

@ -1,5 +1,6 @@
## php.ini ## php.ini
PHP settings are defined in: PHP settings are defined in:
- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g. - a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
- `/etc/php5/php.ini` - used when running console scripts - `/etc/php5/php.ini` - used when running console scripts
- `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache - `/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
## fail2ban ## fail2ban
`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts: `fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page) - [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
- [Source code](https://github.com/fail2ban/fail2ban) - [Source code](https://github.com/fail2ban/fail2ban)
@ -68,6 +70,7 @@ Disallow: /
``` ```
See: See:
- http://www.robotstxt.org/
- http://www.robotstxt.org
- http://www.robotstxt.org/robotstxt.html - http://www.robotstxt.org/robotstxt.html
- http://www.robotstxt.org/meta.html - http://www.robotstxt.org/meta.html

82
doc/md/Shaarli-configuration.md
View file

@ -42,70 +42,70 @@ See also [Plugin System](Plugin-System.html).
### Credentials ### Credentials
> You shouldn't edit those. _These settings should not be edited_
**login**: Login username. - **login**: Login username.
**hash**: Generated password hash. - **hash**: Generated password hash.
**salt**: Password salt. - **salt**: Password salt.
### General ### General
**title**: Shaarli's instance title. - **title**: Shaarli's instance title.
**header_link**: Link to the homepage. - **header_link**: Link to the homepage.
**links_per_page**: Number of shaares displayed per page. - **links_per_page**: Number of shaares displayed per page.
**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). - **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
**enabled_plugins**: List of enabled plugins. - **enabled_plugins**: List of enabled plugins.
### Security ### Security
**session_protection_disabled**: Disable session cookie hijacking protection (not recommended). - **session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
It might be useful if your IP adress often changes. It might be useful if your IP adress often changes.
**ban_after**: Failed login attempts before being IP banned. - **ban_after**: Failed login attempts before being IP banned.
**ban_duration**: IP ban duration in seconds. - **ban_duration**: IP ban duration in seconds.
**open_shaarli**: Anyone can add a new link while logged out if enabled. - **open_shaarli**: Anyone can add a new link while logged out if enabled.
**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. - **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
**allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`). - **allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
### Resources ### Resources
**data_dir**: Data directory. - **data_dir**: Data directory.
**datastore**: Shaarli's links database file path. - **datastore**: Shaarli's links database file path.
**history**: Shaarli's operation history file path. - **history**: Shaarli's operation history file path.
**updates**: File path for the ran updates file. - **updates**: File path for the ran updates file.
**log**: Log file path. - **log**: Log file path.
**update_check**: Last update check file path. - **update_check**: Last update check file path.
**raintpl_tpl**: Templates directory. - **raintpl_tpl**: Templates directory.
**raintpl_tmp**: Template engine cache directory. - **raintpl_tmp**: Template engine cache directory.
**thumbnails_cache**: Thumbnails cache directory. - **thumbnails_cache**: Thumbnails cache directory.
**page_cache**: Shaarli's internal cache directory. - **page_cache**: Shaarli's internal cache directory.
**ban_file**: Banned IP file path. - **ban_file**: Banned IP file path.
### Updates ### Updates
**check_updates**: Enable or disable update check to the git repository. - **check_updates**: Enable or disable update check to the git repository.
**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`). - **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
**check_updates_interval**: Look for new version every N seconds (default: every day). - **check_updates_interval**: Look for new version every N seconds (default: every day).
### Privacy ### Privacy
**default_private_links**: Check the private checkbox by default for every new link. - **default_private_links**: Check the private checkbox by default for every new link.
**hide_public_links**: All links are hidden while logged out. - **hide_public_links**: All links are hidden while logged out.
**hide_timestamps**: Timestamps are hidden. - **hide_timestamps**: Timestamps are hidden.
### Feed ### Feed
**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL. - **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
**show_atom**: Display ATOM feed button. - **show_atom**: Display ATOM feed button.
### Thumbnail ### Thumbnail
**enable_thumbnails**: Enable or disable thumbnail display. - **enable_thumbnails**: Enable or disable thumbnail display.
**enable_localcache**: Enable or disable local cache. - **enable_localcache**: Enable or disable local cache.
### Redirector ### Redirector
**url**: Redirector URL, such as `anonym.to`. - **url**: Redirector URL, such as `anonym.to`.
**encode_url**: Enable this if the redirector needs encoded URL to work properly. - **encode_url**: Enable this if the redirector needs encoded URL to work properly.
## Configuration file example ## Configuration file example
@ -211,7 +211,7 @@ It might be useful if your IP adress often changes.
## Additional configuration ## Additional configuration
The playvideos plugin may require that you adapt your server's The `playvideos` plugin may require that you adapt your server's
[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) [Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
configuration to work properly.[](.html) configuration to work properly.

2
doc/md/Static-analysis.md
View file

@ -1,5 +1,6 @@
## WIP ## WIP
This topic is currently being discussed here: This topic is currently being discussed here:
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95) - [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130) - [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
@ -7,5 +8,6 @@ This topic is currently being discussed here:
Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile). Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
For an overview of the available features, see: For an overview of the available features, see:
- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124) - [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276) - [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)

5
doc/md/Theming.md
View file

@ -8,6 +8,7 @@ There are two ways of customizing how Shaarli looks:
## Custom CSS ## Custom CSS
Shaarli's appearance can be modified by adding CSS rules to: Shaarli's appearance can be modified by adding CSS rules to:
- Shaarli < `v0.9.0`: `inc/user.css` - Shaarli < `v0.9.0`: `inc/user.css`
- Shaarli >= `v0.9.0`: `data/user.css` - Shaarli >= `v0.9.0`: `data/user.css`
@ -22,6 +23,7 @@ See also [Download CSS styles from an OPML list](Download CSS styles from an OPM
_WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._ _WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._
Installation: Installation:
- find a theme you'd like to install - find a theme you'd like to install
- copy or clone the theme folder under `tpl/<a_sweet_theme>` - copy or clone the theme folder under `tpl/<a_sweet_theme>`
- enable the theme: - enable the theme:
@ -54,6 +56,7 @@ Installation:
## Example installation: AlbinoMouse theme ## Example installation: AlbinoMouse theme
With the following configuration: With the following configuration:
- Apache 2 / PHP 5.6 - Apache 2 / PHP 5.6
- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir` - user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
- `http` is the name of the Apache user - `http` is the name of the Apache user
@ -77,7 +80,7 @@ Get config written:
- fill the install form - fill the install form
- log in to Shaarli - log in to Shaarli
Edit Shaarli's [configuration|Shaarli configuration](configuration|Shaarli configuration): Edit Shaarli's [configuration](Shaarli-configuration):
```bash ```bash
# the file should be owned by Apache, thus not writeable => sudo # the file should be owned by Apache, thus not writeable => sudo
$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php $ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php

63
doc/md/Troubleshooting.md
View file

@ -7,6 +7,7 @@
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages. Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
See: See:
- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia) - [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/) - [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/) - [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
@ -16,29 +17,35 @@ See:
HTTP settings are available by browsing `about:config`, here are the available settings and their values. HTTP settings are available by browsing `about:config`, here are the available settings and their values.
`network.http.sendRefererHeader` - determines when to send the Referer HTTP header `network.http.sendRefererHeader` - determines when to send the Referer HTTP header
- 0: Never send the referring URL
- `0`: Never send the referring URL
- not recommended, may break some sites - not recommended, may break some sites
- 1: Send only on clicked links - `1`: Send only on clicked links
- 2 (default): Send for links and images - `2` (default): Send for links and images
`network.http.referer.XOriginPolicy` - Cross-domain origin policy `network.http.referer.XOriginPolicy` - Cross-domain origin policy
- 0 (default): Always send
- 1: Send if base domains match - `0` (default): Always send
- 2: Send if hosts match - `1`: Send if base domains match
- `2`: Send if hosts match
`network.http.referer.spoofSource` - Referer spoofing (~faking) `network.http.referer.spoofSource` - Referer spoofing (~faking)
- false (default): real referer
- true: spoof referer (use target URI as referer) - `false` (default): real referer
- known to break some functionality in Shaarli - `true`: spoof referer (use target URI as referer)
- known to break some functionality in Shaarli
`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer `network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
- 0 (default): send full URI
- 1: scheme+host+port+path - `0`: (default): send full URI
- 2: scheme+host+port - `1`: scheme+host+port+path
- `2`: scheme+host+port
### Firefox, localhost and redirections ### Firefox, localhost and redirections
`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly. `localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
been set up to spoof referers, or only accept requests from the same base domain/host,
Shaarli redirections will not work properly.
To solve this, assign a local domain to your host, e.g. To solve this, assign a local domain to your host, e.g.
``` ```
@ -73,17 +80,20 @@ Search for `failed` in this file to look for unauthorized login attempts.
### Old PHP versions ### Old PHP versions
* On **free.fr** : free.fr now support php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a `sessions` directory and a `.htaccess` file containing: On **free.fr**: free.fr now supports 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.
```ini At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
```xml
<IfDefine Free> <IfDefine Free>
php56 1 php56 1
</IfDefine> </IfDefine>
``` ```
* If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5` - If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
* On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP). - On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
* If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines: - If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
```php ```php
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive. //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
@ -91,8 +101,8 @@ php56 1
//if (strpos($status,'200 OK')) $title=html_extract_title($data); //if (strpos($status,'200 OK')) $title=html_extract_title($data);
``` ```
* On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work. - On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
* On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php` - On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
### Dates are not properly formatted ### Dates are not properly formatted
@ -102,17 +112,16 @@ Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE h
On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package. On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
### My session expires! I can't stay logged in ### My session expires! I can't stay logged in
This can be caused by several things: This can be caused by several things:
* Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up. - Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
* Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !) - Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
* If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses). - If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
* Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those. - Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
* You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time. - You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
* If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions. - If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
## Sessions do not seem to work correctly on your server ## Sessions do not seem to work correctly on your server

27
doc/md/Unit-tests.md
View file

@ -3,8 +3,9 @@
The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool. The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
Regarding Composer, you can either use: Regarding Composer, you can either use:
* a system-wide version, e.g. installed through your distro's package manager
* a local version, downloadable [here](https://getcomposer.org/download/) - a system-wide version, e.g. installed through your distro's package manager
- a local version, downloadable [here](https://getcomposer.org/download/)
#### Sample usage #### Sample usage
@ -118,18 +119,20 @@ Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
By default, PHPUnit will run all suitable tests found under the `tests` directory. By default, PHPUnit will run all suitable tests found under the `tests` directory.
Each test has 3 possible outcomes: Each test has 3 possible outcomes:
* `.` - success
* `F` - failure: the test was run but its results are invalid - `.` - success
* the code does not behave as expected - `F` - failure: the test was run but its results are invalid
* dependencies to external elements: globals, session, cache... - the code does not behave as expected
* `E` - error: something went wrong and the tested code has crashed - dependencies to external elements: globals, session, cache...
* typos in the code, or in the test code - `E` - error: something went wrong and the tested code has crashed
* dependencies to missing external elements - typos in the code, or in the test code
- dependencies to missing external elements
If Xdebug has been installed and activated, two coverage reports will be generated: If Xdebug has been installed and activated, two coverage reports will be generated:
* a summary in the console
* a detailed HTML report with metrics for tested code - a summary in the console
* to open it in a web browser: `firefox coverage/index.html &` - a detailed HTML report with metrics for tested code
- to open it in a web browser: `firefox coverage/index.html &`
### Executing specific tests ### Executing specific tests

17
doc/md/Upgrade-and-migration.md
View file

@ -8,6 +8,7 @@ The current version is present in the `version.php` file.
### Backup your data ### Backup your data
Shaarli stores all user data under the `data` directory: Shaarli stores all user data under the `data` directory:
- `data/config.php` - main configuration file - `data/config.php` - main configuration file
- `data/datastore.php` - bookmarked links - `data/datastore.php` - bookmarked links
- `data/ipbans.php` - banned IP addresses - `data/ipbans.php` - banned IP addresses
@ -16,6 +17,7 @@ Shaarli stores all user data under the `data` directory:
See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources. See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
It is recommended to backup this repository _before_ starting updating/upgrading Shaarli: It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
- users with SSH access: copy or archive the directory to a temporary location - users with SSH access: copy or archive the directory to a temporary location
- users with FTP access: download a local copy of your Shaarli installation using your favourite client - users with FTP access: download a local copy of your Shaarli installation using your favourite client
@ -75,6 +77,7 @@ Updating dependencies
If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy. If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
The following guide assumes that: The following guide assumes that:
- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) - you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
- the default remote is named `origin` and points to Sebsauvage's repository - the default remote is named `origin` and points to Sebsauvage's repository
- the current branch is `master` - the current branch is `master`
@ -174,7 +177,7 @@ After migrating, access your fresh Shaarli installation from a web browser; the
## Troubleshooting ## Troubleshooting
If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to. If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
### You must specify an integer as a key ### You must specify an integer as a key
@ -185,10 +188,10 @@ Take a look at `data/updates.txt` content.
Try to delete it and refresh your page while being logged in. Try to delete it and refresh your page while being logged in.
#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds` #### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
1. Create `data/updates.txt` if it doesn't exist. 1. Create `data/updates.txt` if it doesn't exist
2. Paste this string in the update file `;updateMethodRenameDashTags;` 2. Paste this string in the update file `;updateMethodRenameDashTags;`
3. Login to Shaarli. 3. Login to Shaarli
4. Delete the update file. 4. Delete the update file
5. Refresh. 5. Refresh

16
doc/md/Various-hacks.md
View file

@ -19,15 +19,15 @@ php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/
### Changing the timestamp for a shaare ### Changing the timestamp for a shaare
* Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14) - Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
* Replace `type="hidden"` with `type="text"` from this line - Replace `type="hidden"` with `type="text"` from this line
* A new date/time field becomes available in the edit/new link dialog. - A new date/time field becomes available in the edit/new link dialog.
* You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`. - You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
### See also ### See also
* [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c) - [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
* [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012) - [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
* [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77) - [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
* [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20) - [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)

10
doc/md/Versioning-and-Branches.md
View file

@ -8,10 +8,10 @@ The `master` branch is the development branch. Any new change MUST go through th
Remarks: Remarks:
* This branch shouldn't be used for production as it isn't necessary stable. - This branch shouldn't be used for production as it isn't necessary stable.
* 3rd party aren't required to be compatible with the latest changes. - 3rd party aren't required to be compatible with the latest changes.
* Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch. - Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
* The version in this branch is always `dev`. - The version in this branch is always `dev`.
## `v0.x` branch ## `v0.x` branch
@ -37,7 +37,7 @@ For example, the current latest release is `v0.8.3`, the stable branch is an ali
Remarks: Remarks:
* Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release. - Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
## Releases ## Releases

3
doc/md/index.md
View file

@ -80,7 +80,8 @@ See the [API documentation](http://shaarli.github.io/api-documentation/).
### Other usages ### Other usages
Though Shaarli is primarily a bookmarking application, it can serve other purposes Though Shaarli is primarily a bookmarking application, it can serve other purposes
(see [usage examples](https://github.com/shaarli/Shaarli/wiki#usage-examples)): (see [Features](Features)):
- micro-blogging - micro-blogging
- pastebin - pastebin
- online notepad - online notepad