aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md')
-rw-r--r--doc/md/3rd-party-libraries.md13
-rw-r--r--doc/md/Backup,-restore,-import-and-export.md60
-rw-r--r--doc/md/Bookmarklet.md29
-rw-r--r--doc/md/Browsing-and-searching.md23
-rw-r--r--doc/md/Community-&-Related-software.md67
-rw-r--r--doc/md/Continuous-integration-tools.md28
-rw-r--r--doc/md/Development-guidelines.md10
-rw-r--r--doc/md/Directory-structure.md34
-rw-r--r--doc/md/Download-and-Installation.md98
-rw-r--r--doc/md/FAQ.md44
-rw-r--r--doc/md/Features.md25
-rw-r--r--doc/md/Firefox-share.md17
-rw-r--r--doc/md/GnuPG-signature.md78
-rw-r--r--doc/md/Plugin-System.md708
-rw-r--r--doc/md/Plugins.md75
-rw-r--r--doc/md/REST-API.md153
-rw-r--r--doc/md/RSS-feeds.md28
-rw-r--r--doc/md/Release-Shaarli.md155
-rw-r--r--doc/md/Security.md28
-rw-r--r--doc/md/Server-configuration.md406
-rw-r--r--doc/md/Server-requirements.md41
-rw-r--r--doc/md/Server-security.md76
-rw-r--r--doc/md/Shaarli-configuration.md217
-rw-r--r--doc/md/Static-analysis.md13
-rw-r--r--doc/md/Theming.md85
-rw-r--r--doc/md/Troubleshooting.md132
-rw-r--r--doc/md/Unit-tests.md155
-rw-r--r--doc/md/Upgrade-and-migration.md197
-rw-r--r--doc/md/Various-hacks.md33
-rw-r--r--doc/md/Versioning-and-Branches.md75
-rw-r--r--doc/md/docker/docker-101.md62
-rw-r--r--doc/md/docker/resources.md19
-rw-r--r--doc/md/docker/reverse-proxy-configuration.md6
-rw-r--r--doc/md/docker/shaarli-images.md71
-rw-r--r--doc/md/images/bookmarklet.pngbin0 -> 53346 bytes
-rw-r--r--doc/md/images/doc-logo.pngbin0 -> 19543 bytes
-rw-r--r--doc/md/images/doc-logo.svg522
-rw-r--r--doc/md/images/firefoxshare.pngbin0 -> 757 bytes
-rw-r--r--doc/md/images/rss-filter-1.pngbin0 -> 18682 bytes
-rw-r--r--doc/md/images/rss-filter-2.pngbin0 -> 15604 bytes
-rw-r--r--doc/md/index.md115
41 files changed, 3898 insertions, 0 deletions
diff --git a/doc/md/3rd-party-libraries.md b/doc/md/3rd-party-libraries.md
new file mode 100644
index 00000000..ebab7a46
--- /dev/null
+++ b/doc/md/3rd-party-libraries.md
@@ -0,0 +1,13 @@
1## CSS
2- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/)
3 - resets default CSS properties for all HTML elements (overriding browsers' default values)
4 - ensures custom CSS stylessheets will provide the same results on all browsers
5
6## Javascript
7- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
8- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
9- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
10
11## PHP
12- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser
13- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP
diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/Backup,-restore,-import-and-export.md
new file mode 100644
index 00000000..89724857
--- /dev/null
+++ b/doc/md/Backup,-restore,-import-and-export.md
@@ -0,0 +1,60 @@
1## Backup and restore the datastore file
2
3Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place.
4
5Example command:
6```bash
7rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php
8```
9
10## Export links as...
11
12To export links as an HTML file, under _Tools > Export_, choose:
13
14- _Export all_ to export both public and private links
15- _Export public_ to export public links only
16- _Export private_ to export private links only
17
18Restore by using the `Import` feature.
19
20- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
21
22Example command:
23```bash
24./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all
25```
26
27## Import links from...
28
29### Diigo
30
31If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.)
32
33### Mister Wong
34
35See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks.
36
37### SemanticScuttle
38
39To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).
40
41### Scuttle
42
43Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
44
45However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
46tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
47
48## Import Shaarli links to Firefox
49
50- Export your Shaarli links as described above.
51 - For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
52- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
53- Select `Import and Backup > Import bookmarks in HTML format`
54
55Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
56
57You may be interested in these Firefox addons to manage links imported from Shaarli
58
59- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
60- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
diff --git a/doc/md/Bookmarklet.md b/doc/md/Bookmarklet.md
new file mode 100644
index 00000000..e53e3261
--- /dev/null
+++ b/doc/md/Bookmarklet.md
@@ -0,0 +1,29 @@
1## Add the sharing button (_bookmarklet_) to your browser
2
3- Open your Shaarli and `Login`
4- Click the `Tools` button in the top bar
5- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
6
7_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._
8
9![](images/bookmarklet.png)
10
11## Share links using the _bookmarklet_
12
13- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
14- A window opens.
15 - You can freely edit title, description, tags... to find it later using the text search or tag filtering.
16 - You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.
17 - You can also check the “Private” box so that the link is saved but only visible to you.
18- Click `Save`.**Voilà! Your link is now shared.**
19
20## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
21
22Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
23
24See [#196](https://github.com/shaarli/Shaarli#196).
25
26There is an open bug for both Firefox and Chromium:
27
28- https://bugzilla.mozilla.org/show_bug.cgi?id=866522
29- https://code.google.com/p/chromium/issues/detail?id=233903
diff --git a/doc/md/Browsing-and-searching.md b/doc/md/Browsing-and-searching.md
new file mode 100644
index 00000000..35707482
--- /dev/null
+++ b/doc/md/Browsing-and-searching.md
@@ -0,0 +1,23 @@
1## Plain text search
2
3Use the `Search text` field to search in _any_ of the fields of all links (Title, URL, Description...)
4
5**Exclude text/tags:** Use the `-` operator before a word or tag (example `-uninteresting`) to prevent entries containing (or tagged) `uninteresting` from showing up in the search results.
6
7**Exact text search:** Use double-quotes (example `"exact search"`) to search for the exact expression.
8
9Both exclude patterns and exact searches can be combined with normal searches (example `"exact search" term otherterm -notthis "very exact" stuff -notagain`)
10
11## Tags search
12
13Use the `Filter by tags` field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).
14
15**Hidden tags:** Tags starting with a dot `.` (example `.secret`) are private. They can only be seen and searched when logged in.
16
17Alternatively you can use the `Tag cloud` to discover all tags and click on any of them to display related links.
18
19To search for links that are not tagged, enter `""` in the tag search field.
20
21## Filtering RSS feeds/Picture wall
22
23RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS feeds).
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
new file mode 100644
index 00000000..8edbeefa
--- /dev/null
+++ b/doc/md/Community-&-Related-software.md
@@ -0,0 +1,67 @@
1_Unofficial but related work on Shaarli. If you maintain one of these,
2please get in touch with us to help us find a way to adapt your work to our fork._
3
4## Community
5- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli
6- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
7- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
8- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
9- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
10- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
11- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
12- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
13- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
14
15
16### Articles and social media discussions
17- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176
18- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)
19- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366
20- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)
21
22
23### REST API clients
24See [REST API](REST-API) for a list of official and community clients.
25
26
27### Third party plugins
28- [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.
29- [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
30- [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
31- [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
32- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
33- [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
34- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
35- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
36- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
37
38
39### Third-party themes
40See [Theming](Theming) for a list of community-contributed themes, and an installation guide.
41
42
43## Integration with other platforms
44- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
45- [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar
46- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle
47
48
49### Mobile Apps
50- [ShaarliOS](https://github.com/mro/ShaarliOS) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes,
51- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
52- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
53
54
55### Server apps
56- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
57- [shaarli-river](https://github.com/mknexen/shaarli-river) - An aggregator for shaarlis with many features
58- [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among French shaarliers: [shaarli.fr](http://shaarli.fr/))
59- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
60- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
61- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
62- [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
63
64
65## Alternatives to Shaarli
66See the [bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing)
67section on [awesome-selfhosted](https://github.com/Kickball/awesome-selfhosted/).
diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md
new file mode 100644
index 00000000..4bd7a0ba
--- /dev/null
+++ b/doc/md/Continuous-integration-tools.md
@@ -0,0 +1,28 @@
1## Local development
2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
3
4- Documentation - generate a local HTML copy of the GitHub wiki
5- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions
6- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits
7
8## Automatic builds
9[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
10
11- each time a commit is merged to the mainline (`master` branch)
12- each time a Pull Request is submitted or updated
13
14A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
15
16Each build job:
17
18- updates Composer
19- installs 3rd-party test dependencies with Composer
20- runs [Unit tests](Unit tests)
21
22After all jobs have finished, Travis returns the results to GitHub:
23
24- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
25- Pull Requests are updated with the Travis result
26 - Green: all tests have passed
27 - Red: some tests failed
28 - Orange: tests are pending
diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md
new file mode 100644
index 00000000..532ec2e4
--- /dev/null
+++ b/doc/md/Development-guidelines.md
@@ -0,0 +1,10 @@
1## Development guidelines
2
3Please have a look at the following pages:
4
5- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
6- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
7 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
8 - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
9- [Unit tests](Unit tests)
10- [GnuPG signature](GnuPG signature) for tags/releases
diff --git a/doc/md/Directory-structure.md b/doc/md/Directory-structure.md
new file mode 100644
index 00000000..eb50965b
--- /dev/null
+++ b/doc/md/Directory-structure.md
@@ -0,0 +1,34 @@
1TODO: This page is out of date
2
3Here is the directory structure of Shaarli and the purpose of the different files:
4
5```bash
6 index.php # Main program
7 application/ # Shaarli classes
8 ├── LinkDB.php
9 └── Utils.php
10 tests/ # Shaarli unitary & functional tests
11 ├── LinkDBTest.php
12 ├── utils # utilities to ease testing
13 │ └── ReferenceLinkDB.php
14 └── UtilsTest.php
15 COPYING # Shaarli license
16 inc/ # static assets and 3rd party libraries
17 ├── awesomplete.* # tags autocompletion library
18 ├── blazy.* # picture wall lazy image loading library
19 ├── shaarli.css, reset.css # Shaarli stylesheet.
20 ├── qr.* # qr code generation library
21 └──rain.tpl.class.php # RainTPL templating library
22 tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
23 images/ # Images and icons used in Shaarli
24 data/ # data storage: bookmark database, configuration, logs, banlist…
25 ├── config.php # Shaarli configuration (login, password, timezone, title…)
26 ├── datastore.php # Your link database (compressed).
27 ├── ipban.php # IP address ban system data
28 ├── lastupdatecheck.txt # Update check timestamp file
29 └──log.txt # login/IPban log.
30 cache/ # thumbnails cache
31 # This directory is automatically created. You can erase it anytime you want.
32 tmp/ # Temporary directory for compiled RainTPL templates.
33 # This directory is automatically created. You can erase it anytime you want.
34```
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
new file mode 100644
index 00000000..135f0633
--- /dev/null
+++ b/doc/md/Download-and-Installation.md
@@ -0,0 +1,98 @@
1To install Shaarli, simply place the files in a directory under your webserver's
2Document Root (or directly at the document root).
3
4Also, please make sure your server meets the [requirements](Server-requirements)
5and is properly [configured](Server-configuration).
6
7Several releases are available:
8
9- by downloading full release archives including all dependencies
10- by downloading Github archives
11- by cloning the Git repository
12
13---
14
15## Latest release (recommended)
16### Download as an archive
17Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.
18
19**Download our *shaarli-full* archive** to include dependencies.
20
21The current latest released version is `v0.9.0`
22
23Or in command lines:
24
25```bash
26$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.0/shaarli-v0.9.0-full.zip
27$ unzip shaarli-v0.9.0-full.zip
28$ mv Shaarli /path/to/shaarli/
29```
30
31In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
32
33### Using git
34
35```
36$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
37$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
38$ composer install --no-dev --prefer-dist
39```
40
41## Stable version
42
43The stable version has been experienced by Shaarli users, and will receive security updates.
44
45### Download as an archive
46
47As a .zip archive:
48
49```bash
50$ wget https://github.com/shaarli/Shaarli/archive/stable.zip
51$ unzip stable.zip
52$ mv Shaarli-stable /path/to/shaarli/
53```
54
55As a .tar.gz archive :
56
57```bash
58$ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz
59$ tar xvf stable.tar.gz
60$ mv Shaarli-stable /path/to/shaarli/
61```
62
63### Clone with Git
64
65[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.
66
67```bash
68$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
69# install/update third-party dependencies
70$ cd /path/to/shaarli/
71$ composer install --no-dev --prefer-dist
72```
73
74## Development version (mainline)
75
76_Use at your own risk!_
77
78To get the latest changes from the `master` branch:
79
80```bash
81# clone the repository
82$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
83# install/update third-party dependencies
84$ cd /path/to/shaarli
85$ composer install --no-dev --prefer-dist
86```
87
88## Finish Installation
89
90Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
91
92![install screenshot](http://i.imgur.com/wuMpDSN.png)
93
94Setup your Shaarli installation, and it's ready to use!
95
96## Updating Shaarli
97
98See [Upgrade and Migration](Upgrade-and-migration)
diff --git a/doc/md/FAQ.md b/doc/md/FAQ.md
new file mode 100644
index 00000000..77faf117
--- /dev/null
+++ b/doc/md/FAQ.md
@@ -0,0 +1,44 @@
1### Why did you create Shaarli ?
2
3I was a StumbleUpon user. Then I got fed up with they big toolbar. I switched to delicious, which was lighter, faster and more beautiful. Until Yahoo bought it. Then the export API broke all the time, delicious became slow and was ditched by Yahoo. I switched to Diigo, which is not bad, but does too much. And Diigo is sslllooooowww and their Firefox extension a bit buggy. And… oh… **their Firefox addon sends to Diigo every single URL you visit** (Don't believe me ? Use [Tamper Data](https://addons.mozilla.org/en-US/firefox/addon/tamper-data/) and open any page).
4
5Enough is enough. Saving simple links should not be a complicated heavy thing. I ditched them all and wrote my own: Shaarli. It's simple, but it does the job and does it well. And my data is not hosted on a foreign server, but on my server.
6
7### Why use Shaarli and not Delicious/Diigo ?
8
9With Shaarli:
10
11- The data is yours: It's hosted on your server.
12- Never fear of having your data locked-in.
13- Never fear to have your data sold to third party.
14- Your private links are not hosted on a third party server.
15- You are not tracked by browser addons (like Diigo does)
16- You can change the look and feel of the pages if you want.
17- You can change the behaviour of the program.
18- It's magnitude faster than most bookmarking services.
19
20### What does Shaarli mean?
21
22Shaarli stands for _shaaring_ your _links_.
23
24### My Shaarli is broken!
25First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
26
27If everything looks right but the issue(s) remain(s), please:
28
29- take a look at the [troubleshooting](Troubleshooting) section
30- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
31- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
32 - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup)
33 - else, [open a new issue](https://github.com/shaarli/Shaarli/issues/new), and provide information about the problem:
34 - _what happens?_ - display glitches, invalid data, security flaws...
35 - _what is your configuration?_ - OS, server version, activated extensions, web browser...
36 - _is it reproducible?_
37
38### Why not use a real database? Files are slow!
39
40Does browsing [this page](http://sebsauvage.net/links/) feel slow? Try browsing older pages, too.
41
42It's not slow at all, is it? And don't forget the database contains more than 16000 links, and it's on a shared host, with 32000 visitors/day for my website alone. And it's still damn fast. Why?
43
44The data file is only 3.7 Mb. It's read 99% of the time, and is probably already in the operation system disk cache. So generating a page involves no I/O at all most of the time.
diff --git a/doc/md/Features.md b/doc/md/Features.md
new file mode 100644
index 00000000..eef88d03
--- /dev/null
+++ b/doc/md/Features.md
@@ -0,0 +1,25 @@
1### Main features
2Shaarli is intended:
3
4- to share, comment and save interesting links and news
5- to bookmark useful/frequent personal links (as private links) and share them between computers
6- as a minimal blog/microblog/writing platform (no character limit)
7- as a read-it-later list (for example items tagged `readlater`)
8- to draft and save articles/ideas
9- to keep code snippets
10- to keep notes and documentation
11- as a shared clipboard between machines
12- as a todo list
13- to store playlists (e.g. with the `music` or `video` tags)
14- to keep extracts/comments from webpages that may disappear
15- to keep track of ongoing discussions (for example items tagged `discussion`)
16- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
17- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
18
19### Using Shaarli as a blog, notepad, pastebin...
20
21- Go to your Shaarli setup and log in
22- Click the `Add Link` button
23- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
24- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
25- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
diff --git a/doc/md/Firefox-share.md b/doc/md/Firefox-share.md
new file mode 100644
index 00000000..878884a4
--- /dev/null
+++ b/doc/md/Firefox-share.md
@@ -0,0 +1,17 @@
1### Add Shaarli as a sharing service to Firefox
2
3- Open your Shaarli and `Login`
4- Click the `Tools` button in the top bar
5- Click the `✚Add to Firefox social` button and accept the activation.
6
7
8### Sharing links using Firefox share
9
10- Add the sharing service as described above
11- When you are visiting a webpage you would like to share with Shaarli,
12 click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
13- You can edit your link before and after saving, just like the bookmarklet above.
14
15_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection)
16enabled server for Firefox Share to work. Firefox Share will not work over
17plain HTTP connections._
diff --git a/doc/md/GnuPG-signature.md b/doc/md/GnuPG-signature.md
new file mode 100644
index 00000000..d1fc10a5
--- /dev/null
+++ b/doc/md/GnuPG-signature.md
@@ -0,0 +1,78 @@
1## Introduction
2### PGP and GPG
3[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the
4[Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
5(OpenPGP) specification. Its main purposes are digital authentication, signature and encryption.
6
7It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
8
9- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
10Keys](https://www.archlinux.org/master-keys/)
11- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
12
13### Trust
14To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/):
15
16> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
17
18Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:
19
20- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
21- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)
22
23## Generate a GPG key
24- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)
25- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)
26
27### gpg - provide identity information
28```bash
29$ gpg --gen-key
30
31gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
32This is free software: you are free to change and redistribute it.
33There is NO WARRANTY, to the extent permitted by law.
34
35Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
36
37GnuPG needs to construct a user ID to identify your key.
38
39Real name: Marvin the Paranoid Android
40Email address: marvin@h2g2.net
41You selected this USER-ID:
42 "Marvin the Paranoid Android <marvin@h2g2.net>"
43
44Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
45We need to generate a lot of random bytes. It is a good idea to perform
46some other action (type on the keyboard, move the mouse, utilize the
47disks) during the prime generation; this gives the random number
48generator a better chance to gain enough entropy.
49```
50
51### gpg - entropy interlude
52At this point, you will:
53- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
54- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step _may take some time_
55
56### gpg - key creation confirmation
57```bash
58gpg: key A9D53A3E marked as ultimately trusted
59public and secret key created and signed.
60
61gpg: checking the trustdb
62gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
63gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
64pub rsa2048/A9D53A3E 2015-07-31
65 Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
66uid [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>
67sub rsa2048/8C0EACF1 2015-07-31
68```
69
70### gpg - submit your public key to a PGP server (Optional)
71``` bash
72$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
73gpg: sending key A9D53A3E to hkp server pgp.mit.edu
74```
75
76## Create and push a GPG-signed tag
77
78See [Release Shaarli](Release Shaarli).
diff --git a/doc/md/Plugin-System.md b/doc/md/Plugin-System.md
new file mode 100644
index 00000000..30f0ae74
--- /dev/null
+++ b/doc/md/Plugin-System.md
@@ -0,0 +1,708 @@
1[**I am a developer: ** Developer API](#developer-api)
2
3[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
4
5---
6
7## Developer API
8
9### What can I do with plugins?
10
11The plugin system let you:
12
13- insert content into specific places across templates.
14- alter data before templates rendering.
15- alter data before saving new links.
16
17### How can I create a plugin for Shaarli?
18
19First, chose a plugin name, such as `demo_plugin`.
20
21Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.
22
23You should have the following tree view:
24
25```
26| index.php
27| plugins/
28|---| demo_plugin/
29| |---| demo_plugin.php
30```
31
32### Plugin initialization
33
34At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
35
36 <plugin_name>_init($conf)
37
38This function can be used to create initial data, load default settings, etc. But also to set *plugin errors*. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
39
40### Understanding hooks
41
42A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
43
44These functions need to be named with this pattern:
45
46```
47hook_<plugin_name>_<hook_name>($data, $conf)
48```
49
50Parameters:
51
52- data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
53- conf: the `ConfigManager` instance.
54
55For exemple, if my plugin want to add data to the header, this function is needed:
56
57 hook_demo_plugin_render_header
58
59If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
60
61### Plugin's data
62
63#### Parameters
64
65Every hook function has a `$data` parameter. Its content differs for each hooks.
66
67**This parameter needs to be returned every time**, otherwise data is lost.
68
69 return $data;
70
71#### Filling templates placeholder
72
73Template placeholders are displayed in template in specific places.
74
75RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
76
77For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
78
79```php
80$data['top_placeholder'][] = 'My content';
81# OR
82array_push($data['top_placeholder'], 'My', 'content');
83
84return $data;
85```
86
87#### Data manipulation
88
89When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
90
91The data contained by this array can be altered before template rendering.
92
93For exemple, in linklist, it is possible to alter every title:
94
95```php
96// mind the reference if you want $data to be altered
97foreach ($data['links'] as &$value) {
98 // String reverse every title.
99 $value['title'] = strrev($value['title']);
100}
101
102return $data;
103```
104
105### Metadata
106
107Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
108
109Each file contain two keys:
110
111- `description`: plugin description
112- `parameters`: user parameter names, separated by a `;`.
113- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
114
115> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
116
117### It's not working!
118
119Use `demo_plugin` as a functional example. It covers most of the plugin system features.
120
121If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
122
123### Hooks
124
125| Hooks | Description |
126| ------------- |:-------------:|
127| [render_header](#render_header) | Allow plugin to add content in page headers. |
128| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
129| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
130| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |
131| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
132| [render_tools](#render_tools) | Allow to add content at the end of the page. |
133| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
134| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
135| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
136| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |
137| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
138| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
139| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
140
141
142
143#### render_header
144
145Triggered on every page.
146
147Allow plugin to add content in page headers.
148
149##### Data
150
151`$data` is an array containing:
152
153- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
154- `_LOGGEDIN_`: true if user is logged in, false otherwise.
155
156##### Template placeholders
157
158Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
159
160List of placeholders:
161
162- `buttons_toolbar`: after the list of buttons in the header.
163
164![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
165
166- `fields_toolbar`: after search fields in the header.
167
168> Note: This will only be called in linklist.
169
170![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)
171
172#### render_includes
173
174Triggered on every page.
175
176Allow plugin to include their own CSS files.
177
178##### Data
179
180`$data` is an array containing:
181
182- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
183- `_LOGGEDIN_`: true if user is logged in, false otherwise.
184
185##### Template placeholders
186
187Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
188
189List of placeholders:
190
191- `css_files`: called after loading default CSS.
192
193> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
194
195#### render_footer
196
197Triggered on every page.
198
199Allow plugin to add content in page footer and include their own JS files.
200
201##### Data
202
203`$data` is an array containing:
204
205- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
206- `_LOGGEDIN_`: true if user is logged in, false otherwise.
207
208##### Template placeholders
209
210Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
211
212List of placeholders:
213
214- `text`: called after the end of the footer text.
215- `endofpage`: called at the end of the page.
216
217![text_example](http://i.imgur.com/L5S2YEH.png)
218
219- `js_files`: called at the end of the page, to include custom JS scripts.
220
221> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
222
223#### render_linklist
224
225Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
226
227It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
228
229##### Data
230
231`$data` is an array containing:
232
233- `_LOGGEDIN_`: true if user is logged in, false otherwise.
234- All templates data, including links.
235
236##### Template placeholders
237
238Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
239
240List of placeholders:
241
242- `action_plugin`: next to the button "private only" at the top and bottom of the page.
243
244![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
245
246- `link_plugin`: for every link, between permalink and link URL.
247
248![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
249
250- `plugin_start_zone`: before displaying the template content.
251
252![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
253
254- `plugin_end_zone`: after displaying the template content.
255
256![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
257
258#### render_editlink
259
260Triggered when the link edition form is displayed.
261
262Allow to add fields in the form, or display elements.
263
264##### Data
265
266`$data` is an array containing:
267
268- All templates data.
269
270##### Template placeholders
271
272Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
273
274List of placeholders:
275
276- `edit_link_plugin`: after tags field.
277
278![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
279
280#### render_tools
281
282Triggered when the "tools" page is displayed.
283
284Allow to add content at the end of the page.
285
286##### Data
287
288`$data` is an array containing:
289
290- All templates data.
291
292##### Template placeholders
293
294Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
295
296List of placeholders:
297
298- `tools_plugin`: at the end of the page.
299
300![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
301
302#### render_picwall
303
304Triggered when picwall is displayed.
305
306Allow to add content at the top and bottom of the page.
307
308##### Data
309
310`$data` is an array containing:
311
312- `_LOGGEDIN_`: true if user is logged in, false otherwise.
313- All templates data.
314
315##### Template placeholders
316
317Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
318
319List of placeholders:
320
321- `plugin_start_zone`: before displaying the template content.
322- `plugin_end_zone`: after displaying the template content.
323
324![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
325
326#### render_tagcloud
327
328Triggered when tagcloud is displayed.
329
330Allow to add content at the top and bottom of the page.
331
332##### Data
333
334`$data` is an array containing:
335
336- `_LOGGEDIN_`: true if user is logged in, false otherwise.
337- All templates data.
338
339##### Template placeholders
340
341Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
342
343List of placeholders:
344
345- `plugin_start_zone`: before displaying the template content.
346- `plugin_end_zone`: after displaying the template content.
347
348For each tag, the following placeholder can be used:
349
350- `tag_plugin`: after each tag
351
352![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
353
354
355#### render_taglist
356
357Triggered when taglist is displayed.
358
359Allow to add content at the top and bottom of the page.
360
361##### Data
362
363`$data` is an array containing:
364
365- `_LOGGEDIN_`: true if user is logged in, false otherwise.
366- All templates data.
367
368##### Template placeholders
369
370Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
371
372List of placeholders:
373
374- `plugin_start_zone`: before displaying the template content.
375- `plugin_end_zone`: after displaying the template content.
376
377For each tag, the following placeholder can be used:
378
379- `tag_plugin`: after each tag
380
381#### render_daily
382
383Triggered when tagcloud is displayed.
384
385Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
386
387##### Data
388
389`$data` is an array containing:
390
391- `_LOGGEDIN_`: true if user is logged in, false otherwise.
392- All templates data, including links.
393
394##### Template placeholders
395
396Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
397
398List of placeholders:
399
400- `link_plugin`: used at bottom of each link.
401
402![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
403
404- `plugin_start_zone`: before displaying the template content.
405- `plugin_end_zone`: after displaying the template content.
406
407#### render_feed
408
409Triggered when the ATOM or RSS feed is displayed.
410
411Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
412
413##### Data
414
415`$data` is an array containing:
416
417- `_LOGGEDIN_`: true if user is logged in, false otherwise.
418- `_PAGE_`: containing either `rss` or `atom`.
419- All templates data, including links.
420
421##### Template placeholders
422
423Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
424
425List of placeholders:
426
427- `feed_plugins_header`: used as a header tag in the feed.
428
429For each links:
430
431- `feed_plugins`: additional tag for every link entry.
432
433#### save_link
434
435Triggered when a link is save (new link or edit).
436
437Allow to alter the link being saved in the datastore.
438
439##### Data
440
441`$data` is an array containing the link being saved:
442
443- id
444- title
445- url
446- shorturl
447- description
448- private
449- tags
450- created
451- updated
452
453
454#### delete_link
455
456Triggered when a link is deleted.
457
458Allow to execute any action before the link is actually removed from the datastore
459
460##### Data
461
462`$data` is an array containing the link being saved:
463
464- id
465- title
466- url
467- shorturl
468- description
469- private
470- tags
471- created
472- updated
473
474## Guide for template designer
475
476### Plugin administration
477
478Your theme must include a plugin administration page: `pluginsadmin.html`.
479
480> Note: repo's template link needs to be added when the PR is merged.
481
482Use the default one as an example.
483
484Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
485
486- you're using a table.
487- you call orderUp() and orderUp() onclick on arrows.
488- you add data-line and data-order to your rows.
489
490Otherwise, you can use your own JS as long as this field is send by the form:
491
492<input type="hidden" name="order_{$key}" value="{$counter}">
493
494### Placeholder system
495
496In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
497
498It's a RainTPL loop like this:
499
500 {loop="$plugin_variable"}
501 {$value}
502 {/loop}
503
504You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
505
506### List of placeholders
507
508**page.header.html**
509
510At the end of the menu:
511
512 {loop="$plugins_header.buttons_toolbar"}
513 {$value}
514 {/loop}
515
516At the end of file, before clearing floating blocks:
517
518 {if="!empty($plugin_errors) && isLoggedIn()"}
519 <ul class="errors">
520 {loop="plugin_errors"}
521 <li>{$value}</li>
522 {/loop}
523 </ul>
524 {/if}
525
526**includes.html**
527
528At the end of the file:
529
530```html
531{loop="$plugins_includes.css_files"}
532<link type="text/css" rel="stylesheet" href="{$value}#"/>
533{/loop}
534```
535
536**page.footer.html**
537
538At the end of your footer notes:
539
540```html
541{loop="$plugins_footer.text"}
542 {$value}
543{/loop}
544```
545
546At the end of file:
547
548```html
549{loop="$plugins_footer.js_files"}
550 <script src="{$value}#"></script>
551{/loop}
552```
553
554**linklist.html**
555
556After search fields:
557
558```html
559{loop="$plugins_header.fields_toolbar"}
560 {$value}
561{/loop}
562```
563
564Before displaying the link list (after paging):
565
566```html
567{loop="$plugin_start_zone"}
568 {$value}
569{/loop}
570```
571
572For every links (icons):
573
574```html
575{loop="$value.link_plugin"}
576 <span>{$value}</span>
577{/loop}
578```
579
580Before end paging:
581
582```html
583{loop="$plugin_end_zone"}
584 {$value}
585{/loop}
586```
587
588**linklist.paging.html**
589
590After the "private only" icon:
591
592```html
593{loop="$action_plugin"}
594 {$value}
595{/loop}
596```
597
598**editlink.html**
599
600After tags field:
601
602```html
603{loop="$edit_link_plugin"}
604 {$value}
605{/loop}
606```
607
608**tools.html**
609
610After the last tool:
611
612```html
613{loop="$tools_plugin"}
614 {$value}
615{/loop}
616```
617
618**picwall.html**
619
620Top:
621
622```html
623<div id="plugin_zone_start_picwall" class="plugin_zone">
624 {loop="$plugin_start_zone"}
625 {$value}
626 {/loop}
627</div>
628```
629
630Bottom:
631
632```html
633<div id="plugin_zone_end_picwall" class="plugin_zone">
634 {loop="$plugin_end_zone"}
635 {$value}
636 {/loop}
637</div>
638```
639
640**tagcloud.html**
641
642Top:
643
644```html
645 <div id="plugin_zone_start_tagcloud" class="plugin_zone">
646 {loop="$plugin_start_zone"}
647 {$value}
648 {/loop}
649 </div>
650```
651
652Bottom:
653
654```html
655 <div id="plugin_zone_end_tagcloud" class="plugin_zone">
656 {loop="$plugin_end_zone"}
657 {$value}
658 {/loop}
659 </div>
660```
661
662**daily.html**
663
664Top:
665
666```html
667<div id="plugin_zone_start_picwall" class="plugin_zone">
668 {loop="$plugin_start_zone"}
669 {$value}
670 {/loop}
671</div>
672```
673
674After every link:
675
676```html
677<div class="dailyEntryFooter">
678 {loop="$link.link_plugin"}
679 {$value}
680 {/loop}
681</div>
682```
683
684Bottom:
685
686```html
687<div id="plugin_zone_end_picwall" class="plugin_zone">
688 {loop="$plugin_end_zone"}
689 {$value}
690 {/loop}
691</div>
692```
693
694**feed.atom.xml** and **feed.rss.xml**:
695
696In headers tags section:
697```xml
698{loop="$feed_plugins_header"}
699 {$value}
700{/loop}
701```
702
703After each entry:
704```xml
705{loop="$value.feed_plugins"}
706 {$value}
707{/loop}
708```
diff --git a/doc/md/Plugins.md b/doc/md/Plugins.md
new file mode 100644
index 00000000..7d40637f
--- /dev/null
+++ b/doc/md/Plugins.md
@@ -0,0 +1,75 @@
1## Plugin installation
2
3There is a bunch of plugins shipped with Shaarli, where there is nothing to do to install them.
4
5If you want to install a third party plugin:
6
7- Download it.
8- Put it in the `plugins` directory in Shaarli's installation folder.
9- Make sure you put it correctly:
10
11```
12| index.php
13| plugins/
14|---| custom_plugin/
15| |---| custom_plugin.php
16| |---| ...
17
18```
19
20 * Make sure your webserver can read and write the files in your plugin folder.
21
22## Plugin configuration
23
24In Shaarli's administration page (`Tools` link), go to `Plugin administration`.
25
26Here you can enable and disable all plugins available, and configure them.
27
28![administration screenshot](https://camo.githubusercontent.com/5da68e191969007492ca0fbeb25f3b2357b748cc/687474703a2f2f692e696d6775722e636f6d2f766837544643712e706e67)
29
30## Plugin order
31
32In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.
33
34This is important in case plugins are depending on each other. Read plugins README details for more information.
35
36**Use case**: The (non existent) plugin `shaares_footer` adds a footer to every shaare in Markdown syntax. It needs to be processed *before* (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.
37
38## File mode
39
40Enabled plugin are stored in your `config.php` parameters file, under the `array`:
41
42```php
43$GLOBALS['config']['ENABLED_PLUGINS']
44```
45
46You can edit them manually here.
47Example:
48
49```php
50$GLOBALS['config']['ENABLED_PLUGINS'] = array(
51 'qrcode',
52 'archiveorg',
53 'wallabag',
54 'markdown',
55);
56```
57
58### Plugin usage
59
60#### Official plugins
61
62Usage of each plugin is documented in it's README file:
63
64 * `addlink-toolbar`: Adds the addlink input on the linklist page
65 * `archiveorg`: For each link, add an Archive.org icon
66 * [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.
67 * [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.
68 * `qrcode`: For each link, add a QRCode icon.
69 * [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.
70
71
72
73#### Third party plugins
74
75See [Community & related software](https://github.com/shaarli/Shaarli/wiki/Community-%26-Related-software#third-party-plugins)
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
new file mode 100644
index 00000000..68a83c00
--- /dev/null
+++ b/doc/md/REST-API.md
@@ -0,0 +1,153 @@
1## Usage and Prerequisites
2
3See the [REST API documentation](http://shaarli.github.io/api-documentation/)
4for a list of available endpoints and parameters.
5
6Please ensure that your server meets the [requirements](Server-requirements)
7and is properly [configured](Server-configuration):
8
9- URL rewriting is enabled (see specific Apache and Nginx sections)
10- the server's timezone is properly defined
11- the server's clock is synchronized with
12 [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)
13
14The host where the API client is invoked should also be synchronized with NTP,
15see [token expiration](#payload).
16
17## Authentication
18
19All requests to Shaarli's API must include a JWT token to verify their authenticity.
20
21This token has to be included as an HTTP header called `Authentication: Bearer <jwt token>`.
22
23JWT resources :
24
25- [jwt.io](https://jwt.io) (including a list of client per language).
26- RFC : https://tools.ietf.org/html/rfc7519
27- https://float-middle.com/json-web-tokens-jwt-vs-sessions/
28- HackerNews thread: https://news.ycombinator.com/item?id=11929267
29
30
31### Shaarli JWT Token
32
33JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64:
34
35```
36[header].[payload].[signature]
37```
38
39#### Header
40
41Shaarli only allow one hash algorithm, so the header will always be the same:
42
43```json
44{
45 "typ": "JWT",
46 "alg": "HS512"
47}
48```
49
50Encoded in base64, it gives:
51
52```
53ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
54```
55
56#### Payload
57
58**Token expiration**
59
60To avoid infinite token validity, JWT tokens must include their creation date
61in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at).
62This token will be valid during **9 minutes**.
63
64```json
65{
66 "iat": 1468663519
67}
68```
69
70See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).
71
72
73#### Signature
74
75The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
76
77Signature example with PHP:
78
79```php
80$content = base64_encode($header) . '.' . base64_encode($payload);
81$signature = hash_hmac('sha512', $content, $secret);
82```
83
84
85## Clients and examples
86### Android, Java, Kotlin
87
88- [Android client example with Kotlin](https://gitlab.com/snippets/1665808)
89 by [Braincoke](https://github.com/Braincoke)
90
91### Javascript, NodeJS
92
93- [shaarli-client](https://www.npmjs.com/package/shaarli-client)
94 ([source code](https://github.com/laBecasse/shaarli-client))
95 by [laBecasse](https://github.com/laBecasse)
96
97### PHP
98
99This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library.
100
101```php
102<?php
103$baseUrl = 'https://shaarli.mydomain.net';
104$secret = 'thats_my_api_secret';
105
106function base64url_encode($data) {
107 return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
108}
109
110function generateToken($secret) {
111 $header = base64url_encode('{
112 "typ": "JWT",
113 "alg": "HS512"
114 }');
115 $payload = base64url_encode('{
116 "iat": '. time() .'
117 }');
118 $signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true));
119 return $header . '.' . $payload . '.' . $signature;
120}
121
122
123function getInfo($baseUrl, $secret) {
124 $token = generateToken($secret);
125 $endpoint = rtrim($baseUrl, '/') . '/api/v1/info';
126
127 $headers = [
128 'Content-Type: text/plain; charset=UTF-8',
129 'Authorization: Bearer ' . $token,
130 ];
131
132 $ch = curl_init($endpoint);
133 curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
134 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
135 curl_setopt($ch, CURLOPT_AUTOREFERER, 1);
136 curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
137
138 $result = curl_exec($ch);
139 curl_close($ch);
140
141 return $result;
142}
143
144var_dump(getInfo($baseUrl, $secret));
145```
146
147
148### Python
149
150See the reference API client:
151
152- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
153- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github
diff --git a/doc/md/RSS-feeds.md b/doc/md/RSS-feeds.md
new file mode 100644
index 00000000..d943218e
--- /dev/null
+++ b/doc/md/RSS-feeds.md
@@ -0,0 +1,28 @@
1### Feeds options
2
3Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
4
5Options:
6
7- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
8 - E.G. `https://my.shaarli.domain/?do=atom&permalinks`.
9- You can use `nb` parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything.
10 - `https://my.shaarli.domain/?do=atom&permalinks&nb=42`
11 - `https://my.shaarli.domain/?do=atom&permalinks&nb=all`
12
13### RSS Feeds or Picture Wall for a specific search/tag
14
15It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**.
16
17For example, if you want to subscribe only to links tagged `photography`:
18
19- Go to the desired Shaarli instance.
20- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
21- Click on the `RSS Feed` button.
22- You are presented with an RSS feed showing only these links. Subscribe to it to receive only updates with this tag.
23- The same method **also works for a full-text search** (_Search_ box) **and for the Picture Wall** (want to only see pictures about `nature`?)
24- You can also build the URLs manually:
25 - `https://my.shaarli.domain/?do=rss&searchtags=nature`
26 - `https://my.shaarli.domain/links/?do=picwall&searchterm=poney`
27
28![](images/rss-filter-1.png) ![](images/rss-filter-2.png)
diff --git a/doc/md/Release-Shaarli.md b/doc/md/Release-Shaarli.md
new file mode 100644
index 00000000..974a7438
--- /dev/null
+++ b/doc/md/Release-Shaarli.md
@@ -0,0 +1,155 @@
1See [Git - Maintaining a project - Tagging your
2releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases).
3
4## Prerequisites
5This guide assumes that you have:
6
7- a GPG key matching your GitHub authentication credentials
8 - i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
9- a GitHub fork of Shaarli
10- a local clone of your Shaarli fork, with the following remotes:
11 - `origin` pointing to your GitHub fork
12 - `upstream` pointing to the main Shaarli repository
13- maintainer permissions on the main Shaarli repository, to:
14 - push the signed tag
15 - create a new release
16- [Composer](https://getcomposer.org/) needs to be installed
17- The [venv](https://docs.python.org/3/library/venv.html) Python 3 module needs to be installed for HTML documentation generation.
18
19## GitHub release draft and `CHANGELOG.md`
20See http://keepachangelog.com/en/0.3.0/ for changelog formatting.
21
22### GitHub release draft
23GitHub allows drafting the release note for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`.
24
25### `CHANGELOG.md`
26This file should contain the same information as the release note draft for the upcoming version.
27
28Update it to:
29
30- add new entries (additions, fixes, etc.)
31- mark the current version as released by setting its date and link
32- add a new section for the future unreleased version
33
34```bash
35$ cd /path/to/shaarli
36
37$ nano CHANGELOG.md
38
39[...]
40## vA.B.C - UNRELEASED
41TBA
42
43## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD
44[...]
45```
46
47
48## Increment the version code, update docs, create and push a signed tag
49### Create and merge a Pull Request
50This one is pretty straightforward ;-)
51
52### Bump Shaarli version to v0.x branch
53
54```bash
55$ git checkout master
56$ git fetch upstream
57$ git pull upstream master
58
59# IF the branch doesn't exists
60$ git checkout -b v0.5
61# OR if the branch already exists
62$ git checkout v0.5
63$ git rebase upstream/master
64
65# Bump shaarli version from dev to 0.5.0, **without the `v`**
66$ vim shaarli_version.php
67$ git add shaarli_version
68$ git commit -s -m "Bump Shaarli version to v0.5.0"
69$ git push upstream v0.5
70```
71
72### Create and push a signed tag
73```bash
74# update your local copy
75$ git checkout v0.5
76$ git fetch upstream
77$ git pull upstream v0.5
78
79# create a signed tag
80$ git tag -s -m "Release v0.5.0" v0.5.0
81
82# push it to "upstream"
83$ git push --tags upstream
84```
85
86### Verify a signed tag
87[`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli.
88
89Let's have a look at its signature!
90
91```bash
92$ cd /path/to/shaarli
93$ git fetch upstream
94
95# get the SHA1 reference of the tag
96$ git show-ref tags/v0.5.0
97f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
98
99# verify the tag signature information
100$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
101gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
102gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate]
103```
104
105## Publish the GitHub release
106### Update release badges
107Update `README.md` so version badges display and point to the newly released Shaarli version(s), in the `master` branch.
108
109### Create a GitHub release from a Git tag
110From the previously drafted release:
111
112- edit the release notes (if needed)
113- specify the appropriate Git tag
114- publish the release
115- profit!
116
117### Generate and upload all-in-one release archives
118Users with a shared hosting may have:
119
120- no SSH access
121- no possibility to install PHP packages or server extensions
122- no possibility to run scripts
123
124To ease Shaarli installations, it is possible to generate and upload additional release archives,
125that will contain Shaarli code plus all required third-party libraries.
126
127**From the `v0.5` branch:**
128
129```bash
130$ make release_archive
131```
132
133This will create the following archives:
134
135- `shaarli-vX.Y.Z-full.tar`
136- `shaarli-vX.Y.Z-full.zip`
137
138The archives need to be manually uploaded on the previously created GitHub release.
139
140### Update `stable` and `latest` branches
141
142```
143$ git checkout latest
144# latest release
145$ git merge v0.5.0
146# fix eventual conflicts
147$ make test
148$ git push upstream latest
149$ git checkout stable
150# latest previous major
151$ git merge v0.4.5
152# fix eventual conflicts
153$ make test
154$ git push upstream stable
155```
diff --git a/doc/md/Security.md b/doc/md/Security.md
new file mode 100644
index 00000000..36f629af
--- /dev/null
+++ b/doc/md/Security.md
@@ -0,0 +1,28 @@
1## Client browser
2- Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
3
4## PHP
5- `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts.
6
7## Server and sessions
8- Directories are protected using `.htaccess` files
9- Forms are protected against XSRF (Cross-site requests forgery):
10 - Forms which act on data (save,delete…) contain a token generated by the server.
11 - Any posted form which does not contain a valid token is rejected.
12 - Any token can only be used once.
13 - Tokens are attached to the session and cannot be reused in another session.
14- Sessions automatically expire after 60 minutes.
15- Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
16
17## Shaarli datastore and configuration
18- The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
19- Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file.
20- Even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
21- The database looks like this:
22
23```php
24<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
25...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
26```
27
28- Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`.
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
new file mode 100644
index 00000000..25dd49fe
--- /dev/null
+++ b/doc/md/Server-configuration.md
@@ -0,0 +1,406 @@
1*Example virtual host configurations for popular web servers*
2
3- [Apache](#apache)
4- [Nginx](#nginx)
5
6## Prerequisites
7### Shaarli
8- Shaarli is installed in a directory readable/writeable by the user
9- the correct read/write permissions have been granted to the web server _user and/or group_
10- for HTTPS / SSL:
11 - a key pair (public, private) and a certificate have been generated
12 - the appropriate server SSL extension is installed and active
13
14### HTTPS, TLS and self-signed certificates
15Related guides:
16
17- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
18- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
19- Generate a self-signed certificate (will trigger browser warnings) with apache2:
20 `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
21
22### Proxies
23If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
24
25- `X-Forwarded-Proto`
26- `X-Forwarded-Host`
27- `X-Forwarded-For`
28
29See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
30
31## Apache
32### Minimal
33```apache
34<VirtualHost *:80>
35 ServerName shaarli.my-domain.org
36 DocumentRoot /absolute/path/to/shaarli/
37</VirtualHost>
38```
39### Debug - Log all the things!
40This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
41
42See:
43
44- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
45- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
46
47```apache
48<VirtualHost *:80>
49 ServerName shaarli.my-domain.org
50 DocumentRoot /absolute/path/to/shaarli/
51
52 LogLevel warn
53 ErrorLog /var/log/apache2/shaarli-error.log
54 CustomLog /var/log/apache2/shaarli-access.log combined
55
56 php_flag log_errors on
57 php_flag display_errors on
58 php_value error_reporting 2147483647
59 php_value error_log /var/log/apache2/shaarli-php-error.log
60</VirtualHost>
61```
62
63### Standard - Keep access and error logs
64```apache
65<VirtualHost *:80>
66 ServerName shaarli.my-domain.org
67 DocumentRoot /absolute/path/to/shaarli/
68
69 LogLevel warn
70 ErrorLog /var/log/apache2/shaarli-error.log
71 CustomLog /var/log/apache2/shaarli-access.log combined
72</VirtualHost>
73```
74
75### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
76See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).
77
78```apache
79<VirtualHost *:443>
80 ServerName shaarli.my-domain.org
81 DocumentRoot /absolute/path/to/shaarli/
82
83 SSLEngine on
84 SSLCertificateFile /absolute/path/to/the/website/certificate.pem
85 SSLCertificateKeyFile /absolute/path/to/the/website/key.key
86
87 <Directory /absolute/path/to/shaarli/>
88 AllowOverride All
89 Options Indexes FollowSymLinks MultiViews
90 Order allow,deny
91 allow from all
92 </Directory>
93
94 LogLevel warn
95 ErrorLog /var/log/apache2/shaarli-error.log
96 CustomLog /var/log/apache2/shaarli-access.log combined
97</VirtualHost>
98<VirtualHost *:80>
99 ServerName shaarli.my-domain.org
100 Redirect 301 / https://shaarli.my-domain.org
101
102 LogLevel warn
103 ErrorLog /var/log/apache2/shaarli-error.log
104 CustomLog /var/log/apache2/shaarli-access.log combined
105</VirtualHost>
106```
107
108### .htaccess
109
110Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
111
112**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.
113
114Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
115
116## LightHttpd
117
118## Nginx
119### Foreword
120Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
121
122Required packages:
123
124- [nginx](http://nginx.org)
125- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
126
127Official documentation:
128
129- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
130- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
131- [Pitfalls](http://wiki.nginx.org/Pitfalls)
132
133Community resources:
134
135- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
136- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
137
138### Common setup
139Once Nginx and PHP-FPM are installed, we need to ensure:
140
141- Nginx and PHP-FPM are running using the _same user and group_
142- both these user and group have
143 - `read` permissions for Shaarli resources
144 - `execute` permissions for Shaarli directories _AND_ their parent directories
145
146On a production server:
147
148- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
149- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
150
151On a development server:
152
153- files may be located in a user's home directory
154- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
155
156For all following configuration examples, this user/group pair will be used:
157
158- `user:group = john:users`,
159
160which corresponds to the following service configuration:
161
162```ini
163; /etc/php/php-fpm.conf
164user = john
165group = users
166
167[...]
168listen.owner = john
169listen.group = users
170```
171
172```nginx
173# /etc/nginx/nginx.conf
174user john users;
175
176http {
177 [...]
178}
179```
180
181### (Optional) Increase the maximum file upload size
182Some bookmark dumps generated by web browsers can be _huge_ due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
183
184To increase upload size, you will need to modify both nginx and PHP configuration:
185
186```nginx
187# /etc/nginx/nginx.conf
188
189http {
190 [...]
191
192 client_max_body_size 10m;
193
194 [...]
195}
196```
197
198```ini
199# /etc/php5/fpm/php.ini
200
201[...]
202post_max_size = 10M
203[...]
204upload_max_filesize = 10M
205```
206
207### Minimal
208_WARNING: Use for development only!_
209
210```nginx
211user john users;
212worker_processes 1;
213events {
214 worker_connections 1024;
215}
216
217http {
218 include mime.types;
219 default_type application/octet-stream;
220 keepalive_timeout 20;
221
222 index index.html index.php;
223
224 server {
225 listen 80;
226 server_name localhost;
227 root /home/john/web;
228
229 access_log /var/log/nginx/access.log;
230 error_log /var/log/nginx/error.log;
231
232 location /shaarli/ {
233 try_files $uri /shaarli/index.php$is_args$args;
234 access_log /var/log/nginx/shaarli.access.log;
235 error_log /var/log/nginx/shaarli.error.log;
236 }
237
238 location ~ (index)\.php$ {
239 try_files $uri =404;
240 fastcgi_split_path_info ^(.+\.php)(/.+)$;
241 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
242 fastcgi_index index.php;
243 include fastcgi.conf;
244 }
245 }
246}
247```
248
249### Modular
250The previous setup is sufficient for development purposes, but has several major caveats:
251
252- every content that does not match the PHP rule will be sent to client browsers:
253 - dotfiles - in our case, `.htaccess`
254 - temporary files, e.g. Vim or Emacs files: `index.php~`
255- asset / static resource caching is not optimized
256- if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
257
258To solve this, we will split Nginx configuration in several parts, that will be included when needed:
259
260```nginx
261# /etc/nginx/deny.conf
262location ~ /\. {
263 # deny access to dotfiles
264 access_log off;
265 log_not_found off;
266 deny all;
267}
268
269location ~ ~$ {
270 # deny access to temp editor files, e.g. "script.php~"
271 access_log off;
272 log_not_found off;
273 deny all;
274}
275```
276
277```nginx
278# /etc/nginx/php.conf
279location ~ (index)\.php$ {
280 # Slim - split URL path into (script_filename, path_info)
281 try_files $uri =404;
282 fastcgi_split_path_info ^(.+\.php)(/.+)$;
283
284 # filter and proxy PHP requests to PHP-FPM
285 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
286 fastcgi_index index.php;
287 include fastcgi.conf;
288}
289
290location ~ \.php$ {
291 # deny access to all other PHP scripts
292 deny all;
293}
294```
295
296```nginx
297# /etc/nginx/static_assets.conf
298location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
299 expires max;
300 add_header Pragma public;
301 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
302}
303```
304
305```nginx
306# /etc/nginx/nginx.conf
307[...]
308
309http {
310 [...]
311
312 root /home/john/web;
313 access_log /var/log/nginx/access.log;
314 error_log /var/log/nginx/error.log;
315
316 server {
317 # virtual host for a first domain
318 listen 80;
319 server_name my.first.domain.org;
320
321 location /shaarli/ {
322 # Slim - rewrite URLs
323 try_files $uri /shaarli/index.php$is_args$args;
324
325 access_log /var/log/nginx/shaarli.access.log;
326 error_log /var/log/nginx/shaarli.error.log;
327 }
328
329 location = /shaarli/favicon.ico {
330 # serve the Shaarli favicon from its custom location
331 alias /var/www/shaarli/images/favicon.ico;
332 }
333
334 include deny.conf;
335 include static_assets.conf;
336 include php.conf;
337 }
338
339 server {
340 # virtual host for a second domain
341 listen 80;
342 server_name second.domain.com;
343
344 location /minigal/ {
345 access_log /var/log/nginx/minigal.access.log;
346 error_log /var/log/nginx/minigal.error.log;
347 }
348
349 include deny.conf;
350 include static_assets.conf;
351 include php.conf;
352 }
353}
354```
355
356### Redirect HTTP to HTTPS
357Assuming you have generated a (self-signed) key and certificate, and they are
358located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
359to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
360
361```nginx
362# /etc/nginx/nginx.conf
363[...]
364
365http {
366 [...]
367
368 index index.html index.php;
369
370 root /home/john/web;
371 access_log /var/log/nginx/access.log;
372 error_log /var/log/nginx/error.log;
373
374 server {
375 listen 80;
376 server_name localhost;
377
378 return 301 https://localhost$request_uri;
379 }
380
381 server {
382 listen 443 ssl;
383 server_name localhost;
384
385 ssl_certificate /home/john/ssl/localhost.crt;
386 ssl_certificate_key /home/john/ssl/localhost.key;
387
388 location /shaarli/ {
389 # Slim - rewrite URLs
390 try_files $uri /index.php$is_args$args;
391
392 access_log /var/log/nginx/shaarli.access.log;
393 error_log /var/log/nginx/shaarli.error.log;
394 }
395
396 location = /shaarli/favicon.ico {
397 # serve the Shaarli favicon from its custom location
398 alias /var/www/shaarli/images/favicon.ico;
399 }
400
401 include deny.conf;
402 include static_assets.conf;
403 include php.conf;
404 }
405}
406```
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
new file mode 100644
index 00000000..707af762
--- /dev/null
+++ b/doc/md/Server-requirements.md
@@ -0,0 +1,41 @@
1## PHP
2
3### Release information
4- [PHP: Supported versions](http://php.net/supported-versions.php)
5- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
6- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
7- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
8- [PHP: Bugs](https://bugs.php.net/)
9
10### Supported versions
11Version | Status | Shaarli compatibility
12:---:|:---:|:---:
137.1 | Supported (v0.9.x) | Yes
147.0 | Supported | Yes
155.6 | Supported | Yes
165.5 | EOL: 2016-07-10 | Yes
175.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
185.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
19
20See also:
21
22- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
23
24### Dependency management
25Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,
26download and install third-party PHP dependencies.
27
28Library | Required? | Usage
29---|:---:|---
30[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files
31[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin
32[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API
33
34### Extensions
35Extension | Required? | Usage
36---|:---:|---
37[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
38[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows | multibyte (Unicode) string support
39[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
40[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
41[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
diff --git a/doc/md/Server-security.md b/doc/md/Server-security.md
new file mode 100644
index 00000000..700084e2
--- /dev/null
+++ b/doc/md/Server-security.md
@@ -0,0 +1,76 @@
1## php.ini
2PHP settings are defined in:
3
4- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
5 - `/etc/php5/php.ini` - used when running console scripts
6 - `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache
7 - `/etc/php5/php-fpm.conf` - used when PHP requests are proxied to PHP-FPM
8- additional configuration files/entries, depending on the installed/enabled extensions:
9 - `/etc/php/conf.d/xdebug.ini`
10
11### Locate .ini files
12#### Console environment
13```bash
14$ php --ini
15Configuration File (php.ini) Path: /etc/php
16Loaded Configuration File: /etc/php/php.ini
17Scan for additional .ini files in: /etc/php/conf.d
18Additional .ini files parsed: /etc/php/conf.d/xdebug.ini
19```
20
21#### Server environment
22- create a `phpinfo.php` script located in a path supported by the web server, e.g.
23 - Apache (with user dirs enabled): `/home/myself/public_html/phpinfo.php`
24 - `/var/www/test/phpinfo.php`
25- make sure the script is readable by the web server user/group (usually, `www`, `www-data` or `httpd`)
26- access the script from a web browser
27- look at the _Loaded Configuration File_ and _Scan this dir for additional .ini files_ entries
28```php
29<?php phpinfo(); ?>
30```
31
32## fail2ban
33`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
34
35- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
36- [Source code](https://github.com/fail2ban/fail2ban)
37
38### Read Shaarli logs to ban IPs
39Example configuration:
40- allow 3 login attempts per IP address
41- after 3 failures, permanently ban the corresponding IP adddress
42
43`/etc/fail2ban/jail.local`
44```ini
45[shaarli-auth]
46enabled = true
47port = https,http
48filter = shaarli-auth
49logpath = /var/www/path/to/shaarli/data/log.txt
50maxretry = 3
51bantime = -1
52```
53
54`/etc/fail2ban/filter.d/shaarli-auth.conf`
55```ini
56[INCLUDES]
57before = common.conf
58[Definition]
59failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
60ignoreregex =
61```
62
63## Robots - Restricting search engines and web crawler traffic
64
65Creating a `robots.txt` with the following contents at the root of your Shaarli installation will prevent _honest_ web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.
66
67```
68User-agent: *
69Disallow: /
70```
71
72See:
73
74- http://www.robotstxt.org
75- http://www.robotstxt.org/robotstxt.html
76- http://www.robotstxt.org/meta.html
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
new file mode 100644
index 00000000..188a3c09
--- /dev/null
+++ b/doc/md/Shaarli-configuration.md
@@ -0,0 +1,217 @@
1## Foreword
2
3**Do not edit configuration options in index.php! Your changes would be lost.**
4
5Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
6* it contains all settings in JSON format, and can be edited to customize values
7* it defines which [plugins](Plugin-System) are enabled[](.html)
8* its values override those defined in `index.php`
9* it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
10
11## File and directory permissions
12
13The server process running Shaarli must have:
14
15- `read` access to the following resources:
16 - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
17 - 3rd party PHP and Javascript libraries: `inc/*.php`, `inc/*.js`
18 - static assets:
19 - CSS stylesheets: `inc/*.css`
20 - `images/*`
21 - RainTPL templates: `tpl/*.html`
22- `read`, `write` and `execution` access to the following directories:
23 - `cache` - thumbnail cache
24 - `data` - link data store, configuration options
25 - `pagecache` - Atom/RSS feed cache
26 - `tmp` - RainTPL page cache
27
28On a Linux distribution:
29
30- the web server user will likely be `www` or `http` (for Apache2)
31- it will be a member of a group of the same name: `www:www`, `http:http`
32- to give it access to Shaarli, either:
33 - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
34 - put users in the same group as the web server, and set the appropriate access rights
35- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html)
36
37## Configuration
38
39In `data/config.json.php`.
40
41See also [Plugin System](Plugin-System.html).
42
43### Credentials
44
45_These settings should not be edited_
46
47- **login**: Login username.
48- **hash**: Generated password hash.
49- **salt**: Password salt.
50
51### General
52
53- **title**: Shaarli's instance title.
54- **header_link**: Link to the homepage.
55- **links_per_page**: Number of shaares displayed per page.
56- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
57- **enabled_plugins**: List of enabled plugins.
58
59### Security
60
61- **session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
62 It might be useful if your IP adress often changes.
63- **ban_after**: Failed login attempts before being IP banned.
64- **ban_duration**: IP ban duration in seconds.
65- **open_shaarli**: Anyone can add a new link while logged out if enabled.
66- **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
67- **allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
68
69### Resources
70
71- **data_dir**: Data directory.
72- **datastore**: Shaarli's links database file path.
73- **history**: Shaarli's operation history file path.
74- **updates**: File path for the ran updates file.
75- **log**: Log file path.
76- **update_check**: Last update check file path.
77- **raintpl_tpl**: Templates directory.
78- **raintpl_tmp**: Template engine cache directory.
79- **thumbnails_cache**: Thumbnails cache directory.
80- **page_cache**: Shaarli's internal cache directory.
81- **ban_file**: Banned IP file path.
82
83### Updates
84
85- **check_updates**: Enable or disable update check to the git repository.
86- **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
87- **check_updates_interval**: Look for new version every N seconds (default: every day).
88
89### Privacy
90
91- **default_private_links**: Check the private checkbox by default for every new link.
92- **hide_public_links**: All links are hidden while logged out.
93- **hide_timestamps**: Timestamps are hidden.
94
95### Feed
96
97- **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
98- **show_atom**: Display ATOM feed button.
99
100### Thumbnail
101
102- **enable_thumbnails**: Enable or disable thumbnail display.
103- **enable_localcache**: Enable or disable local cache.
104
105### Redirector
106
107- **url**: Redirector URL, such as `anonym.to`.
108- **encode_url**: Enable this if the redirector needs encoded URL to work properly.
109
110## Configuration file example
111
112```json
113<?php /*
114{
115 "credentials": {
116 "login": "<login>",
117 "hash": "<password hash>",
118 "salt": "<password salt>"
119 },
120 "security": {
121 "ban_after": 4,
122 "session_protection_disabled": false,
123 "ban_duration": 1800,
124 "trusted_proxies": [
125 "1.2.3.4",
126 "5.6.7.8"
127 ],
128 "allowed_protocols": [
129 "ftp",
130 "ftps",
131 "magnet"
132 ]
133 },
134 "resources": {
135 "data_dir": "data",
136 "config": "data\/config.php",
137 "datastore": "data\/datastore.php",
138 "ban_file": "data\/ipbans.php",
139 "updates": "data\/updates.txt",
140 "log": "data\/log.txt",
141 "update_check": "data\/lastupdatecheck.txt",
142 "raintpl_tmp": "tmp\/",
143 "raintpl_tpl": "tpl\/",
144 "thumbnails_cache": "cache",
145 "page_cache": "pagecache"
146 },
147 "general": {
148 "check_updates": true,
149 "rss_permalinks": true,
150 "links_per_page": 20,
151 "default_private_links": true,
152 "enable_thumbnails": true,
153 "enable_localcache": true,
154 "check_updates_branch": "stable",
155 "check_updates_interval": 86400,
156 "enabled_plugins": [
157 "markdown",
158 "wallabag",
159 "archiveorg"
160 ],
161 "timezone": "Europe\/Paris",
162 "title": "My Shaarli",
163 "header_link": "?"
164 },
165 "extras": {
166 "show_atom": false,
167 "hide_public_links": false,
168 "hide_timestamps": false,
169 "open_shaarli": false,
170 "redirector": "http://anonym.to/?",
171 "redirector_encode_url": false
172 },
173 "general": {
174 "header_link": "?",
175 "links_per_page": 20,
176 "enabled_plugins": [
177 "markdown",
178 "wallabag"
179 ],
180 "timezone": "Europe\/Paris",
181 "title": "My Shaarli"
182 },
183 "updates": {
184 "check_updates": true,
185 "check_updates_branch": "stable",
186 "check_updates_interval": 86400
187 },
188 "feed": {
189 "rss_permalinks": true,
190 "show_atom": false
191 },
192 "privacy": {
193 "default_private_links": true,
194 "hide_public_links": false,
195 "hide_timestamps": false
196 },
197 "thumbnail": {
198 "enable_thumbnails": true,
199 "enable_localcache": true
200 },
201 "redirector": {
202 "url": "http://anonym.to/?",
203 "encode_url": false
204 },
205 "plugins": {
206 "WALLABAG_URL": "http://demo.wallabag.org",
207 "WALLABAG_VERSION": "1"
208 }
209} ?>
210```
211
212## Additional configuration
213
214The `playvideos` plugin may require that you adapt your server's
215[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
216configuration to work properly.
217
diff --git a/doc/md/Static-analysis.md b/doc/md/Static-analysis.md
new file mode 100644
index 00000000..29d98362
--- /dev/null
+++ b/doc/md/Static-analysis.md
@@ -0,0 +1,13 @@
1## WIP
2This topic is currently being discussed here:
3
4- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
5- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
6
7### Usage
8Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
9
10For an overview of the available features, see:
11
12- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
13- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)
diff --git a/doc/md/Theming.md b/doc/md/Theming.md
new file mode 100644
index 00000000..bd400776
--- /dev/null
+++ b/doc/md/Theming.md
@@ -0,0 +1,85 @@
1## Foreword
2
3There are two ways of customizing how Shaarli looks:
4
51. by using a custom CSS to override Shaarli's CSS
62. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
7
8## Custom CSS
9
10Shaarli's appearance can be modified by adding CSS rules to:
11
12- Shaarli < `v0.9.0`: `inc/user.css`
13- Shaarli >= `v0.9.0`: `data/user.css`
14
15This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.
16
17**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli.
18
19See also [Download CSS styles from an OPML list](Download CSS styles from an OPML list)
20
21## Themes
22
23Installation:
24
25- find a theme you'd like to install
26- copy or clone the theme folder under `tpl/<a_sweet_theme>`
27- enable the theme:
28 - Shaarli < `v0.9.0`: edit `data/config.json.php` and set the value of `raintpl_tpl` to the new theme name:
29 `"raintpl_tpl": "tpl\/my-template\/"`
30 - Shaarli >= `v0.9.0`: select the theme through the _Tools_ page
31
32## Community CSS & themes
33
34### Custom CSS
35
36- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli
37- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)
38
39### Themes
40
41- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
42- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
43- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
44- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
45- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
46- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone
47- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site
48
49### Shaarli forks
50
51- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
52- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
53
54## Example installation: AlbinoMouse theme
55
56With the following configuration:
57
58- Apache 2 / PHP 5.6
59- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
60- `http` is the name of the Apache user
61
62```bash
63$ cd ~/public_html
64
65# clone repositories
66$ git clone https://github.com/shaarli/Shaarli.git shaarli
67$ pushd shaarli/tpl
68$ git clone https://github.com/alexisju/albinomouse-template.git
69$ popd
70
71# set access rights for Apache
72$ chgrp -R http shaarli
73$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
74```
75
76Get config written:
77- go to the freshly installed site
78- fill the install form
79- log in to Shaarli
80
81Edit Shaarli's [configuration](Shaarli-configuration):
82```bash
83# the file should be owned by Apache, thus not writeable => sudo
84$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
85```
diff --git a/doc/md/Troubleshooting.md b/doc/md/Troubleshooting.md
new file mode 100644
index 00000000..b2d86d40
--- /dev/null
+++ b/doc/md/Troubleshooting.md
@@ -0,0 +1,132 @@
1# Troubleshooting
2
3## Browser
4
5### Redirection issues (HTTP Referer)
6
7Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
8
9See:
10
11- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
12- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
13- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
14
15### Firefox HTTP Referer options
16
17HTTP settings are available by browsing `about:config`, here are the available settings and their values.
18
19`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
20
21- `0`: Never send the referring URL
22 - not recommended, may break some sites
23- `1`: Send only on clicked links
24- `2` (default): Send for links and images
25
26`network.http.referer.XOriginPolicy` - Cross-domain origin policy
27
28- `0` (default): Always send
29- `1`: Send if base domains match
30- `2`: Send if hosts match
31
32`network.http.referer.spoofSource` - Referer spoofing (~faking)
33
34- `false` (default): real referer
35- `true`: spoof referer (use target URI as referer)
36 - known to break some functionality in Shaarli
37
38`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
39
40- `0`: (default): send full URI
41- `1`: scheme+host+port+path
42- `2`: scheme+host+port
43
44### Firefox, localhost and redirections
45
46`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
47been set up to spoof referers, or only accept requests from the same base domain/host,
48Shaarli redirections will not work properly.
49
50To solve this, assign a local domain to your host, e.g.
51```
52127.0.0.1 localhost desktop localhost.lan
53::1 localhost desktop localhost.lan
54```
55
56and browse Shaarli at http://localhost.lan/.
57
58Related threads:
59- [What is localhost.localdomain for?](https://bbs.archlinux.org/viewtopic.php?id=156064)
60- [Stop returning to the first page after editing a bookmark from another page](https://github.com/shaarli/Shaarli/issues/311)
61
62## Login
63
64### I forgot my password!
65
66Delete the file `data/config.php` and display the page again. You will be asked for a new login/password.
67
68### I'm locked out - Login bruteforce protection
69
70Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links.
71
72To remove the current IP bans, delete the file `data/ipbans.php`
73
74### List of all login attempts
75
76The file `data/log.txt` shows all logins (successful or failed) and bans/lifted bans.
77Search for `failed` in this file to look for unauthorized login attempts.
78
79## Hosting problems
80
81### Old PHP versions
82
83On **free.fr**: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
84and so support now the tag autocompletion but you have to do the following.
85
86At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
87
88```xml
89<IfDefine Free>
90php56 1
91</IfDefine>
92```
93
94- If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
95- On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
96- If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
97
98```php
99//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
100// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
101//if (strpos($status,'200 OK')) $title=html_extract_title($data);
102```
103
104- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
105- On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
106
107### Dates are not properly formatted
108
109Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( )
110
111### Problems on CentOS servers
112
113On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
114
115### My session expires! I can't stay logged in
116
117This can be caused by several things:
118
119- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
120- Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
121- If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
122- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
123- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
124- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
125
126## Sessions do not seem to work correctly on your server
127
128Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)).
129
130### pubsubhubbub support
131
132Download [publisher.php](https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php) at the root of your Shaarli installation and set `$GLOBALS['config']['PUBSUBHUB_URL']` in your `config.php`
diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
new file mode 100644
index 00000000..d200634f
--- /dev/null
+++ b/doc/md/Unit-tests.md
@@ -0,0 +1,155 @@
1### Setup your environment for tests
2
3The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
4
5Regarding Composer, you can either use:
6
7- a system-wide version, e.g. installed through your distro's package manager
8- a local version, downloadable [here](https://getcomposer.org/download/)
9
10#### Sample usage
11
12```bash
13# system-wide version
14$ composer install
15$ composer update
16
17# local version
18$ php composer.phar self-update
19$ php composer.phar install
20$ php composer.phar update
21```
22
23#### Install Shaarli dev dependencies
24
25```bash
26$ cd /path/to/shaarli
27$ composer update
28```
29
30#### Install and enable Xdebug to generate PHPUnit coverage reports
31
32For Debian-based distros:
33```bash
34$ aptitude install php5-xdebug
35```
36For ArchLinux:
37```bash
38$ pacman -S xdebug
39```
40
41Then add the following line to `/etc/php/php.ini`:
42```ini
43zend_extension=xdebug.so
44```
45
46#### Run unit tests
47
48Successful test suite:
49```bash
50$ make test
51
52-------
53PHPUNIT
54-------
55PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
56
57Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
58
59....................................
60
61Time: 759 ms, Memory: 8.25Mb
62
63OK (36 tests, 65 assertions)
64```
65
66Test suite with failures and errors:
67```bash
68$ make test
69-------
70PHPUNIT
71-------
72PHPUnit 4.6.9 by Sebastian Bergmann and contributors.
73
74Configuration read from /home/virtualtam/public_html/shaarli/phpunit.xml
75
76E..FF...............................
77
78Time: 802 ms, Memory: 8.25Mb
79
80There was 1 error:
81
821) LinkDBTest::testConstructLoggedIn
83Missing argument 2 for LinkDB::__construct(), called in /home/virtualtam/public_html/shaarli/tests/Link\
84DBTest.php on line 79 and defined
85
86/home/virtualtam/public_html/shaarli/application/LinkDB.php:58
87/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:79
88
89--
90
91There were 2 failures:
92
931) LinkDBTest::testCheckDBNew
94Failed asserting that two strings are equal.
95--- Expected
96+++ Actual
97@@ @@
98-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
99+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
100
101/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:121
102
1032) LinkDBTest::testCheckDBLoad
104Failed asserting that two strings are equal.
105--- Expected
106+++ Actual
107@@ @@
108-'e3edea8ea7bb50be4bcb404df53fbb4546a7156e'
109+'85eab0c610d4f68025f6ed6e6b6b5fabd4b55834'
110
111/home/virtualtam/public_html/shaarli/tests/LinkDBTest.php:133
112
113FAILURES!
114Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
115```
116
117#### Test results and coverage
118
119By default, PHPUnit will run all suitable tests found under the `tests` directory.
120
121Each test has 3 possible outcomes:
122
123- `.` - success
124- `F` - failure: the test was run but its results are invalid
125 - the code does not behave as expected
126 - dependencies to external elements: globals, session, cache...
127- `E` - error: something went wrong and the tested code has crashed
128 - typos in the code, or in the test code
129 - dependencies to missing external elements
130
131If Xdebug has been installed and activated, two coverage reports will be generated:
132
133- a summary in the console
134- a detailed HTML report with metrics for tested code
135 - to open it in a web browser: `firefox coverage/index.html &`
136
137### Executing specific tests
138
139Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
140
141```php
142/**
143 * Netscape bookmark import
144 * @group WIP
145 */
146class BookmarkImportTest extends PHPUnit_Framework_TestCase
147{
148 [...]
149}
150```
151
152To run all tests annotated with `@group WIP`:
153```bash
154$ vendor/bin/phpunit --group WIP tests/
155```
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
new file mode 100644
index 00000000..b3a08764
--- /dev/null
+++ b/doc/md/Upgrade-and-migration.md
@@ -0,0 +1,197 @@
1## Preparation
2
3### Note your current version
4
5If anything goes wrong, it's important for us to know which version you're upgrading from.
6The current version is present in the `version.php` file.
7
8### Backup your data
9
10Shaarli stores all user data under the `data` directory:
11
12- `data/config.php` - main configuration file
13- `data/datastore.php` - bookmarked links
14- `data/ipbans.php` - banned IP addresses
15- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
16
17See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
18
19It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
20
21- users with SSH access: copy or archive the directory to a temporary location
22- users with FTP access: download a local copy of your Shaarli installation using your favourite client
23
24### Migrating data from a previous installation
25
26As all user data is kept under `data`, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:
27
28- backup the `data` directory
29- install or update Shaarli:
30 - fresh installation - see [Download and installation](Download and installation)
31 - update - see the following sections
32- check or restore the `data` directory
33
34## Recommended : Upgrading from release archives
35
36All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
37
38We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download and installation) for `git` complete instructions.
39
40Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
41
42After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details).
43
44## Upgrading with Git
45
46### Updating a community Shaarli
47
48If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:
49
50```bash
51$ cd /path/to/shaarli
52$ git pull
53
54From github.com:shaarli/Shaarli
55 * branch master -> FETCH_HEAD
56Updating ebd67c6..521f0e6
57Fast-forward
58 application/Url.php | 1 +
59 shaarli_version.php | 2 +-
60 tests/Url/UrlTest.php | 1 +
61 3 files changed, 3 insertions(+), 1 deletion(-)
62```
63
64Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
65
66```bash
67$ composer install --no-dev
68
69Loading composer repositories with package information
70Updating dependencies
71 - Installing shaarli/netscape-bookmark-parser (v1.0.1)
72 Downloading: 100%
73```
74
75### Migrating and upgrading from Sebsauvage's repository
76
77If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
78
79The following guide assumes that:
80
81- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
82- the default remote is named `origin` and points to Sebsauvage's repository
83- the current branch is `master`
84 - if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break!
85- the working copy is clean:
86 - no versioned file has been locally modified
87 - no untracked files are present
88
89#### Step 0: show repository information
90
91```bash
92$ cd /path/to/shaarli
93
94$ git remote -v
95origin https://github.com/sebsauvage/Shaarli (fetch)
96origin https://github.com/sebsauvage/Shaarli (push)
97
98$ git branch -vv
99* master 029f75f [origin/master] Update README.md
100
101$ git status
102On branch master
103Your branch is up-to-date with 'origin/master'.
104nothing to commit, working directory clean
105```
106
107#### Step 1: update Git remotes
108
109```
110$ git remote rename origin sebsauvage
111$ git remote -v
112sebsauvage https://github.com/sebsauvage/Shaarli (fetch)
113sebsauvage https://github.com/sebsauvage/Shaarli (push)
114
115$ git remote add origin https://github.com/shaarli/Shaarli
116$ git fetch origin
117
118remote: Counting objects: 3015, done.
119remote: Compressing objects: 100% (19/19), done.
120remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
121Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
122Resolving deltas: 100% (1899/1899), completed with 48 local objects.
123From https://github.com/shaarli/Shaarli
124 * [new branch] master -> origin/master
125 * [new branch] stable -> origin/stable
126[...]
127 * [new tag] v0.6.4 -> v0.6.4
128 * [new tag] v0.7.0 -> v0.7.0
129```
130
131#### Step 2: use the stable community branch
132
133```bash
134$ git checkout origin/stable -b stable
135Branch stable set up to track remote branch stable from origin.
136Switched to a new branch 'stable'
137
138$ git branch -vv
139 master 029f75f [sebsauvage/master] Update README.md
140* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5
141```
142
143Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
144
145```bash
146$ composer install --no-dev
147
148Loading composer repositories with package information
149Updating dependencies
150 - Installing shaarli/netscape-bookmark-parser (v1.0.1)
151 Downloading: 100%
152```
153
154Optionally, you can delete information related to the legacy version:
155
156```bash
157$ git branch -D master
158Deleted branch master (was 029f75f).
159
160$ git remote remove sebsauvage
161
162$ git remote -v
163origin https://github.com/shaarli/Shaarli (fetch)
164origin https://github.com/shaarli/Shaarli (push)
165
166$ git gc
167Counting objects: 3317, done.
168Delta compression using up to 8 threads.
169Compressing objects: 100% (1237/1237), done.
170Writing objects: 100% (3317/3317), done.
171Total 3317 (delta 2050), reused 3301 (delta 2034)to
172```
173
174#### Step 3: configuration
175
176After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli configuration) for more details).
177
178## Troubleshooting
179
180If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
181
182### You must specify an integer as a key
183
184In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
185Take a look at `data/updates.txt` content.
186
187#### `updates.txt` contains `updateMethodDatastoreIds`
188
189Try to delete it and refresh your page while being logged in.
190
191#### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
192
1931. Create `data/updates.txt` if it doesn't exist
1942. Paste this string in the update file `;updateMethodRenameDashTags;`
1953. Login to Shaarli
1964. Delete the update file
1975. Refresh
diff --git a/doc/md/Various-hacks.md b/doc/md/Various-hacks.md
new file mode 100644
index 00000000..0074ae9f
--- /dev/null
+++ b/doc/md/Various-hacks.md
@@ -0,0 +1,33 @@
1### Decode datastore content
2
3To display the array representing the data saved in `data/datastore.php`, use the following snippet:
4
5```php
6$data = "tZNdb9MwFIb... <Commented content inside datastore.php>";
7$out = unserialize(gzinflate(base64_decode($data)));
8echo "<pre>"; // Pretty printing is love, pretty printing is life
9print_r($out);
10echo "</pre>";
11exit;
12```
13This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation).
14
15Alternatively, you can transform to JSON format (and pretty-print if you have `jq` installed):
16```
17php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/\* (.+) \*/.*!", "$1", file_get_contents("data/datastore.php")))))));' | jq .
18```
19
20### Changing the timestamp for a shaare
21
22- Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
23- Replace `type="hidden"` with `type="text"` from this line
24- A new date/time field becomes available in the edit/new link dialog.
25- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
26
27
28### See also
29
30- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
31- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
32- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
33- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)
diff --git a/doc/md/Versioning-and-Branches.md b/doc/md/Versioning-and-Branches.md
new file mode 100644
index 00000000..7097ca0a
--- /dev/null
+++ b/doc/md/Versioning-and-Branches.md
@@ -0,0 +1,75 @@
1**WORK IN PROGRESS**
2
3It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.
4
5## `master` branch
6
7The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
8
9Remarks:
10
11- This branch shouldn't be used for production as it isn't necessary stable.
12- 3rd party aren't required to be compatible with the latest changes.
13- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
14- The version in this branch is always `dev`.
15
16## `v0.x` branch
17
18This `v0.x` branch, points to the latest `v0.x.y` release.
19
20Explanation:
21
22When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.
23
24In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch.
25
26This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
27
28## `latest` branch
29
30This branch point the latest release. It recommended to use it to get the latest tested changes.
31
32## `stable` branch
33
34The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release.
35
36For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release.
37
38Remarks:
39
40- Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
41
42## Releases
43
44Releases are always made from the latest `v0.x` branch.
45
46Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
47
48## Advices on 3rd party git repos workflow
49
50### Versioning
51
52Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:
53
54 - use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
55 - use your own versioning scheme, and state Shaarli compatibility in the release description.
56
57Using this, any user will be able to pick the release matching his own Shaarli version.
58
59### Major bugfix backport releases
60
61To be able to support backported fixes, it recommended to use our workflow:
62
63```bash
64# In master, fix the major bug
65git commit -m "Katastrophe"
66git push origin master
67# Get your commit hash
68git log --format="%H" -n 1
69# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
70git checkout -b katastrophe v0.8.2-1
71# Backport the fix commit to your brand new branch
72git cherry-pick <fix commit hash>
73git push origin katastrophe
74# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
75```
diff --git a/doc/md/docker/docker-101.md b/doc/md/docker/docker-101.md
new file mode 100644
index 00000000..b02dd149
--- /dev/null
+++ b/doc/md/docker/docker-101.md
@@ -0,0 +1,62 @@
1## Basics
2Install [Docker](https://www.docker.com/), by following the instructions relevant
3to your OS / distribution, and start the service.
4
5### Search an image on [DockerHub](https://hub.docker.com/)
6
7```bash
8$ docker search debian
9
10NAME DESCRIPTION STARS OFFICIAL AUTOMATED
11ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]
12debian Debian is a Linux distribution that's comp... 603 [OK]
13google/debian 47 [OK]
14```
15
16### Show available tags for a repository
17```bash
18$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool
19
20% Total % Received % Xferd Average Speed Time Time Time Current
21Dload Upload Total Spent Left Speed
22100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433
23```
24
25Sample output:
26```json
27[
28 {
29 "layer": "85a02782",
30 "name": "stretch"
31 },
32 {
33 "layer": "59abecbc",
34 "name": "testing"
35 },
36 {
37 "layer": "bf0fd686",
38 "name": "unstable"
39 },
40 {
41 "layer": "60c52dbe",
42 "name": "wheezy"
43 },
44 {
45 "layer": "c5b806fe",
46 "name": "wheezy-backports"
47 }
48]
49
50```
51
52### Pull an image from DockerHub
53```bash
54$ docker pull repository[:tag]
55
56$ docker pull debian:wheezy
57wheezy: Pulling from debian
584c8cbfd2973e: Pull complete
5960c52dbe9d91: Pull complete
60Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
61Status: Downloaded newer image for debian:wheezy
62```
diff --git a/doc/md/docker/resources.md b/doc/md/docker/resources.md
new file mode 100644
index 00000000..082d4a46
--- /dev/null
+++ b/doc/md/docker/resources.md
@@ -0,0 +1,19 @@
1### Docker
2
3- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
4- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)
5- [Dockerfile reference](https://docs.docker.com/reference/builder/)
6- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
7- [Volumes](https://docs.docker.com/userguide/dockervolumes/)
8
9### DockerHub
10
11- [Repositories](https://docs.docker.com/userguide/dockerrepos/)
12- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/)
13- [GitHub automated build](https://docs.docker.com/docker-hub/github/)
14
15### Service management
16
17- [Using supervisord](https://docs.docker.com/articles/using_supervisord/)
18- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
19- [supervisord](http://supervisord.org/)
diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md
new file mode 100644
index 00000000..91ffecff
--- /dev/null
+++ b/doc/md/docker/reverse-proxy-configuration.md
@@ -0,0 +1,6 @@
1
2TODO, see https://github.com/shaarli/Shaarli/issues/888
3
4## HAProxy
5
6## Nginx
diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md
new file mode 100644
index 00000000..6d108d21
--- /dev/null
+++ b/doc/md/docker/shaarli-images.md
@@ -0,0 +1,71 @@
1## Get and run a Shaarli image
2
3### DockerHub repository
4The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/)
5repository.
6
7### Available image tags
8- `latest`: master branch (tarball release)
9- `stable`: stable branch (tarball release)
10
11All images rely on:
12- [Debian 8 Jessie](https://hub.docker.com/_/debian/)
13- [PHP5-FPM](http://php-fpm.org/)
14- [Nginx](http://nginx.org/)
15
16### Download from DockerHub
17```bash
18$ docker pull shaarli/shaarli
19latest: Pulling from shaarli/shaarli
2032716d9fcddb: Pull complete
2184899d045435: Pull complete
224b6ad7444763: Pull complete
23e0345ef7a3e0: Pull complete
245c1dd344094f: Pull complete
256422305a200b: Pull complete
267d63f861dbef: Pull complete
273eb97210645c: Pull complete
28869319d746ff: Already exists
29869319d746ff: Pulling fs layer
30902b87aaaec9: Already exists
31Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98
32Status: Downloaded newer image for shaarli/shaarli:latest
33```
34
35### Create and start a new container from the image
36```bash
37# map the host's :8000 port to the container's :80 port
38$ docker create -p 8000:80 shaarli/shaarli
39d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
40
41# launch the container in the background
42$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
43d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
44
45# list active containers
46$ docker ps
47CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
48d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo
49```
50
51### Stop and destroy a container
52```bash
53$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
54backstabbing_galileo
55
56# check the container is stopped
57$ docker ps
58CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
59
60# list ALL containers
61$ docker ps -a
62CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
63d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo
64
65# destroy the container
66$ docker rm backstabbing_galileo # let's put an end to these barbarian practices
67backstabbing_galileo
68
69$ docker ps -a
70CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
71```
diff --git a/doc/md/images/bookmarklet.png b/doc/md/images/bookmarklet.png
new file mode 100644
index 00000000..0262578e
--- /dev/null
+++ b/doc/md/images/bookmarklet.png
Binary files differ
diff --git a/doc/md/images/doc-logo.png b/doc/md/images/doc-logo.png
new file mode 100644
index 00000000..3d8d1787
--- /dev/null
+++ b/doc/md/images/doc-logo.png
Binary files differ
diff --git a/doc/md/images/doc-logo.svg b/doc/md/images/doc-logo.svg
new file mode 100644
index 00000000..37fc6658
--- /dev/null
+++ b/doc/md/images/doc-logo.svg
@@ -0,0 +1,522 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<svg
3 xmlns:dc="http://purl.org/dc/elements/1.1/"
4 xmlns:cc="http://creativecommons.org/ns#"
5 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
6 xmlns:svg="http://www.w3.org/2000/svg"
7 xmlns="http://www.w3.org/2000/svg"
8 xmlns:xlink="http://www.w3.org/1999/xlink"
9 width="600"
10 height="240"
11 id="svg2"
12 version="1.1">
13 <title
14 id="title6384">Shaarli Logo</title>
15 <defs
16 id="defs4">
17 <linearGradient
18 id="linearGradient4405">
19 <stop
20 style="stop-color:#000000;stop-opacity:1;"
21 offset="0"
22 id="stop4407" />
23 <stop
24 style="stop-color:#ffffff;stop-opacity:1;"
25 offset="1"
26 id="stop4409" />
27 </linearGradient>
28 <linearGradient
29 id="linearGradient3780">
30 <stop
31 style="stop-color:#8aea00;stop-opacity:1;"
32 offset="0"
33 id="stop3782" />
34 <stop
35 style="stop-color:#ebff36;stop-opacity:1;"
36 offset="1"
37 id="stop3784" />
38 </linearGradient>
39 <linearGradient
40 id="linearGradient4333-6-7">
41 <stop
42 style="stop-color:#ffffff;stop-opacity:1;"
43 offset="0"
44 id="stop4335-0-4" />
45 <stop
46 style="stop-color:#e1e1e1;stop-opacity:1;"
47 offset="1"
48 id="stop4337-49-0" />
49 </linearGradient>
50 <linearGradient
51 xlink:href="#linearGradient4333-6-7"
52 id="linearGradient4435"
53 gradientUnits="userSpaceOnUse"
54 gradientTransform="translate(-606.51586,-487.01655)"
55 x1="845.7998"
56 y1="637.30005"
57 x2="845.7998"
58 y2="509.84348" />
59 <linearGradient
60 xlink:href="#linearGradient3780"
61 id="linearGradient4437"
62 gradientUnits="userSpaceOnUse"
63 gradientTransform="translate(-1434.0326,365.55395)"
64 x1="1984.2427"
65 y1="-348.63434"
66 x2="1984.2427"
67 y2="-293.69879" />
68 <linearGradient
69 xlink:href="#linearGradient4333-6-7"
70 id="linearGradient4439"
71 gradientUnits="userSpaceOnUse"
72 gradientTransform="translate(-699.19746,-487.01655)"
73 x1="845.7998"
74 y1="637.30005"
75 x2="845.7998"
76 y2="509.84348" />
77 <linearGradient
78 xlink:href="#linearGradient4333-6-7"
79 id="linearGradient4441"
80 gradientUnits="userSpaceOnUse"
81 gradientTransform="translate(-699.87915,-487.01655)"
82 x1="845.7998"
83 y1="637.30005"
84 x2="845.7998"
85 y2="509.84348" />
86 <linearGradient
87 xlink:href="#linearGradient4333-6-7"
88 id="linearGradient4443"
89 gradientUnits="userSpaceOnUse"
90 gradientTransform="translate(-703.2869,-487.01655)"
91 x1="845.7998"
92 y1="637.30005"
93 x2="845.7998"
94 y2="509.84348" />
95 <linearGradient
96 xlink:href="#linearGradient4333-6-7"
97 id="linearGradient4445"
98 gradientUnits="userSpaceOnUse"
99 gradientTransform="translate(-701.24225,-487.01655)"
100 x1="845.7998"
101 y1="637.30005"
102 x2="845.7998"
103 y2="509.84348" />
104 <linearGradient
105 xlink:href="#linearGradient4333-6-7"
106 id="linearGradient4447"
107 gradientUnits="userSpaceOnUse"
108 gradientTransform="translate(-699.1976,-487.01655)"
109 x1="845.7998"
110 y1="637.30005"
111 x2="845.7998"
112 y2="509.84348" />
113 <linearGradient
114 xlink:href="#linearGradient4333-6-7"
115 id="linearGradient4449"
116 gradientUnits="userSpaceOnUse"
117 gradientTransform="translate(-701.24225,-487.01655)"
118 x1="845.7998"
119 y1="637.30005"
120 x2="845.7998"
121 y2="509.84348" />
122 <linearGradient
123 xlink:href="#linearGradient4333-6-7"
124 id="linearGradient4451"
125 gradientUnits="userSpaceOnUse"
126 gradientTransform="translate(-701.24225,-487.01655)"
127 x1="845.7998"
128 y1="637.30005"
129 x2="845.7998"
130 y2="509.84348" />
131 <linearGradient
132 xlink:href="#linearGradient4333-6-7"
133 id="linearGradient4453"
134 gradientUnits="userSpaceOnUse"
135 gradientTransform="translate(-701.24225,-487.01655)"
136 x1="845.7998"
137 y1="637.30005"
138 x2="845.7998"
139 y2="509.84348" />
140 <linearGradient
141 y2="509.84348"
142 x2="845.7998"
143 y1="637.30005"
144 x1="845.7998"
145 gradientTransform="translate(-701.24225,-487.01655)"
146 gradientUnits="userSpaceOnUse"
147 id="linearGradient6071"
148 xlink:href="#linearGradient4333-6-7" />
149 <linearGradient
150 y2="509.84348"
151 x2="845.7998"
152 y1="637.30005"
153 x1="845.7998"
154 gradientTransform="translate(-701.24225,-487.01655)"
155 gradientUnits="userSpaceOnUse"
156 id="linearGradient6073"
157 xlink:href="#linearGradient4333-6-7" />
158 <linearGradient
159 y2="509.84348"
160 x2="845.7998"
161 y1="637.30005"
162 x1="845.7998"
163 gradientTransform="translate(-701.24225,-487.01655)"
164 gradientUnits="userSpaceOnUse"
165 id="linearGradient6075"
166 xlink:href="#linearGradient4333-6-7" />
167 <linearGradient
168 y2="509.84348"
169 x2="845.7998"
170 y1="637.30005"
171 x1="845.7998"
172 gradientTransform="translate(-699.1976,-487.01655)"
173 gradientUnits="userSpaceOnUse"
174 id="linearGradient6077"
175 xlink:href="#linearGradient4333-6-7" />
176 <linearGradient
177 y2="509.84348"
178 x2="845.7998"
179 y1="637.30005"
180 x1="845.7998"
181 gradientTransform="translate(-701.24225,-487.01655)"
182 gradientUnits="userSpaceOnUse"
183 id="linearGradient6079"
184 xlink:href="#linearGradient4333-6-7" />
185 <linearGradient
186 y2="509.84348"
187 x2="845.7998"
188 y1="637.30005"
189 x1="845.7998"
190 gradientTransform="translate(-703.2869,-487.01655)"
191 gradientUnits="userSpaceOnUse"
192 id="linearGradient6081"
193 xlink:href="#linearGradient4333-6-7" />
194 <linearGradient
195 y2="509.84348"
196 x2="845.7998"
197 y1="637.30005"
198 x1="845.7998"
199 gradientTransform="translate(-699.87915,-487.01655)"
200 gradientUnits="userSpaceOnUse"
201 id="linearGradient6083"
202 xlink:href="#linearGradient4333-6-7" />
203 <linearGradient
204 y2="509.84348"
205 x2="845.7998"
206 y1="637.30005"
207 x1="845.7998"
208 gradientTransform="translate(-699.19746,-487.01655)"
209 gradientUnits="userSpaceOnUse"
210 id="linearGradient6085"
211 xlink:href="#linearGradient4333-6-7" />
212 <linearGradient
213 y2="-293.69879"
214 x2="1984.2427"
215 y1="-348.63434"
216 x1="1984.2427"
217 gradientTransform="translate(-1434.0326,365.55395)"
218 gradientUnits="userSpaceOnUse"
219 id="linearGradient6087"
220 xlink:href="#linearGradient3780" />
221 <linearGradient
222 y2="509.84348"
223 x2="845.7998"
224 y1="637.30005"
225 x1="845.7998"
226 gradientTransform="translate(-606.51586,-487.01655)"
227 gradientUnits="userSpaceOnUse"
228 id="linearGradient6089"
229 xlink:href="#linearGradient4333-6-7" />
230 <linearGradient
231 y2="-5.3252554"
232 x2="1795.8763"
233 y1="-116.8399"
234 x1="1795.8763"
235 gradientTransform="translate(-1431.3064,219.11539)"
236 gradientUnits="userSpaceOnUse"
237 id="linearGradient6095"
238 xlink:href="#linearGradient4405" />
239 <mask
240 id="mask6091"
241 maskUnits="userSpaceOnUse">
242 <rect
243 y="11.978719"
244 x="8.1208458"
245 height="153.34807"
246 width="582.72266"
247 id="rect6093"
248 style="color:#000000;fill:url(#linearGradient6095);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:0" />
249 </mask>
250 </defs>
251 <metadata
252 id="metadata7">
253 <rdf:RDF>
254 <cc:Work
255 rdf:about="">
256 <dc:format>image/svg+xml</dc:format>
257 <dc:type
258 rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
259 <dc:title>Shaarli Logo</dc:title>
260 <dc:creator>
261 <cc:Agent>
262 <dc:title>http://blog.idleman.fr/</dc:title>
263 </cc:Agent>
264 </dc:creator>
265 <dc:date>2012-08-29 22:36:01+02:00</dc:date>
266 <dc:publisher>
267 <cc:Agent>
268 <dc:title>http://sebsauvage.net/</dc:title>
269 </cc:Agent>
270 </dc:publisher>
271 <dc:subject>
272 <rdf:Bag>
273 <rdf:li>Shaarli</rdf:li>
274 <rdf:li>Logo</rdf:li>
275 </rdf:Bag>
276 </dc:subject>
277 <dc:contributor>
278 <cc:Agent>
279 <dc:title>http://thatguynamedandy.com/,
280http://mro.name/me</dc:title>
281 </cc:Agent>
282 </dc:contributor>
283 <cc:license
284 rdf:resource="http://www.opensource.org/licenses/zlib-license.php" />
285 <dc:source>http://sebsauvage.net/files/shaarli_logo.zip</dc:source>
286 <dc:relation>http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion#comment_09a1e91bc0abc7db6d186a6abf429877</dc:relation>
287 </cc:Work>
288 </rdf:RDF>
289 </metadata>
290 <g
291 style="display:inline"
292 id="layer9">
293 <g
294 id="g6232">
295 <g
296 style="display:inline"
297 id="g5987"
298 transform="matrix(1,0,0,-1,0,323.7441)"
299 mask="url(#mask6091)">
300 <path
301 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
302 d="m 549.36434,78.11349 c -9.4946,1.99352 -9.7027,14.03504 -9.8352,21.77668 0.1121,11.0831 -0.2095,22.9628 4.1417,33.27264 2.0054,4.85047 9.7812,4.74809 10.3195,-1.06753 4.7624,-15.20498 4.7481,-32.01281 1.4946,-47.50541 -0.983,-2.75668 -3.069,-6.35036 -6.1206,-6.47638 z"
303 id="path5989" />
304 <path
305 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
306 d="m 499.48944,47.6175 c -6.4927,-0.34021 -9.3439,6.60543 -8.1121,12.16941 -0.5858,24.07597 -0.3292,48.31194 0.034,72.30837 1.7508,6.96484 14.895,8.48808 15.0166,-0.0712 1.2169,-13.27189 -0.274,-26.75029 0.6639,-40.10232 0.7817,-11.41478 -0.5568,-23.24296 -0.6994,-34.37618 1.5849,-5.10643 -0.4706,-11.12871 -6.9034,-9.92811 z"
307 id="path5991" />
308 <path
309 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
310 d="m 132.42293,35.23407 c -7.6945,2.17125 -5.9206,12.79289 -6.2273,19.00216 1.6106,23.24538 0.8475,46.57408 2.1706,69.81693 0.068,7.09423 3.2021,16.90233 11.8853,16.22657 7.5709,-1.76417 5.7778,-11.8325 5.6557,-17.71589 -0.047,-7.84014 -4.5559,-19.23884 3.9165,-24.30949 7.6405,-5.37547 19.848,0.64078 18.6463,10.39069 -0.3251,8.83089 -2.0837,22.16882 7.8287,26.47493 6.4024,2.92649 10.6176,-5.21693 9.3943,-10.71096 -0.3749,-13.55442 1.2727,-30.22607 -10.711,-39.6768 -7.9735,-4.05845 -18.9828,-5.54515 -26.8307,-0.21351 -1.0372,2.42576 -6.9951,6.95054 -6.4053,1.24546 -1.6949,-15.3749 2.056,-31.45755 -2.3485,-46.40228 -1.2024,-2.63946 -4.0324,-4.45898 -6.9746,-4.12781 z"
311 id="path5993" />
312 <path
313 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
314 d="m 442.14024,64.05759 c -10.165,-0.2579 -20.6562,1.86137 -28.1474,9.18081 -2.8958,2.05591 -1.2663,-4.94966 -4.8395,-5.01742 -5.4074,-2.93338 -11.5829,2.98762 -9.5367,8.75381 0.099,20.06919 -1.977,40.97889 3.8787,60.387 3.1796,4.95849 13.7562,4.09337 12.7037,-2.9891 1.546,-15.53942 -2.968,-32.10549 3.167,-46.86488 4.3319,-8.66318 18.41,-14.13659 25.3718,-5.90704 3.521,6.12624 -0.9752,16.78774 6.8323,20.31879 7.6504,1.3481 9.6041,-9.08157 8.825,-14.7676 -1.6539,-6.72434 -2.1565,-14.5353 -6.6544,-19.99852 -3.1376,-2.78799 -7.564,-3.22067 -11.6005,-3.09585 z"
315 id="path5995" />
316 <path
317 style="color:#000000;fill:url(#linearGradient6071);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
318 d="m 442.38294,54.04595 c -0.1827,-0.005 -0.3789,0.0345 -0.5625,0.0312 -8.6942,-0.15632 -18.301,1.16995 -26.7813,5.96876 -0.368,-0.21564 -0.7676,-0.37654 -1.1562,-0.5625 l 0.031,-0.0625 c -0.2019,-0.10958 -0.4204,-0.1194 -0.625,-0.21875 -0.5569,-0.23563 -1.1103,-0.37966 -1.6874,-0.53125 -6.0741,-2.10894 -12.7994,-0.4336 -16.8438,3.34375 -3.8577,3.60298 -6.0063,9.29062 -5.1562,15.125 0.085,19.31578 -2.292,41.23535 4.3124,63.12499 l 0.4063,1.3125 0.75,1.1875 c 4.4521,6.94297 11.5862,8.53059 18,7.46875 3.2069,-0.53092 6.701,-1.89897 9.5,-5.03125 2.2725,-2.54317 3.5121,-6.27514 3.5937,-9.84375 0,-0.0435 0,-0.0816 0,-0.125 1.7478,-17.81793 -1.8544,-32.72457 2.2813,-43.375 0.6976,-1.23208 3.1856,-3.39065 5.4063,-4.03125 1.1119,-0.32077 1.7363,-0.44325 2.1874,-0.40625 0.051,0.8996 0.2789,2.71568 0.5313,6.0625 0.1821,2.41445 0.4732,5.42185 2.0313,8.8125 1.558,3.39065 4.8419,6.94014 8.8437,8.75 l 1.1563,0.5 1.2187,0.21875 c 4.1545,0.73208 8.9361,-0.28467 12.2187,-2.59375 3.2827,-2.30908 5.1358,-5.31163 6.3126,-8.0625 2.3534,-5.50175 2.5912,-10.54096 1.9374,-15.3125 l -0.062,-0.53125 -0.125,-0.5 c -1.3372,-5.43656 -1.418,-15.17693 -8.6563,-23.96874 l -0.4687,-0.59375 -0.5938,-0.53125 c -6.0316,-5.35952 -13.0425,-5.71213 -18,-5.59376 l 0,-0.0312 z m -20.9688,14.62501 c 0.3103,0.61975 0.1924,0.76755 0.063,0.28125 -0.016,-0.0599 -0.046,-0.21107 -0.063,-0.28125 z m -11.8437,14.15624 c 0.271,0.10418 0.5347,0.22752 0.8125,0.3125 l -0.125,0.21875 -0.125,0.3125 c -0.2313,0.55649 -0.3535,1.10135 -0.5625,1.65625 0.01,-0.84699 -0.01,-1.64903 0,-2.5 z"
319 id="path5997" />
320 <path
321 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:38"
322 d="m 334.93614,43.42895 -1.125,0.0625 c -11.4541,0.68757 -31.1299,2.13948 -42.5313,20.5 l -0.6875,1.15625 -0.5312,1.21875 c -4.0155,9.09454 -1.1737,19.34928 5,25.5 -7.1006,9.03999 -10.5361,20.69833 -9.25,32.65625 -0.7932,13.71238 8.5163,26.58972 21.5624,30.34375 l -0.031,0.0625 c 14.5936,5.02387 28.3345,3.89176 40,1.875 1.1383,0.61027 2.377,1.24208 3.8438,1.84375 3.1932,1.30991 7.6804,2.60895 13.1874,1.96875 5.5071,-0.6402 11.3463,-3.71585 15.0626,-7.53125 l 0.6562,-0.6875 0.5938,-0.75 c 7.375,-9.27994 7.6766,-20.19393 7.1874,-26.8125 -0.4891,-6.61857 -1.0653,-10.99648 -1.0312,-11.375 l 0.125,-1.46875 -0.094,-1.5 c -0.9045,-13.69999 -0.4438,-31.50909 -8.6874,-49.71875 -0.8869,-3.14352 -2.6183,-4.60975 -5,-6.625 -14.193,-12.04738 -29.8012,-10.22761 -37.125,-10.65625 z m -5,69.25 c -0.6975,0.25422 -0.096,-0.059 3.5937,0.375 3.1757,0.3735 8.4922,1.29071 15.3437,0.34375 -0.042,1.60674 -0.047,3.10046 0.031,4.46875 l -1.2187,0.25 c -9.4296,1.92946 -17.7526,2.70557 -24.0626,1.71875 0.3089,-2.61777 2.5558,-6.11412 4.2813,-6.53125 l 1.0313,-0.25 1,-0.375 z"
323 id="path5999" />
324 <path
325 id="path6001"
326 d="m 242.86794,62.94328 c -9.8451,0.59098 -21.9234,2.57343 -27.5069,11.56498 -1.5225,3.44827 2.5155,7.16458 5.8003,4.55483 11.6876,-3.18405 25.8772,-8.64334 36.9368,-1.03196 3.4255,4.6575 3.2712,13.73214 -2.1351,16.8315 -8.1137,1.83399 -16.456,-2.50178 -24.589,0.4626 -12.7407,3.08001 -20.924,16.83116 -18.6463,29.53519 -1.221,6.03853 2.7535,11.58045 8.7182,12.59694 12.2603,4.22059 25.7141,2.25842 37.9688,-0.24909 3.9671,2.72001 9.7011,7.85911 14.3406,3.09585 6.2596,-7.87653 1.273,-19.02318 2.088,-28.06851 -0.9577,-14.50429 -1.0481,-29.91302 -7.0343,-43.1362 -7.0905,-6.01862 -17.2216,-5.6458 -25.9411,-6.15613 z"
327 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
328 <path
329 style="color:#000000;fill:url(#linearGradient6073);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
330 d="m 132.71733,24.19589 c -0.5004,0.0152 -1.0205,0.0363 -1.5312,0.0937 l -0.9063,0.0937 -0.8437,0.25 c -4.2861,1.20943 -8.1936,4.24904 -10.375,7.56249 -2.1816,3.31346 -2.9841,6.56659 -3.4063,9.375 -0.8444,5.61682 -0.3823,10.37282 -0.4687,12.125 l -0.031,0.65625 0.062,0.625 c 1.548,22.34205 0.8033,45.46456 2.125,69.1875 5e-4,0.0505 0.031,0.10568 0.031,0.15625 0.01,0.1151 -0.01,0.22862 0,0.34375 l 0.031,0 c 0.099,4.98929 0.9665,10.43113 4.125,15.90625 3.2605,5.65198 11.0145,11.32149 19.5625,10.65625 l 0.8438,-0.0625 0.8124,-0.1875 c 4.2384,-0.98762 8.3269,-3.79564 10.625,-7.09375 2.1728,-3.63384 4.3342,-6.89183 5.1872,-10.22818 3.8402,7.13335 5.9507,8.04619 13.1566,11.44693 l 0,0.0312 c 0.059,0.0269 0.1281,0.0362 0.1875,0.0625 3.7423,1.65403 8.4312,1.97661 12.2813,0.65625 3.91101,-1.34132 6.71761,-3.90092 8.59371,-6.5 3.336,-4.62154 4.6441,-9.64143 3.9063,-15.25 -0.1718,-6.20746 0.2238,-14.23226 -1.1563,-22.8125 -1.3801,-8.58024 -5.0962,-18.36284 -13.75001,-25.1875 l -0.8437,-0.6875 -0.9688,-0.5 c -7.7653,-3.95251 -17.7087,-6.355 -27.4062,-4.09375 0.4086,-10.28331 1.089,-21.96033 -2.625,-34.5625 l -0.2188,-0.75 -0.3125,-0.71875 c -2.9167,-6.40275 -9.181,-10.82231 -16.6875,-10.59374 z m 6.0625,53.99999 c 0,0.0101 0.05,0.0315 0.062,0.0625 l -0.6245,1.46875 c 0.3311,-0.86163 0.5542,-1.56647 0.5625,-1.53125 z m 36.0625,48.28125 c 0.012,-0.004 0.019,0.005 0.031,0 l 0.063,0.3125 c -0.043,-0.19086 -0.061,-0.25465 -0.094,-0.3125 z"
331 id="path6003" />
332 <path
333 style="fill:#484848;fill-opacity:1;stroke:none"
334 id="path6005"
335 d="m 133.3461,36.09636 c -1.692,0.49428 -2.8155,1.39846 -3.625,2.625 -0.8214,1.24442 -1.3243,2.85069 -1.5938,4.625 -0.5342,3.51732 -0.1953,7.61208 -0.3438,10.8125 0,0.0285 0,0.0654 0,0.0937 1.6063,23.27388 0.8692,46.5905 2.1876,69.75 a 0.88388823,0.88388823 0 0 1 0,0.0625 c 0.033,3.4213 0.83,7.53419 2.5937,10.59375 1.7438,3.02495 4.2922,5.00636 8.2187,4.75 0.011,-7.3e-4 0.02,7.7e-4 0.031,0 1.6857,-0.39978 2.7542,-1.19719 3.5313,-2.3125 0.7819,-1.12237 1.2391,-2.59827 1.4687,-4.25 0.4593,-3.30346 2e-4,-7.22907 -0.062,-10.25 a 0.88388823,0.88388823 0 0 1 0,-0.0312 c -0.023,-3.75401 -1.179,-8.58343 -1.25,-13.1875 -0.071,-4.59014 1.0512,-9.12033 5.5625,-11.84375 0.012,-0.008 0.019,-0.023 0.031,-0.0312 8.2411,-5.75335 21.2001,0.72746 19.9687,11.1875 0,0.011 0,0.0202 0,0.0312 -4e-4,0.01 4e-4,0.0216 0,0.0312 -0.1662,4.44678 -0.6416,9.92071 0.094,14.71875 0.7386,4.81878 2.5857,8.83105 7.2188,10.84375 a 0.88388823,0.88388823 0 0 1 0.031,0 c 1.4264,0.65196 2.625,0.67804 3.6876,0.3125 1.0625,-0.36554 2.0152,-1.15367 2.7812,-2.21875 1.532,-2.13016 2.2012,-5.36524 1.6562,-7.8125 a 0.88388823,0.88388823 0 0 1 0,-0.15625 c -0.1887,-6.82351 0.1073,-14.35845 -1,-21.28125 -1.1026,-6.89383 -3.5864,-13.13587 -9.3124,-17.6875 -7.7294,-3.90433 -18.3437,-5.25802 -25.7813,-0.25 -0.7734,1.48479 -2.3237,3.00623 -4,3.78125 -0.9043,0.41808 -1.982,0.65336 -2.875,0.0312 -0.8519,-0.59346 -1.0866,-1.72753 -0.9687,-3.1875 0.01,-0.0705 -0.01,-0.11538 0,-0.1875 -1.6634,-15.48034 1.9617,-31.38045 -2.2813,-45.9375 -1.0363,-2.2749 -3.4784,-3.85945 -5.9687,-3.625 z" />
336 <path
337 style="color:#000000;fill:url(#linearGradient6075);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
338 d="m 500.00794,37.6397 c -0.47,-0.0246 -0.9099,0.13839 -1.375,0.15625 -0.3182,0.036 -0.6564,-0.0583 -0.9688,0 l 0,0.0937 c -5.9486,0.59666 -11.3199,4.27914 -13.8124,8.625 -2.5191,4.39212 -3.1643,9.07388 -2.4688,13.75001 -0.5691,24.07161 -0.3288,48.17845 0.031,71.96874 l 0.031,1.1875 0.2813,1.125 c 2.2758,9.05358 10.1204,12.94327 17.2812,13.3125 3.5804,0.18461 7.6057,-0.50128 11.25,-3.21875 3.4431,-2.56742 5.753,-7.21537 6.0625,-11.6875 l 0.062,0 c 0.024,-0.26477 0.01,-0.51719 0.031,-0.78125 1.2169,-14.32127 -0.1813,-27.63851 0.6563,-39.5625 0.8412,-12.28307 -0.4559,-23.97948 -0.6563,-34.18749 0.9168,-4.19732 0.7514,-8.64033 -1.75,-13.09376 -2.5398,-4.52202 -8.6787,-7.57722 -14.4374,-7.5625 -0.073,1.9e-4 -0.1457,-0.001 -0.2188,0 l 0,-0.125 z m -0.4375,10.46875 1.5625,8.375 c -0.089,0.0884 -0.5399,0.26586 -0.9688,0.50001 -0.4433,-0.17558 -0.588,-0.31717 -1.125,-0.59376 l 0.5313,-8.28125 z m 1.625,8.6875 0.125,0.65626 c 0,-5.2e-4 -0.146,-0.0578 -0.1563,-0.0625 0.013,-0.26164 0.01,-0.41632 0.031,-0.59376 z"
339 id="path6007" />
340 <path
341 style="fill:#484848;fill-opacity:1;stroke:none"
342 d="m 499.48944,47.6175 c -6.4927,-0.34021 -9.3439,6.60543 -8.1121,12.16941 -0.5858,24.07597 -0.3292,48.31194 0.034,72.30837 1.7508,6.96484 14.895,8.48808 15.0166,-0.0712 1.2169,-13.27189 -0.274,-26.75029 0.6639,-40.10232 0.7817,-11.41478 -0.5568,-23.24296 -0.6994,-34.37618 1.5849,-5.10643 -0.4706,-11.12871 -6.9034,-9.92811 z"
343 id="path6009" />
344 <path
345 style="fill:#000000;fill-opacity:1;stroke:none"
346 d="m 544.51954,53.6313 c -7.5784,-0.46784 -10.6755,10.08558 -4.626,14.19825 6.4831,5.13984 16.9776,-2.57743 12.9884,-10.24836 -1.4384,-3.20261 -5.1136,-4.25984 -8.3624,-3.94989 z"
347 id="path6011" />
348 <path
349 style="fill:#484848;fill-opacity:1;stroke:#484848;stroke-width:38;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
350 d="m 66.312222,57.93009 c -17.370703,0.62829 -30.0641,20.09681 -26.023403,36.39781 2.1928,10.05075 13.8541,12.09708 22.635103,11.4922 7.1377,-0.5151 17.6041,2.45346 16.7319,11.49222 -1.8676,6.29718 -10.9897,4.97438 -16.0667,5.21679 -7.019003,0.3042 -14.551803,-2.83467 -21.309203,-1.0251 -5.546297,3.71601 -0.7698,11.63178 4.4362,13.09902 11.6204,3.85396 24.776703,2.98561 36.677203,0.52396 8.494404,-1.78465 13.976704,-9.66183 14.007304,-18.12905 0.5362,-8.45978 -0.1252,-18.85777 -9.082,-22.63511 -7.833304,-4.5437 -17.524404,-2.59996 -25.744004,-4.64578 -6.504303,-3.75215 -4.590203,-15.08325 3.2137,-15.54417 8.376,-2.645 16.5844,3.54335 24.730904,1.74653 6.8027,-2.75685 5.6777,-13.26551 -1.2924,-15.19486 C 82.177322,57.19274 73.972122,57.9802 66.312222,57.93009 Z"
351 id="path6013" />
352 <path
353 style="color:#000000;fill:url(#linearGradient6077);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
354 d="m 66.146122,46.92095 -0.2187,0.0312 c -25.268203,0.91394 -41.9786,26.29641 -36.375,49.71875 0,0.01 0,0.0214 0,0.0312 0.023,0.0937 0.039,0.18758 0.062,0.28125 l 0.062,0 c 1.4158,6.03031 5.2241,10.72981 9.5937,13.9375 l -1.5937,0.4375 -1.5313,1 c -3.4934,2.34058 -6.2461,6.40677 -7.0312,10.4375 -0.7852,4.03073 0.016,7.64447 1.2812,10.53125 2.4625,5.61698 6.4364,9.72109 12.843797,11.6875 l 0,0.0312 c 0.1235,0.0409 0.2514,0.0537 0.375,0.0937 0.044,0.0142 0.081,0.0484 0.125,0.0625 14.2876,4.59699 29.052403,3.33987 41.875007,0.6875 l 0.031,0 c 13.703,-2.87897 22.354804,-15.23519 22.687504,-28.1875 l 0.031,0 c 0.01,-0.1043 -0.01,-0.23849 0,-0.34375 0,-0.10511 0.031,-0.20733 0.031,-0.3125 l -0.031,0 c 0.275,-4.68022 0.3633,-10.21921 -1.4063,-16.21875 -1.6128,-5.46789 -5.6186,-11.40935 -11.718704,-15.03125 C 110.28983,79.05558 108.57813,56.15757 93.550926,50.6395 83.076822,45.62854 73.121622,46.96476 66.394622,46.92075 l -0.25,0 z M 49.927419,124.0772 c 0.4736,0.11312 0.7429,0.17483 0.6875,0.1875 -0.1379,-0.0437 -0.3009,-0.0484 -0.4375,-0.0937 l -0.25,-0.0937 z"
355 id="path6015" />
356 <path
357 style="fill:#484848;fill-opacity:1;stroke:none"
358 id="path6017"
359 d="M 67.047,59.37761 C 50.7565,60.01346 38.6203,78.63489 42.422,93.97136 a 1.4420115,1.4420115 0 0 1 0,0.0312 c 0.9874,4.52574 3.9833,7.14275 7.9688,8.71875 3.9854,1.576 8.921,1.948 13.1562,1.65625 3.8182,-0.27555 8.4163,0.35581 12.1562,2.34375 3.74,1.98794 6.6157,5.6345 6.125,10.71875 a 1.4420115,1.4420115 0 0 1 -0.062,0.28125 c -0.5618,1.89409 -1.746,3.32797 -3.1876,4.25 -1.4415,0.92203 -3.0867,1.39395 -4.7812,1.65625 -3.3889,0.5246 -7.0334,0.23046 -9.4062,0.34375 -7.4077,0.32104 -14.726,-2.60314 -20.7813,-1.09375 -0.9228,0.69289 -1.3969,1.4625 -1.5625,2.3125 -0.1806,0.92739 -0.017,2.01851 0.4688,3.125 0.9708,2.21298 3.281,4.32492 5.3437,4.90625 a 1.4420115,1.4420115 0 0 1 0.062,0 c 11.2515,3.73156 24.1465,2.93253 35.9062,0.5 7.7821,-1.63499 12.8466,-8.87337 12.875,-16.71875 a 1.4420115,1.4420115 0 0 1 0,-0.0937 c 0.2634,-4.15469 0.2008,-8.71518 -0.9374,-12.5625 -1.1383,-3.84732 -3.227,-6.9152 -7.2813,-8.625 a 1.4420115,1.4420115 0 0 1 -0.1563,-0.0937 c -7.233,-4.1955 -16.6908,-2.33856 -25.375,-4.5 a 1.4420115,1.4420115 0 0 1 -0.375,-0.15625 c -7.593,-4.38022 -5.364,-17.27483 3.5,-18.15625 l 0,-0.0312 c 0.1153,-0.0364 0.2288,-0.0291 0.3438,-0.0625 4.5012,-1.3064 8.8395,-0.37995 12.875,0.59375 4.0804,0.98454 7.88,1.92841 11.4688,1.1875 5.4755,-2.31046 4.4951,-10.8333 -1.1876,-12.40625 a 1.4420115,1.4420115 0 0 1 -0.2812,-0.0937 c -6.5535,-3.28332 -14.4405,-2.57842 -22.1875,-2.625 -0.021,-1.3e-4 -0.042,1.4e-4 -0.062,0 z" />
360 <path
361 style="color:#000000;fill:url(#linearGradient6079);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
362 d="m 334.91414,52.45217 -0.5624,0.0312 c -10.692,0.64182 -26.7608,2.35866 -35.4063,16.28126 l -0.375,0.59375 -0.2813,0.625 c -2.6168,5.92672 -0.4865,12.63582 3.8126,16.24999 2.47,2.0766 6.1544,2.97511 9.8124,2.75 -12.1731,7.16212 -18.9579,21.29295 -17.0937,35.5 -0.9321,10.0329 5.7963,19.42583 15.4375,21.90625 l 0,0.0312 c 13.5839,4.67628 27.0449,3.11875 38.7812,0.90625 1.4491,0.98507 3.2876,2.06677 5.5626,3 2.2748,0.93323 5.2583,1.74964 8.75,1.34375 3.4915,-0.40589 7.1195,-2.30283 9.625,-4.875 l 0.375,-0.34375 0.3124,-0.40625 c 5.3642,-6.74967 5.6479,-14.75709 5.2188,-20.5625 -0.4291,-5.80541 -1.211,-10.50221 -1,-12.84375 l 0.062,-0.78125 -0.062,-0.75 c -0.9297,-14.08097 -0.732,-30.77734 -7.9062,-46.62499 -0.4593,-1.65783 -1.3753,-2.43205 -2.625,-3.4999 -10.8288,-9.19166 -23.8588,-8.03267 -31.8438,-8.50001 l -0.5938,-0.0312 z m 22.0626,47.46875 c 0.2983,4.01025 0.663,7.89337 0.9374,12.09375 -0.3619,6.15055 0.7536,11.18085 1.0313,14.9375 0.091,1.23358 -3e-4,1.89681 -0.031,2.71875 -0.7261,-0.49389 -0.8804,-0.56988 -1.7812,-1.1875 l -3.5,-2.40625 -4.1562,0.84375 c -11.8502,2.42474 -23.4896,3.77093 -32.7188,0.59375 l -0.75,-0.25 -0.8125,-0.15625 c -0.7563,-0.12889 -0.7437,-0.008 -0.5937,-0.75 l 0.375,-1.875 -0.3438,-1.875 c -1.3223,-7.37497 4.0726,-16.31882 11.1562,-18.03125 l 0.5626,-0.15625 0.5312,-0.1875 c 1.5591,-0.56829 3.7957,-0.58273 7.6875,-0.125 3.8918,0.45773 9.2275,1.48444 15.6563,0.0312 l 1.4687,-0.34375 1.3125,-0.75 c 1.5458,-0.8862 2.8481,-1.95265 3.9688,-3.125 z"
363 id="path6019" />
364 <path
365 style="fill:#484848;fill-opacity:1;stroke:none"
366 id="path6021"
367 d="m 442.8461,65.50261 c -9.9417,-0.25223 -20.0112,1.83054 -27.125,8.78125 a 1.4249747,1.4249747 0 0 1 -0.1876,0.125 c -0.4923,0.34955 -1.0141,0.64308 -1.6874,0.65625 -0.6734,0.0132 -1.3402,-0.39879 -1.6876,-0.8125 -0.6947,-0.82743 -0.7686,-1.5945 -0.9687,-2.34375 -0.2001,-0.74925 -0.4246,-1.47139 -0.6563,-1.84375 -0.2316,-0.37236 -0.2624,-0.39819 -0.6874,-0.40625 a 1.4249747,1.4249747 0 0 1 -0.6563,-0.1875 c -2.1511,-1.16691 -4.3134,-0.58174 -5.9063,0.90625 -1.5928,1.48799 -2.4145,3.81205 -1.5937,6.125 a 1.4249747,1.4249747 0 0 1 0.094,0.46875 c 0.099,20.08519 -1.9054,40.73856 3.75,59.71875 1.2377,1.74956 4.0539,2.66609 6.4063,2.28125 1.2075,-0.19755 2.2216,-0.71247 2.8437,-1.40625 0.6222,-0.69378 0.9615,-1.54589 0.75,-2.96875 a 1.4249747,1.4249747 0 0 1 0,-0.375 c 1.5091,-15.16756 -3.1254,-31.94343 3.25,-47.28125 a 1.4249747,1.4249747 0 0 1 0.031,-0.0625 c 2.3884,-4.77662 7.2847,-8.50018 12.5937,-10.03125 5.3091,-1.53107 11.2689,-0.75156 15.1563,3.84375 a 1.4249747,1.4249747 0 0 1 0.1563,0.1875 c 2.0694,3.60071 1.6918,8.0153 1.9687,11.75 0.1385,1.86735 0.4194,3.54061 1.0313,4.875 0.5916,1.2904 1.4751,2.25734 3.0312,3 1.4606,0.20734 2.5297,-0.051 3.4375,-0.6875 0.9587,-0.67214 1.771,-1.81376 2.375,-3.21875 1.2079,-2.80999 1.508,-6.6831 1.1563,-9.25 -1.6601,-6.82503 -2.269,-14.23556 -6.2813,-19.1875 -2.6943,-2.32961 -6.6692,-2.77567 -10.5313,-2.65625 a 1.4249747,1.4249747 0 0 1 -0.062,0 z" />
368 <path
369 style="color:#000000;fill:url(#linearGradient6081);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
370 d="m 548.52594,68.07721 -1.2187,0.25 c -8.6956,1.82574 -14.1425,9.53796 -15.9688,15.68749 -1.8263,6.14954 -1.7462,11.84707 -1.8125,15.71875 l 0,0.125 0,0.125 c 0.1092,10.79916 -0.5536,24.0134 4.9063,37 0.01,0.0225 0.022,0.0401 0.031,0.0625 2.7726,6.62078 9.3817,9.9621 15.5625,9.5625 5.6001,-0.36206 11.8353,-5.2195 13.5,-11.53125 5.3924,-17.21633 5.3013,-35.62075 1.75,-52.53125 l -0.1563,-0.6875 -0.2187,-0.62499 c -0.7814,-2.19128 -1.853,-4.62969 -3.9375,-7.1875 -2.0845,-2.55781 -5.8401,-5.71667 -11.1875,-5.9375 l -1.25,-0.0312 z"
371 id="path6023" />
372 <path
373 style="fill:#484848;fill-opacity:1;stroke:none"
374 id="path6025"
375 d="m 550.1139,78.59636 c -4.5226,0.97522 -6.7823,4.26272 -8,8.375 -1.2232,4.13111 -1.3087,9.03503 -1.375,12.90625 0.1123,11.09592 -0.2043,22.90976 4.0938,33.09375 0.9213,2.22841 3.1731,3.32073 5.25,3.1875 2.0769,-0.13323 3.906,-1.39 4.1562,-4.09375 a 0.46475483,0.46475483 0 0 1 0.031,-0.0937 c 4.7332,-15.11164 4.7084,-31.85462 1.4687,-47.28125 -0.4788,-1.32581 -1.2248,-2.85305 -2.1874,-4.03125 -0.9629,-1.17844 -2.1146,-1.98485 -3.4376,-2.0625 z" />
376 <path
377 style="color:#000000;fill:url(#linearGradient6083);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
378 d="m 242.87094,52.92092 -0.5938,0.0312 c -10.6919,0.64192 -26.7607,2.35873 -35.4062,16.28131 l -0.375,0.59375 -0.2813,0.65625 c -2.6168,5.92671 -0.4864,12.60456 3.8125,16.21874 2.4771,2.0825 6.1757,2.98309 9.8438,2.75 -12.176,7.14722 -18.9659,21.26849 -17.125,35.46875 -0.9665,10.0609 5.7999,19.48906 15.4687,21.96875 l -0.031,0.0312 c 13.5891,4.67806 27.073,3.12012 38.8125,0.90625 1.4445,0.97996 3.2715,2.07302 5.5313,3 2.2749,0.93323 5.2585,1.71839 8.75,1.3125 3.4915,-0.40589 7.1509,-2.27156 9.6562,-4.84375 l 0.3438,-0.375 0.3125,-0.40625 c 5.3641,-6.74969 5.6478,-14.72585 5.2187,-20.53125 -0.4291,-5.8054 -1.2109,-10.50221 -1,-12.84375 l 0.062,-0.78125 -0.062,-0.78125 c -0.9297,-14.081 -0.7006,-30.74608 -7.875,-46.59374 l -0.9375,-2.0625 -1.7187,-1.4375 c -10.8287,-9.19167 -23.8276,-8.06392 -31.8125,-8.53126 l -0.5938,-0.0312 z m 22.0312,47.5 c 0.2974,4.00059 0.6637,7.87292 0.9375,12.0625 -0.3619,6.15055 0.7536,11.2121 1.0313,14.96875 0.091,1.22812 0,1.86766 -0.031,2.6875 -0.7261,-0.49388 -0.8805,-0.56989 -1.7813,-1.1875 l -3.5,-2.40625 -4.1562,0.875 c -11.8502,2.42475 -23.4582,3.77094 -32.6875,0.59375 l -0.7813,-0.28125 -0.8125,-0.125 c -0.7563,-0.12888 -0.7437,-0.0396 -0.5938,-0.78125 l 0.375,-1.84375 -0.3437,-1.875 c -1.3223,-7.37494 4.0726,-16.35008 11.1562,-18.0625 l 0.5625,-0.125 0.5313,-0.1875 c 1.5591,-0.56828 3.7957,-0.58273 7.6875,-0.125 3.8918,0.45773 9.2275,1.45313 15.6562,0 l 1.4688,-0.3125 1.3125,-0.75 c 1.5458,-0.8862 2.8482,-1.95265 3.9687,-3.125 z"
379 id="path6027" />
380 <path
381 style="fill:#484848;fill-opacity:1;stroke:#484848;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
382 id="path6029"
383 d="m 243.6361,64.63031 c -9.6363,0.58398 -20.9336,2.59484 -26.0312,10.625 -0.4035,0.99026 -0.045,1.9107 0.6562,2.5 0.717,0.60234 1.4896,0.85243 2.5626,0 a 1.684398,1.684398 0 0 1 0.625,-0.3125 c 5.775,-1.5733 12.3167,-3.78461 18.9374,-4.625 6.6208,-0.84039 13.4444,-0.25925 19.4063,3.84375 a 1.684398,1.684398 0 0 1 0.375,0.375 c 2.0281,2.75755 2.9112,6.50666 2.5937,10.125 -0.3174,3.61834 -1.9072,7.25777 -5.2187,9.15625 a 1.684398,1.684398 0 0 1 -0.4687,0.1875 c -4.4561,1.00721 -8.7953,0.29068 -12.875,-0.1875 -4.0798,-0.47818 -7.8868,-0.73461 -11.5313,0.59375 a 1.684398,1.684398 0 0 1 -0.1563,0.0312 c -11.7884,2.8498 -19.5228,15.78804 -17.4062,27.59375 a 1.684398,1.684398 0 0 1 0,0.65625 c -1.0407,5.14641 2.2557,9.72666 7.3438,10.59375 a 1.684398,1.684398 0 0 1 0.2812,0.0625 c 11.7498,4.04484 24.8758,2.18109 37.0625,-0.3125 a 1.684398,1.684398 0 0 1 1.2813,0.28125 c 2.0816,1.42722 4.4575,3.29235 6.625,4.1875 1.0837,0.44757 2.0633,0.63094 2.9374,0.53125 0.8627,-0.0984 1.6764,-0.44585 2.5938,-1.375 0.01,-0.0118 0.022,-0.0195 0.031,-0.0312 2.6608,-3.43997 2.9705,-7.61463 2.625,-12.3125 -0.3431,-4.66636 -1.3766,-9.66321 -1,-14.46875 -0.9524,-14.4251 -1.1073,-29.45823 -6.7187,-42.15625 -6.4124,-5.22259 -15.7954,-5.06556 -24.4687,-5.5625 -0.021,-10e-4 -0.042,0.001 -0.063,0 z" />
384 <path
385 style="color:#000000;fill:url(#linearGradient6085);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
386 id="path6031"
387 d="m 252.9376,106.30395 c -3.4993,0.0307 -6.9607,-0.0581 -10.375,0.0312 -4.1004,0.36044 -9.0376,1.69024 -12.625,4.09375 -3.614,2.42133 -5.8704,5.68864 -5.2813,10.4375 0.4935,4.61527 3.5645,7.56447 7.6876,9.21875 4.123,1.65428 9.2633,1.8209 13.1562,0.65625 a 1.3611835,1.3611835 0 0 1 0.1562,-0.0312 c 2.8688,-0.49834 6.5939,-1.2529 9.2813,-2.71875 1.3437,-0.73292 2.3836,-1.63683 3.0313,-2.6875 0.6476,-1.05067 0.9604,-2.26047 0.6874,-3.96875 a 1.3611835,1.3611835 0 0 1 0,-0.28125 c 0.1564,-2.76724 0.3451,-6.68524 -0.375,-9.71875 -0.36,-1.51676 -0.9264,-2.77474 -1.75,-3.625 -0.8176,-0.8442 -1.8698,-1.36151 -3.5624,-1.40625 -0.012,-3.2e-4 -0.019,2.7e-4 -0.031,0 z" />
388 <path
389 style="color:#000000;fill:#305f00;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:10"
390 d="m 550.24144,11.97714 c -4.7431,8e-5 -9.3884,1.94508 -12.1562,5.65625 -2.3938,3.20927 -3.2655,7.28209 -3.5,11.84374 -5.2417,0.10768 -9.658,0.71067 -13.2813,2.53125 -3.7519,1.88519 -6.5576,5.75636 -6.9063,9.9375 l -0.062,0 c -0.013,0.1027 0.011,0.20947 0,0.3125 0,0.043 -0.03,0.0819 -0.031,0.125 l 0.031,0 c -0.383,3.94189 0.8037,8.08581 3.625,10.84375 1.7434,1.70445 3.9242,2.79035 6.3124,3.59375 l -0.875,2.4375 -0.062,0.125 -0.031,0.125 c -1.0239,3.32791 -0.9882,7.09444 0.8437,10.15625 1.8322,3.06181 4.9132,4.85334 8.3438,5.90625 l 0.7188,0.21875 0.75,0 2.2812,0 c 4.1038,5e-5 8.0184,-1.11288 11.1562,-3.5 1.388,-1.05587 2.5677,-2.38102 3.5938,-3.8125 2.738,2.5559 6.0541,4.80834 10,6.78125 l 0.5,0.25 0.5312,0.15625 c 3.235,0.79227 6.3972,0.95306 9.4063,-0.1875 2.9956,-1.13542 5.3523,-3.78973 6.4375,-6.71875 l 0.031,0 0,-0.0312 c 1.3188,-3.58119 1.0754,-7.65809 -0.4687,-11.1875 -0.3593,-0.82136 -0.9637,-1.56048 -1.4375,-2.34375 0.7988,-0.35352 1.5774,-0.75006 2.3125,-1.28125 3.1456,-2.2731 4.4669,-6.43958 4.1563,-10.25 l 0.031,0 c 0,-0.12851 -0.061,-0.24691 -0.062,-0.375 -0.017,-0.15367 0.023,-0.31671 0,-0.46875 l -0.062,0 c -0.2506,-3.85862 -2.6242,-7.47641 -5.875,-9.5625 -3.1968,-2.05143 -7.2278,-3.19745 -12.0625,-4.03124 -0.5947,-4.02941 -1.4462,-7.64148 -3.125,-10.53125 -2.2702,-3.9078 -6.5646,-6.71865 -11.0625,-6.71875 z m 18.3125,50.62499 c 0.2654,0.97712 0.2969,1.7705 -0.031,2.65625 l 0,0.0312 c -0.3181,0.86918 -0.3036,0.72198 -0.625,0.84375 -0.2585,0.098 -1.2073,0.14918 -2.5624,-0.0625 0.3313,-0.1475 0.7366,-0.14338 1.0312,-0.34375 l 0.4375,-0.28125 0.375,-0.40625 c 0.5814,-0.62017 0.9776,-1.55372 1.375,-2.4375 z"
391 id="path6033" />
392 <g
393 id="text6035"
394 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:165.01513672px;line-height:125%;font-family:'comic andy';-inkscape-font-specification:'comic andy';letter-spacing:0px;word-spacing:0px;fill:url(#linearGradient4437);fill-opacity:1;stroke:none">
395 <path
396 id="path98"
397 style="fill:url(#linearGradient6087);fill-opacity:1"
398 d="m 550.24549,16.984496 q 8.54083,0 9.83001,16.920498 l 2.33664,0 q 15.22844,2.33664 15.0673,9.668855 1.28918,8.621397 -11.03861,7.976806 9.42713,8.299101 6.7682,15.470169 -2.09492,5.72074 -9.99116,3.786969 -8.70197,-4.350985 -12.32779,-9.991151 l -1.5309,0 q -3.3841,9.991151 -13.13353,9.991151 l -2.25606,0 q -8.13796,-2.497788 -5.88189,-9.830003 l 2.82008,-7.815659 -0.80574,0 q -11.92492,-1.692049 -10.79688,-10.555167 0.32229,-8.137954 16.35648,-8.218527 4.43155,-0.483443 3.70639,-2.820083 0,-14.583858 10.87746,-14.583858 z m -4.5927,16.034186 -0.16115,4.512133 q -0.24172,3.384099 -2.17549,3.384099 l -12.73066,0.725164 q -2.98123,0.08057 -2.98123,2.417214 0,2.256067 3.22295,2.417214 11.19976,-0.564016 10.47459,1.530902 l -2.25606,4.834428 q -5.72074,8.621396 -2.82009,10.152299 3.86754,2.33664 10.95804,-12.08607 1.69205,-1.530902 2.82008,0 4.99558,5.317871 8.21853,8.70197 3.30353,3.3841 5.31787,2.014345 2.41721,-2.578361 -1.28918,-5.559592 -3.62582,-3.061804 -8.2991,-8.379675 -0.48344,-1.772623 0.24172,-1.772623 15.79246,1.047459 15.14787,-2.014345 0.48345,-3.3841 -13.69754,-3.3841 -2.17549,0.402869 -3.54525,-1.047459 l 0,-7.896232 q 0,-6.607052 -3.14238,-6.526478 -3.3841,-0.805738 -3.30352,7.976806 z" />
399 </g>
400 <path
401 d="m 335.7911,64.63031 c -9.6363,0.58398 -20.9336,2.59484 -26.0312,10.625 -0.4035,0.99026 -0.045,1.9107 0.6562,2.5 0.717,0.60234 1.4896,0.85243 2.5626,0 a 1.684398,1.684398 0 0 1 0.625,-0.3125 c 5.775,-1.5733 12.3167,-3.78461 18.9374,-4.625 6.6208,-0.84039 13.4444,-0.25925 19.4063,3.84375 a 1.684398,1.684398 0 0 1 0.375,0.375 c 2.0281,2.75755 2.9112,6.50666 2.5937,10.125 -0.3174,3.61834 -1.9072,7.25777 -5.2187,9.15625 a 1.684398,1.684398 0 0 1 -0.4687,0.1875 c -4.4561,1.00721 -8.7953,0.29068 -12.875,-0.1875 -4.0798,-0.47818 -7.8868,-0.73461 -11.5313,0.59375 a 1.684398,1.684398 0 0 1 -0.1563,0.0312 c -11.7884,2.8498 -19.5228,15.78804 -17.4062,27.59375 a 1.684398,1.684398 0 0 1 0,0.65625 c -1.0407,5.14641 2.2557,9.72666 7.3438,10.59375 a 1.684398,1.684398 0 0 1 0.2812,0.0625 c 11.7498,4.04484 24.8758,2.18109 37.0625,-0.3125 a 1.684398,1.684398 0 0 1 1.2813,0.28125 c 2.0816,1.42722 4.4575,3.29235 6.625,4.1875 1.0837,0.44757 2.0633,0.63094 2.9374,0.53125 0.8627,-0.0984 1.6764,-0.44585 2.5938,-1.375 0.01,-0.0118 0.022,-0.0195 0.031,-0.0312 2.6608,-3.43997 2.9705,-7.61463 2.625,-12.3125 -0.3431,-4.66636 -1.3766,-9.66321 -1,-14.46875 -0.9524,-14.4251 -1.1073,-29.45823 -6.7187,-42.15625 -6.4124,-5.22259 -15.7954,-5.06556 -24.4687,-5.5625 -0.021,-10e-4 -0.042,0.001 -0.063,0 z"
402 id="path6039"
403 style="fill:#484848;fill-opacity:1;stroke:#484848;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
404 <path
405 d="m 345.6192,106.30395 c -3.4993,0.0307 -6.9607,-0.0581 -10.375,0.0312 -4.1004,0.36044 -9.0376,1.69024 -12.625,4.09375 -3.614,2.42133 -5.8704,5.68864 -5.2813,10.4375 0.4935,4.61527 3.5645,7.56447 7.6876,9.21875 4.123,1.65428 9.2633,1.8209 13.1562,0.65625 a 1.3611835,1.3611835 0 0 1 0.1562,-0.0312 c 2.8688,-0.49834 6.5939,-1.2529 9.2813,-2.71875 1.3437,-0.73292 2.3836,-1.63683 3.0313,-2.6875 0.6476,-1.05067 0.9604,-2.26047 0.6874,-3.96875 a 1.3611835,1.3611835 0 0 1 0,-0.28125 c 0.1564,-2.76724 0.3451,-6.68524 -0.375,-9.71875 -0.36,-1.51676 -0.9264,-2.77474 -1.75,-3.625 -0.8176,-0.8442 -1.8698,-1.36151 -3.5624,-1.40625 -0.012,-3.2e-4 -0.019,2.7e-4 -0.031,0 z"
406 id="path6041"
407 style="color:#000000;fill:url(#linearGradient6089);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
408 </g>
409 <g
410 id="g5958">
411 <path
412 id="path4188"
413 d="m 549.36434,78.11349 c -9.4946,1.99352 -9.7027,14.03504 -9.8352,21.77668 0.1121,11.0831 -0.2095,22.9628 4.1417,33.27264 2.0054,4.85047 9.7812,4.74809 10.3195,-1.06753 4.7624,-15.20498 4.7481,-32.01281 1.4946,-47.50541 -0.983,-2.75668 -3.069,-6.35036 -6.1206,-6.47638 z"
414 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
415 <path
416 id="path4190"
417 d="m 499.48944,47.6175 c -6.4927,-0.34021 -9.3439,6.60543 -8.1121,12.16941 -0.5858,24.07597 -0.3292,48.31194 0.034,72.30837 1.7508,6.96484 14.895,8.48808 15.0166,-0.0712 1.2169,-13.27189 -0.274,-26.75029 0.6639,-40.10232 0.7817,-11.41478 -0.5568,-23.24296 -0.6994,-34.37618 1.5849,-5.10643 -0.4706,-11.12871 -6.9034,-9.92811 z"
418 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
419 <path
420 id="path4192"
421 d="m 132.42293,35.23407 c -7.6945,2.17125 -5.9206,12.79289 -6.2273,19.00216 1.6106,23.24538 0.8475,46.57408 2.1706,69.81693 0.068,7.09423 3.2021,16.90233 11.8853,16.22657 7.5709,-1.76417 5.7778,-11.8325 5.6557,-17.71589 -0.047,-7.84014 -4.5559,-19.23884 3.9165,-24.30949 7.6405,-5.37547 19.848,0.64078 18.6463,10.39069 -0.3251,8.83089 -2.0837,22.16882 7.8287,26.47493 6.4024,2.92649 10.6176,-5.21693 9.3943,-10.71096 -0.3749,-13.55442 1.2727,-30.22607 -10.711,-39.6768 -7.9735,-4.05845 -18.9828,-5.54515 -26.8307,-0.21351 -1.0372,2.42576 -6.9951,6.95054 -6.4053,1.24546 -1.6949,-15.3749 2.056,-31.45755 -2.3485,-46.40228 -1.2024,-2.63946 -4.0324,-4.45898 -6.9746,-4.12781 z"
422 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
423 <path
424 id="path4194"
425 d="m 442.14024,64.05759 c -10.165,-0.2579 -20.6562,1.86137 -28.1474,9.18081 -2.8958,2.05591 -1.2663,-4.94966 -4.8395,-5.01742 -5.4074,-2.93338 -11.5829,2.98762 -9.5367,8.75381 0.099,20.06919 -1.977,40.97889 3.8787,60.387 3.1796,4.95849 13.7562,4.09337 12.7037,-2.9891 1.546,-15.53942 -2.968,-32.10549 3.167,-46.86488 4.3319,-8.66318 18.41,-14.13659 25.3718,-5.90704 3.521,6.12624 -0.9752,16.78774 6.8323,20.31879 7.6504,1.3481 9.6041,-9.08157 8.825,-14.7676 -1.6539,-6.72434 -2.1565,-14.5353 -6.6544,-19.99852 -3.1376,-2.78799 -7.564,-3.22067 -11.6005,-3.09585 z"
426 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
427 <path
428 id="path4196"
429 d="m 442.38294,54.04595 c -0.1827,-0.005 -0.3789,0.0345 -0.5625,0.0312 -8.6942,-0.15632 -18.301,1.16995 -26.7813,5.96876 -0.368,-0.21564 -0.7676,-0.37654 -1.1562,-0.5625 l 0.031,-0.0625 c -0.2019,-0.10958 -0.4204,-0.1194 -0.625,-0.21875 -0.5569,-0.23563 -1.1103,-0.37966 -1.6874,-0.53125 -6.0741,-2.10894 -12.7994,-0.4336 -16.8438,3.34375 -3.8577,3.60298 -6.0063,9.29062 -5.1562,15.125 0.085,19.31578 -2.292,41.23535 4.3124,63.12499 l 0.4063,1.3125 0.75,1.1875 c 4.4521,6.94297 11.5862,8.53059 18,7.46875 3.2069,-0.53092 6.701,-1.89897 9.5,-5.03125 2.2725,-2.54317 3.5121,-6.27514 3.5937,-9.84375 0,-0.0435 0,-0.0816 0,-0.125 1.7478,-17.81793 -1.8544,-32.72457 2.2813,-43.375 0.6976,-1.23208 3.1856,-3.39065 5.4063,-4.03125 1.1119,-0.32077 1.7363,-0.44325 2.1874,-0.40625 0.051,0.8996 0.2789,2.71568 0.5313,6.0625 0.1821,2.41445 0.4732,5.42185 2.0313,8.8125 1.558,3.39065 4.8419,6.94014 8.8437,8.75 l 1.1563,0.5 1.2187,0.21875 c 4.1545,0.73208 8.9361,-0.28467 12.2187,-2.59375 3.2827,-2.30908 5.1358,-5.31163 6.3126,-8.0625 2.3534,-5.50175 2.5912,-10.54096 1.9374,-15.3125 l -0.062,-0.53125 -0.125,-0.5 c -1.3372,-5.43656 -1.418,-15.17693 -8.6563,-23.96874 l -0.4687,-0.59375 -0.5938,-0.53125 c -6.0316,-5.35952 -13.0425,-5.71213 -18,-5.59376 l 0,-0.0312 z m -20.9688,14.62501 c 0.3103,0.61975 0.1924,0.76755 0.063,0.28125 -0.016,-0.0599 -0.046,-0.21107 -0.063,-0.28125 z m -11.8437,14.15624 c 0.271,0.10418 0.5347,0.22752 0.8125,0.3125 l -0.125,0.21875 -0.125,0.3125 c -0.2313,0.55649 -0.3535,1.10135 -0.5625,1.65625 0.01,-0.84699 -0.01,-1.64903 0,-2.5 z"
430 style="color:#000000;fill:url(#linearGradient4453);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
431 <path
432 id="path4198"
433 d="m 334.93614,43.42895 -1.125,0.0625 c -11.4541,0.68757 -31.1299,2.13948 -42.5313,20.5 l -0.6875,1.15625 -0.5312,1.21875 c -4.0155,9.09454 -1.1737,19.34928 5,25.5 -7.1006,9.03999 -10.5361,20.69833 -9.25,32.65625 -0.7932,13.71238 8.5163,26.58972 21.5624,30.34375 l -0.031,0.0625 c 14.5936,5.02387 28.3345,3.89176 40,1.875 1.1383,0.61027 2.377,1.24208 3.8438,1.84375 3.1932,1.30991 7.6804,2.60895 13.1874,1.96875 5.5071,-0.6402 11.3463,-3.71585 15.0626,-7.53125 l 0.6562,-0.6875 0.5938,-0.75 c 7.375,-9.27994 7.6766,-20.19393 7.1874,-26.8125 -0.4891,-6.61857 -1.0653,-10.99648 -1.0312,-11.375 l 0.125,-1.46875 -0.094,-1.5 c -0.9045,-13.69999 -0.4438,-31.50909 -8.6874,-49.71875 -0.8869,-3.14352 -2.6183,-4.60975 -5,-6.625 -14.193,-12.04738 -29.8012,-10.22761 -37.125,-10.65625 z m -5,69.25 c -0.6975,0.25422 -0.096,-0.059 3.5937,0.375 3.1757,0.3735 8.4922,1.29071 15.3437,0.34375 -0.042,1.60674 -0.047,3.10046 0.031,4.46875 l -1.2187,0.25 c -9.4296,1.92946 -17.7526,2.70557 -24.0626,1.71875 0.3089,-2.61777 2.5558,-6.11412 4.2813,-6.53125 l 1.0313,-0.25 1,-0.375 z"
434 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:38" />
435 <path
436 style="color:#000000;fill:#484848;fill-opacity:1;fill-rule:nonzero;stroke:#484848;stroke-width:38;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
437 d="m 242.86794,62.94328 c -9.8451,0.59098 -21.9234,2.57343 -27.5069,11.56498 -1.5225,3.44827 2.5155,7.16458 5.8003,4.55483 11.6876,-3.18405 25.8772,-8.64334 36.9368,-1.03196 3.4255,4.6575 3.2712,13.73214 -2.1351,16.8315 -8.1137,1.83399 -16.456,-2.50178 -24.589,0.4626 -12.7407,3.08001 -20.924,16.83116 -18.6463,29.53519 -1.221,6.03853 2.7535,11.58045 8.7182,12.59694 12.2603,4.22059 25.7141,2.25842 37.9688,-0.24909 3.9671,2.72001 9.7011,7.85911 14.3406,3.09585 6.2596,-7.87653 1.273,-19.02318 2.088,-28.06851 -0.9577,-14.50429 -1.0481,-29.91302 -7.0343,-43.1362 -7.0905,-6.01862 -17.2216,-5.6458 -25.9411,-6.15613 z"
438 id="path4200" />
439 <path
440 id="path4202"
441 d="m 132.71733,24.19589 c -0.5004,0.0152 -1.0205,0.0363 -1.5312,0.0937 l -0.9063,0.0937 -0.8437,0.25 c -4.2861,1.20943 -8.1936,4.24904 -10.375,7.56249 -2.1816,3.31346 -2.9841,6.56659 -3.4063,9.375 -0.8444,5.61682 -0.3823,10.37282 -0.4687,12.125 l -0.031,0.65625 0.062,0.625 c 1.548,22.34205 0.8033,45.46456 2.125,69.1875 5e-4,0.0505 0.031,0.10568 0.031,0.15625 0.01,0.1151 -0.01,0.22862 0,0.34375 l 0.031,0 c 0.099,4.98929 0.9665,10.43113 4.125,15.90625 3.2605,5.65198 11.0145,11.32149 19.5625,10.65625 l 0.8438,-0.0625 0.8124,-0.1875 c 4.2384,-0.98762 8.3269,-3.79564 10.625,-7.09375 2.1728,-3.63384 4.3342,-6.89183 5.1872,-10.22818 3.8402,7.13335 5.9507,8.04619 13.1566,11.44693 l 0,0.0312 c 0.059,0.0269 0.1281,0.0362 0.1875,0.0625 3.7423,1.65403 8.4312,1.97661 12.2813,0.65625 3.91101,-1.34132 6.71761,-3.90092 8.59371,-6.5 3.336,-4.62154 4.6441,-9.64143 3.9063,-15.25 -0.1718,-6.20746 0.2238,-14.23226 -1.1563,-22.8125 -1.3801,-8.58024 -5.0962,-18.36284 -13.75001,-25.1875 l -0.8437,-0.6875 -0.9688,-0.5 c -7.7653,-3.95251 -17.7087,-6.355 -27.4062,-4.09375 0.4086,-10.28331 1.089,-21.96033 -2.625,-34.5625 l -0.2188,-0.75 -0.3125,-0.71875 c -2.9167,-6.40275 -9.181,-10.82231 -16.6875,-10.59374 z m 6.0625,53.99999 c 0,0.0101 0.05,0.0315 0.062,0.0625 l -0.6245,1.46875 c 0.3311,-0.86163 0.5542,-1.56647 0.5625,-1.53125 z m 36.0625,48.28125 c 0.012,-0.004 0.019,0.005 0.031,0 l 0.063,0.3125 c -0.043,-0.19086 -0.061,-0.25465 -0.094,-0.3125 z"
442 style="color:#000000;fill:url(#linearGradient4451);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
443 <path
444 d="m 133.3461,36.09636 c -1.692,0.49428 -2.8155,1.39846 -3.625,2.625 -0.8214,1.24442 -1.3243,2.85069 -1.5938,4.625 -0.5342,3.51732 -0.1953,7.61208 -0.3438,10.8125 0,0.0285 0,0.0654 0,0.0937 1.6063,23.27388 0.8692,46.5905 2.1876,69.75 a 0.88388823,0.88388823 0 0 1 0,0.0625 c 0.033,3.4213 0.83,7.53419 2.5937,10.59375 1.7438,3.02495 4.2922,5.00636 8.2187,4.75 0.011,-7.3e-4 0.02,7.7e-4 0.031,0 1.6857,-0.39978 2.7542,-1.19719 3.5313,-2.3125 0.7819,-1.12237 1.2391,-2.59827 1.4687,-4.25 0.4593,-3.30346 2e-4,-7.22907 -0.062,-10.25 a 0.88388823,0.88388823 0 0 1 0,-0.0312 c -0.023,-3.75401 -1.179,-8.58343 -1.25,-13.1875 -0.071,-4.59014 1.0512,-9.12033 5.5625,-11.84375 0.012,-0.008 0.019,-0.023 0.031,-0.0312 8.2411,-5.75335 21.2001,0.72746 19.9687,11.1875 0,0.011 0,0.0202 0,0.0312 -4e-4,0.01 4e-4,0.0216 0,0.0312 -0.1662,4.44678 -0.6416,9.92071 0.094,14.71875 0.7386,4.81878 2.5857,8.83105 7.2188,10.84375 a 0.88388823,0.88388823 0 0 1 0.031,0 c 1.4264,0.65196 2.625,0.67804 3.6876,0.3125 1.0625,-0.36554 2.0152,-1.15367 2.7812,-2.21875 1.532,-2.13016 2.2012,-5.36524 1.6562,-7.8125 a 0.88388823,0.88388823 0 0 1 0,-0.15625 c -0.1887,-6.82351 0.1073,-14.35845 -1,-21.28125 -1.1026,-6.89383 -3.5864,-13.13587 -9.3124,-17.6875 -7.7294,-3.90433 -18.3437,-5.25802 -25.7813,-0.25 -0.7734,1.48479 -2.3237,3.00623 -4,3.78125 -0.9043,0.41808 -1.982,0.65336 -2.875,0.0312 -0.8519,-0.59346 -1.0866,-1.72753 -0.9687,-3.1875 0.01,-0.0705 -0.01,-0.11538 0,-0.1875 -1.6634,-15.48034 1.9617,-31.38045 -2.2813,-45.9375 -1.0363,-2.2749 -3.4784,-3.85945 -5.9687,-3.625 z"
445 id="path4440"
446 style="fill:#484848;fill-opacity:1;stroke:none" />
447 <path
448 id="path4206"
449 d="m 500.00794,37.6397 c -0.47,-0.0246 -0.9099,0.13839 -1.375,0.15625 -0.3182,0.036 -0.6564,-0.0583 -0.9688,0 l 0,0.0937 c -5.9486,0.59666 -11.3199,4.27914 -13.8124,8.625 -2.5191,4.39212 -3.1643,9.07388 -2.4688,13.75001 -0.5691,24.07161 -0.3288,48.17845 0.031,71.96874 l 0.031,1.1875 0.2813,1.125 c 2.2758,9.05358 10.1204,12.94327 17.2812,13.3125 3.5804,0.18461 7.6057,-0.50128 11.25,-3.21875 3.4431,-2.56742 5.753,-7.21537 6.0625,-11.6875 l 0.062,0 c 0.024,-0.26477 0.01,-0.51719 0.031,-0.78125 1.2169,-14.32127 -0.1813,-27.63851 0.6563,-39.5625 0.8412,-12.28307 -0.4559,-23.97948 -0.6563,-34.18749 0.9168,-4.19732 0.7514,-8.64033 -1.75,-13.09376 -2.5398,-4.52202 -8.6787,-7.57722 -14.4374,-7.5625 -0.073,1.9e-4 -0.1457,-0.001 -0.2188,0 l 0,-0.125 z m -0.4375,10.46875 1.5625,8.375 c -0.089,0.0884 -0.5399,0.26586 -0.9688,0.50001 -0.4433,-0.17558 -0.588,-0.31717 -1.125,-0.59376 l 0.5313,-8.28125 z m 1.625,8.6875 0.125,0.65626 c 0,-5.2e-4 -0.146,-0.0578 -0.1563,-0.0625 0.013,-0.26164 0.01,-0.41632 0.031,-0.59376 z"
450 style="color:#000000;fill:url(#linearGradient4449);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
451 <path
452 id="path4208"
453 d="m 499.48944,47.6175 c -6.4927,-0.34021 -9.3439,6.60543 -8.1121,12.16941 -0.5858,24.07597 -0.3292,48.31194 0.034,72.30837 1.7508,6.96484 14.895,8.48808 15.0166,-0.0712 1.2169,-13.27189 -0.274,-26.75029 0.6639,-40.10232 0.7817,-11.41478 -0.5568,-23.24296 -0.6994,-34.37618 1.5849,-5.10643 -0.4706,-11.12871 -6.9034,-9.92811 z"
454 style="fill:#484848;fill-opacity:1;stroke:none" />
455 <path
456 id="path4210"
457 d="m 544.51954,53.6313 c -7.5784,-0.46784 -10.6755,10.08558 -4.626,14.19825 6.4831,5.13984 16.9776,-2.57743 12.9884,-10.24836 -1.4384,-3.20261 -5.1136,-4.25984 -8.3624,-3.94989 z"
458 style="fill:#000000;fill-opacity:1;stroke:none" />
459 <path
460 id="path4212"
461 d="m 66.312222,57.93009 c -17.370703,0.62829 -30.0641,20.09681 -26.023403,36.39781 2.1928,10.05075 13.8541,12.09708 22.635103,11.4922 7.1377,-0.5151 17.6041,2.45346 16.7319,11.49222 -1.8676,6.29718 -10.9897,4.97438 -16.0667,5.21679 -7.019003,0.3042 -14.551803,-2.83467 -21.309203,-1.0251 -5.546297,3.71601 -0.7698,11.63178 4.4362,13.09902 11.6204,3.85396 24.776703,2.98561 36.677203,0.52396 8.494404,-1.78465 13.976704,-9.66183 14.007304,-18.12905 0.5362,-8.45978 -0.1252,-18.85777 -9.082,-22.63511 -7.833304,-4.5437 -17.524404,-2.59996 -25.744004,-4.64578 -6.504303,-3.75215 -4.590203,-15.08325 3.2137,-15.54417 8.376,-2.645 16.5844,3.54335 24.730904,1.74653 6.8027,-2.75685 5.6777,-13.26551 -1.2924,-15.19486 C 82.177322,57.19274 73.972122,57.9802 66.312222,57.93009 Z"
462 style="fill:#484848;fill-opacity:1;stroke:#484848;stroke-width:38;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
463 <path
464 id="path4214"
465 d="m 66.146122,46.92095 -0.2187,0.0312 c -25.268203,0.91394 -41.9786,26.29641 -36.375,49.71875 0,0.01 0,0.0214 0,0.0312 0.023,0.0937 0.039,0.18758 0.062,0.28125 l 0.062,0 c 1.4158,6.03031 5.2241,10.72981 9.5937,13.9375 l -1.5937,0.4375 -1.5313,1 c -3.4934,2.34058 -6.2461,6.40677 -7.0312,10.4375 -0.7852,4.03073 0.016,7.64447 1.2812,10.53125 2.4625,5.61698 6.4364,9.72109 12.843797,11.6875 l 0,0.0312 c 0.1235,0.0409 0.2514,0.0537 0.375,0.0937 0.044,0.0142 0.081,0.0484 0.125,0.0625 14.2876,4.59699 29.052403,3.33987 41.875007,0.6875 l 0.031,0 c 13.703,-2.87897 22.354804,-15.23519 22.687504,-28.1875 l 0.031,0 c 0.01,-0.1043 -0.01,-0.23849 0,-0.34375 0,-0.10511 0.031,-0.20733 0.031,-0.3125 l -0.031,0 c 0.275,-4.68022 0.3633,-10.21921 -1.4063,-16.21875 -1.6128,-5.46789 -5.6186,-11.40935 -11.718704,-15.03125 C 110.28983,79.05558 108.57813,56.15757 93.550926,50.6395 83.076822,45.62854 73.121622,46.96476 66.394622,46.92075 l -0.25,0 z M 49.927419,124.0772 c 0.4736,0.11312 0.7429,0.17483 0.6875,0.1875 -0.1379,-0.0437 -0.3009,-0.0484 -0.4375,-0.0937 l -0.25,-0.0937 z"
466 style="color:#000000;fill:url(#linearGradient4447);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
467 <path
468 d="M 67.047,59.37761 C 50.7565,60.01346 38.6203,78.63489 42.422,93.97136 a 1.4420115,1.4420115 0 0 1 0,0.0312 c 0.9874,4.52574 3.9833,7.14275 7.9688,8.71875 3.9854,1.576 8.921,1.948 13.1562,1.65625 3.8182,-0.27555 8.4163,0.35581 12.1562,2.34375 3.74,1.98794 6.6157,5.6345 6.125,10.71875 a 1.4420115,1.4420115 0 0 1 -0.062,0.28125 c -0.5618,1.89409 -1.746,3.32797 -3.1876,4.25 -1.4415,0.92203 -3.0867,1.39395 -4.7812,1.65625 -3.3889,0.5246 -7.0334,0.23046 -9.4062,0.34375 -7.4077,0.32104 -14.726,-2.60314 -20.7813,-1.09375 -0.9228,0.69289 -1.3969,1.4625 -1.5625,2.3125 -0.1806,0.92739 -0.017,2.01851 0.4688,3.125 0.9708,2.21298 3.281,4.32492 5.3437,4.90625 a 1.4420115,1.4420115 0 0 1 0.062,0 c 11.2515,3.73156 24.1465,2.93253 35.9062,0.5 7.7821,-1.63499 12.8466,-8.87337 12.875,-16.71875 a 1.4420115,1.4420115 0 0 1 0,-0.0937 c 0.2634,-4.15469 0.2008,-8.71518 -0.9374,-12.5625 -1.1383,-3.84732 -3.227,-6.9152 -7.2813,-8.625 a 1.4420115,1.4420115 0 0 1 -0.1563,-0.0937 c -7.233,-4.1955 -16.6908,-2.33856 -25.375,-4.5 a 1.4420115,1.4420115 0 0 1 -0.375,-0.15625 c -7.593,-4.38022 -5.364,-17.27483 3.5,-18.15625 l 0,-0.0312 c 0.1153,-0.0364 0.2288,-0.0291 0.3438,-0.0625 4.5012,-1.3064 8.8395,-0.37995 12.875,0.59375 4.0804,0.98454 7.88,1.92841 11.4688,1.1875 5.4755,-2.31046 4.4951,-10.8333 -1.1876,-12.40625 a 1.4420115,1.4420115 0 0 1 -0.2812,-0.0937 c -6.5535,-3.28332 -14.4405,-2.57842 -22.1875,-2.625 -0.021,-1.3e-4 -0.042,1.4e-4 -0.062,0 z"
469 id="path4442"
470 style="fill:#484848;fill-opacity:1;stroke:none" />
471 <path
472 id="path4218"
473 d="m 334.91414,52.45217 -0.5624,0.0312 c -10.692,0.64182 -26.7608,2.35866 -35.4063,16.28126 l -0.375,0.59375 -0.2813,0.625 c -2.6168,5.92672 -0.4865,12.63582 3.8126,16.24999 2.47,2.0766 6.1544,2.97511 9.8124,2.75 -12.1731,7.16212 -18.9579,21.29295 -17.0937,35.5 -0.9321,10.0329 5.7963,19.42583 15.4375,21.90625 l 0,0.0312 c 13.5839,4.67628 27.0449,3.11875 38.7812,0.90625 1.4491,0.98507 3.2876,2.06677 5.5626,3 2.2748,0.93323 5.2583,1.74964 8.75,1.34375 3.4915,-0.40589 7.1195,-2.30283 9.625,-4.875 l 0.375,-0.34375 0.3124,-0.40625 c 5.3642,-6.74967 5.6479,-14.75709 5.2188,-20.5625 -0.4291,-5.80541 -1.211,-10.50221 -1,-12.84375 l 0.062,-0.78125 -0.062,-0.75 c -0.9297,-14.08097 -0.732,-30.77734 -7.9062,-46.62499 -0.4593,-1.65783 -1.3753,-2.43205 -2.625,-3.4999 -10.8288,-9.19166 -23.8588,-8.03267 -31.8438,-8.50001 l -0.5938,-0.0312 z m 22.0626,47.46875 c 0.2983,4.01025 0.663,7.89337 0.9374,12.09375 -0.3619,6.15055 0.7536,11.18085 1.0313,14.9375 0.091,1.23358 -3e-4,1.89681 -0.031,2.71875 -0.7261,-0.49389 -0.8804,-0.56988 -1.7812,-1.1875 l -3.5,-2.40625 -4.1562,0.84375 c -11.8502,2.42474 -23.4896,3.77093 -32.7188,0.59375 l -0.75,-0.25 -0.8125,-0.15625 c -0.7563,-0.12889 -0.7437,-0.008 -0.5937,-0.75 l 0.375,-1.875 -0.3438,-1.875 c -1.3223,-7.37497 4.0726,-16.31882 11.1562,-18.03125 l 0.5626,-0.15625 0.5312,-0.1875 c 1.5591,-0.56829 3.7957,-0.58273 7.6875,-0.125 3.8918,0.45773 9.2275,1.48444 15.6563,0.0312 l 1.4687,-0.34375 1.3125,-0.75 c 1.5458,-0.8862 2.8481,-1.95265 3.9688,-3.125 z"
474 style="color:#000000;fill:url(#linearGradient4445);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
475 <path
476 d="m 442.8461,65.50261 c -9.9417,-0.25223 -20.0112,1.83054 -27.125,8.78125 a 1.4249747,1.4249747 0 0 1 -0.1876,0.125 c -0.4923,0.34955 -1.0141,0.64308 -1.6874,0.65625 -0.6734,0.0132 -1.3402,-0.39879 -1.6876,-0.8125 -0.6947,-0.82743 -0.7686,-1.5945 -0.9687,-2.34375 -0.2001,-0.74925 -0.4246,-1.47139 -0.6563,-1.84375 -0.2316,-0.37236 -0.2624,-0.39819 -0.6874,-0.40625 a 1.4249747,1.4249747 0 0 1 -0.6563,-0.1875 c -2.1511,-1.16691 -4.3134,-0.58174 -5.9063,0.90625 -1.5928,1.48799 -2.4145,3.81205 -1.5937,6.125 a 1.4249747,1.4249747 0 0 1 0.094,0.46875 c 0.099,20.08519 -1.9054,40.73856 3.75,59.71875 1.2377,1.74956 4.0539,2.66609 6.4063,2.28125 1.2075,-0.19755 2.2216,-0.71247 2.8437,-1.40625 0.6222,-0.69378 0.9615,-1.54589 0.75,-2.96875 a 1.4249747,1.4249747 0 0 1 0,-0.375 c 1.5091,-15.16756 -3.1254,-31.94343 3.25,-47.28125 a 1.4249747,1.4249747 0 0 1 0.031,-0.0625 c 2.3884,-4.77662 7.2847,-8.50018 12.5937,-10.03125 5.3091,-1.53107 11.2689,-0.75156 15.1563,3.84375 a 1.4249747,1.4249747 0 0 1 0.1563,0.1875 c 2.0694,3.60071 1.6918,8.0153 1.9687,11.75 0.1385,1.86735 0.4194,3.54061 1.0313,4.875 0.5916,1.2904 1.4751,2.25734 3.0312,3 1.4606,0.20734 2.5297,-0.051 3.4375,-0.6875 0.9587,-0.67214 1.771,-1.81376 2.375,-3.21875 1.2079,-2.80999 1.508,-6.6831 1.1563,-9.25 -1.6601,-6.82503 -2.269,-14.23556 -6.2813,-19.1875 -2.6943,-2.32961 -6.6692,-2.77567 -10.5313,-2.65625 a 1.4249747,1.4249747 0 0 1 -0.062,0 z"
477 id="path4436"
478 style="fill:#484848;fill-opacity:1;stroke:none" />
479 <path
480 id="path4224"
481 d="m 548.52594,68.07721 -1.2187,0.25 c -8.6956,1.82574 -14.1425,9.53796 -15.9688,15.68749 -1.8263,6.14954 -1.7462,11.84707 -1.8125,15.71875 l 0,0.125 0,0.125 c 0.1092,10.79916 -0.5536,24.0134 4.9063,37 0.01,0.0225 0.022,0.0401 0.031,0.0625 2.7726,6.62078 9.3817,9.9621 15.5625,9.5625 5.6001,-0.36206 11.8353,-5.2195 13.5,-11.53125 5.3924,-17.21633 5.3013,-35.62075 1.75,-52.53125 l -0.1563,-0.6875 -0.2187,-0.62499 c -0.7814,-2.19128 -1.853,-4.62969 -3.9375,-7.1875 -2.0845,-2.55781 -5.8401,-5.71667 -11.1875,-5.9375 l -1.25,-0.0312 z"
482 style="color:#000000;fill:url(#linearGradient4443);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
483 <path
484 d="m 550.1139,78.59636 c -4.5226,0.97522 -6.7823,4.26272 -8,8.375 -1.2232,4.13111 -1.3087,9.03503 -1.375,12.90625 0.1123,11.09592 -0.2043,22.90976 4.0938,33.09375 0.9213,2.22841 3.1731,3.32073 5.25,3.1875 2.0769,-0.13323 3.906,-1.39 4.1562,-4.09375 a 0.46475483,0.46475483 0 0 1 0.031,-0.0937 c 4.7332,-15.11164 4.7084,-31.85462 1.4687,-47.28125 -0.4788,-1.32581 -1.2248,-2.85305 -2.1874,-4.03125 -0.9629,-1.17844 -2.1146,-1.98485 -3.4376,-2.0625 z"
485 id="path4438"
486 style="fill:#484848;fill-opacity:1;stroke:none" />
487 <path
488 id="path4229"
489 d="m 242.87094,52.92092 -0.5938,0.0312 c -10.6919,0.64192 -26.7607,2.35873 -35.4062,16.28131 l -0.375,0.59375 -0.2813,0.65625 c -2.6168,5.92671 -0.4864,12.60456 3.8125,16.21874 2.4771,2.0825 6.1757,2.98309 9.8438,2.75 -12.176,7.14722 -18.9659,21.26849 -17.125,35.46875 -0.9665,10.0609 5.7999,19.48906 15.4687,21.96875 l -0.031,0.0312 c 13.5891,4.67806 27.073,3.12012 38.8125,0.90625 1.4445,0.97996 3.2715,2.07302 5.5313,3 2.2749,0.93323 5.2585,1.71839 8.75,1.3125 3.4915,-0.40589 7.1509,-2.27156 9.6562,-4.84375 l 0.3438,-0.375 0.3125,-0.40625 c 5.3641,-6.74969 5.6478,-14.72585 5.2187,-20.53125 -0.4291,-5.8054 -1.2109,-10.50221 -1,-12.84375 l 0.062,-0.78125 -0.062,-0.78125 c -0.9297,-14.081 -0.7006,-30.74608 -7.875,-46.59374 l -0.9375,-2.0625 -1.7187,-1.4375 c -10.8287,-9.19167 -23.8276,-8.06392 -31.8125,-8.53126 l -0.5938,-0.0312 z m 22.0312,47.5 c 0.2974,4.00059 0.6637,7.87292 0.9375,12.0625 -0.3619,6.15055 0.7536,11.2121 1.0313,14.96875 0.091,1.22812 0,1.86766 -0.031,2.6875 -0.7261,-0.49388 -0.8805,-0.56989 -1.7813,-1.1875 l -3.5,-2.40625 -4.1562,0.875 c -11.8502,2.42475 -23.4582,3.77094 -32.6875,0.59375 l -0.7813,-0.28125 -0.8125,-0.125 c -0.7563,-0.12888 -0.7437,-0.0396 -0.5938,-0.78125 l 0.375,-1.84375 -0.3437,-1.875 c -1.3223,-7.37494 4.0726,-16.35008 11.1562,-18.0625 l 0.5625,-0.125 0.5313,-0.1875 c 1.5591,-0.56828 3.7957,-0.58273 7.6875,-0.125 3.8918,0.45773 9.2275,1.45313 15.6562,0 l 1.4688,-0.3125 1.3125,-0.75 c 1.5458,-0.8862 2.8482,-1.95265 3.9687,-3.125 z"
490 style="color:#000000;fill:url(#linearGradient4441);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
491 <path
492 d="m 243.6361,64.63031 c -9.6363,0.58398 -20.9336,2.59484 -26.0312,10.625 -0.4035,0.99026 -0.045,1.9107 0.6562,2.5 0.717,0.60234 1.4896,0.85243 2.5626,0 a 1.684398,1.684398 0 0 1 0.625,-0.3125 c 5.775,-1.5733 12.3167,-3.78461 18.9374,-4.625 6.6208,-0.84039 13.4444,-0.25925 19.4063,3.84375 a 1.684398,1.684398 0 0 1 0.375,0.375 c 2.0281,2.75755 2.9112,6.50666 2.5937,10.125 -0.3174,3.61834 -1.9072,7.25777 -5.2187,9.15625 a 1.684398,1.684398 0 0 1 -0.4687,0.1875 c -4.4561,1.00721 -8.7953,0.29068 -12.875,-0.1875 -4.0798,-0.47818 -7.8868,-0.73461 -11.5313,0.59375 a 1.684398,1.684398 0 0 1 -0.1563,0.0312 c -11.7884,2.8498 -19.5228,15.78804 -17.4062,27.59375 a 1.684398,1.684398 0 0 1 0,0.65625 c -1.0407,5.14641 2.2557,9.72666 7.3438,10.59375 a 1.684398,1.684398 0 0 1 0.2812,0.0625 c 11.7498,4.04484 24.8758,2.18109 37.0625,-0.3125 a 1.684398,1.684398 0 0 1 1.2813,0.28125 c 2.0816,1.42722 4.4575,3.29235 6.625,4.1875 1.0837,0.44757 2.0633,0.63094 2.9374,0.53125 0.8627,-0.0984 1.6764,-0.44585 2.5938,-1.375 0.01,-0.0118 0.022,-0.0195 0.031,-0.0312 2.6608,-3.43997 2.9705,-7.61463 2.625,-12.3125 -0.3431,-4.66636 -1.3766,-9.66321 -1,-14.46875 -0.9524,-14.4251 -1.1073,-29.45823 -6.7187,-42.15625 -6.4124,-5.22259 -15.7954,-5.06556 -24.4687,-5.5625 -0.021,-10e-4 -0.042,0.001 -0.063,0 z"
493 id="path4426"
494 style="fill:#484848;fill-opacity:1;stroke:#484848;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
495 <path
496 d="m 252.9376,106.30395 c -3.4993,0.0307 -6.9607,-0.0581 -10.375,0.0312 -4.1004,0.36044 -9.0376,1.69024 -12.625,4.09375 -3.614,2.42133 -5.8704,5.68864 -5.2813,10.4375 0.4935,4.61527 3.5645,7.56447 7.6876,9.21875 4.123,1.65428 9.2633,1.8209 13.1562,0.65625 a 1.3611835,1.3611835 0 0 1 0.1562,-0.0312 c 2.8688,-0.49834 6.5939,-1.2529 9.2813,-2.71875 1.3437,-0.73292 2.3836,-1.63683 3.0313,-2.6875 0.6476,-1.05067 0.9604,-2.26047 0.6874,-3.96875 a 1.3611835,1.3611835 0 0 1 0,-0.28125 c 0.1564,-2.76724 0.3451,-6.68524 -0.375,-9.71875 -0.36,-1.51676 -0.9264,-2.77474 -1.75,-3.625 -0.8176,-0.8442 -1.8698,-1.36151 -3.5624,-1.40625 -0.012,-3.2e-4 -0.019,2.7e-4 -0.031,0 z"
497 id="path5306"
498 style="color:#000000;fill:url(#linearGradient4439);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22" />
499 <path
500 id="text4338"
501 d="m 550.24144,11.97714 c -4.7431,8e-5 -9.3884,1.94508 -12.1562,5.65625 -2.3938,3.20927 -3.2655,7.28209 -3.5,11.84374 -5.2417,0.10768 -9.658,0.71067 -13.2813,2.53125 -3.7519,1.88519 -6.5576,5.75636 -6.9063,9.9375 l -0.062,0 c -0.013,0.1027 0.011,0.20947 0,0.3125 0,0.043 -0.03,0.0819 -0.031,0.125 l 0.031,0 c -0.383,3.94189 0.8037,8.08581 3.625,10.84375 1.7434,1.70445 3.9242,2.79035 6.3124,3.59375 l -0.875,2.4375 -0.062,0.125 -0.031,0.125 c -1.0239,3.32791 -0.9882,7.09444 0.8437,10.15625 1.8322,3.06181 4.9132,4.85334 8.3438,5.90625 l 0.7188,0.21875 0.75,0 2.2812,0 c 4.1038,5e-5 8.0184,-1.11288 11.1562,-3.5 1.388,-1.05587 2.5677,-2.38102 3.5938,-3.8125 2.738,2.5559 6.0541,4.80834 10,6.78125 l 0.5,0.25 0.5312,0.15625 c 3.235,0.79227 6.3972,0.95306 9.4063,-0.1875 2.9956,-1.13542 5.3523,-3.78973 6.4375,-6.71875 l 0.031,0 0,-0.0312 c 1.3188,-3.58119 1.0754,-7.65809 -0.4687,-11.1875 -0.3593,-0.82136 -0.9637,-1.56048 -1.4375,-2.34375 0.7988,-0.35352 1.5774,-0.75006 2.3125,-1.28125 3.1456,-2.2731 4.4669,-6.43958 4.1563,-10.25 l 0.031,0 c 0,-0.12851 -0.061,-0.24691 -0.062,-0.375 -0.017,-0.15367 0.023,-0.31671 0,-0.46875 l -0.062,0 c -0.2506,-3.85862 -2.6242,-7.47641 -5.875,-9.5625 -3.1968,-2.05143 -7.2278,-3.19745 -12.0625,-4.03124 -0.5947,-4.02941 -1.4462,-7.64148 -3.125,-10.53125 -2.2702,-3.9078 -6.5646,-6.71865 -11.0625,-6.71875 z m 18.3125,50.62499 c 0.2654,0.97712 0.2969,1.7705 -0.031,2.65625 l 0,0.0312 c -0.3181,0.86918 -0.3036,0.72198 -0.625,0.84375 -0.2585,0.098 -1.2073,0.14918 -2.5624,-0.0625 0.3313,-0.1475 0.7366,-0.14338 1.0312,-0.34375 l 0.4375,-0.28125 0.375,-0.40625 c 0.5814,-0.62017 0.9776,-1.55372 1.375,-2.4375 z"
502 style="color:#000000;fill:#305f00;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:10" />
503 <g
504 id="text4342"
505 style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:165.01513672px;line-height:125%;font-family:'comic andy';-inkscape-font-specification:'comic andy';letter-spacing:0px;word-spacing:0px;fill:url(#linearGradient4437);fill-opacity:1;stroke:none">
506 <path
507 id="path101"
508 style="fill:url(#linearGradient4437);fill-opacity:1"
509 d="m 550.24549,16.984496 q 8.54083,0 9.83001,16.920498 l 2.33664,0 q 15.22844,2.33664 15.0673,9.668855 1.28918,8.621397 -11.03861,7.976806 9.42713,8.299101 6.7682,15.470169 -2.09492,5.72074 -9.99116,3.786969 -8.70197,-4.350985 -12.32779,-9.991151 l -1.5309,0 q -3.3841,9.991151 -13.13353,9.991151 l -2.25606,0 q -8.13796,-2.497788 -5.88189,-9.830003 l 2.82008,-7.815659 -0.80574,0 q -11.92492,-1.692049 -10.79688,-10.555167 0.32229,-8.137954 16.35648,-8.218527 4.43155,-0.483443 3.70639,-2.820083 0,-14.583858 10.87746,-14.583858 z m -4.5927,16.034186 -0.16115,4.512133 q -0.24172,3.384099 -2.17549,3.384099 l -12.73066,0.725164 q -2.98123,0.08057 -2.98123,2.417214 0,2.256067 3.22295,2.417214 11.19976,-0.564016 10.47459,1.530902 l -2.25606,4.834428 q -5.72074,8.621396 -2.82009,10.152299 3.86754,2.33664 10.95804,-12.08607 1.69205,-1.530902 2.82008,0 4.99558,5.317871 8.21853,8.70197 3.30353,3.3841 5.31787,2.014345 2.41721,-2.578361 -1.28918,-5.559592 -3.62582,-3.061804 -8.2991,-8.379675 -0.48344,-1.772623 0.24172,-1.772623 15.79246,1.047459 15.14787,-2.014345 0.48345,-3.3841 -13.69754,-3.3841 -2.17549,0.402869 -3.54525,-1.047459 l 0,-7.896232 q 0,-6.607052 -3.14238,-6.526478 -3.3841,-0.805738 -3.30352,7.976806 z" />
510 </g>
511 <path
512 style="fill:#484848;fill-opacity:1;stroke:#484848;stroke-width:3;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
513 id="path4714"
514 d="m 335.7911,64.63031 c -9.6363,0.58398 -20.9336,2.59484 -26.0312,10.625 -0.4035,0.99026 -0.045,1.9107 0.6562,2.5 0.717,0.60234 1.4896,0.85243 2.5626,0 a 1.684398,1.684398 0 0 1 0.625,-0.3125 c 5.775,-1.5733 12.3167,-3.78461 18.9374,-4.625 6.6208,-0.84039 13.4444,-0.25925 19.4063,3.84375 a 1.684398,1.684398 0 0 1 0.375,0.375 c 2.0281,2.75755 2.9112,6.50666 2.5937,10.125 -0.3174,3.61834 -1.9072,7.25777 -5.2187,9.15625 a 1.684398,1.684398 0 0 1 -0.4687,0.1875 c -4.4561,1.00721 -8.7953,0.29068 -12.875,-0.1875 -4.0798,-0.47818 -7.8868,-0.73461 -11.5313,0.59375 a 1.684398,1.684398 0 0 1 -0.1563,0.0312 c -11.7884,2.8498 -19.5228,15.78804 -17.4062,27.59375 a 1.684398,1.684398 0 0 1 0,0.65625 c -1.0407,5.14641 2.2557,9.72666 7.3438,10.59375 a 1.684398,1.684398 0 0 1 0.2812,0.0625 c 11.7498,4.04484 24.8758,2.18109 37.0625,-0.3125 a 1.684398,1.684398 0 0 1 1.2813,0.28125 c 2.0816,1.42722 4.4575,3.29235 6.625,4.1875 1.0837,0.44757 2.0633,0.63094 2.9374,0.53125 0.8627,-0.0984 1.6764,-0.44585 2.5938,-1.375 0.01,-0.0118 0.022,-0.0195 0.031,-0.0312 2.6608,-3.43997 2.9705,-7.61463 2.625,-12.3125 -0.3431,-4.66636 -1.3766,-9.66321 -1,-14.46875 -0.9524,-14.4251 -1.1073,-29.45823 -6.7187,-42.15625 -6.4124,-5.22259 -15.7954,-5.06556 -24.4687,-5.5625 -0.021,-10e-4 -0.042,0.001 -0.063,0 z" />
515 <path
516 style="color:#000000;fill:url(#linearGradient4435);fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:22"
517 id="path5310"
518 d="m 345.6192,106.30395 c -3.4993,0.0307 -6.9607,-0.0581 -10.375,0.0312 -4.1004,0.36044 -9.0376,1.69024 -12.625,4.09375 -3.614,2.42133 -5.8704,5.68864 -5.2813,10.4375 0.4935,4.61527 3.5645,7.56447 7.6876,9.21875 4.123,1.65428 9.2633,1.8209 13.1562,0.65625 a 1.3611835,1.3611835 0 0 1 0.1562,-0.0312 c 2.8688,-0.49834 6.5939,-1.2529 9.2813,-2.71875 1.3437,-0.73292 2.3836,-1.63683 3.0313,-2.6875 0.6476,-1.05067 0.9604,-2.26047 0.6874,-3.96875 a 1.3611835,1.3611835 0 0 1 0,-0.28125 c 0.1564,-2.76724 0.3451,-6.68524 -0.375,-9.71875 -0.36,-1.51676 -0.9264,-2.77474 -1.75,-3.625 -0.8176,-0.8442 -1.8698,-1.36151 -3.5624,-1.40625 -0.012,-3.2e-4 -0.019,2.7e-4 -0.031,0 z" />
519 </g>
520 </g>
521 </g>
522</svg>
diff --git a/doc/md/images/firefoxshare.png b/doc/md/images/firefoxshare.png
new file mode 100644
index 00000000..98c2fdd3
--- /dev/null
+++ b/doc/md/images/firefoxshare.png
Binary files differ
diff --git a/doc/md/images/rss-filter-1.png b/doc/md/images/rss-filter-1.png
new file mode 100644
index 00000000..d2a03f67
--- /dev/null
+++ b/doc/md/images/rss-filter-1.png
Binary files differ
diff --git a/doc/md/images/rss-filter-2.png b/doc/md/images/rss-filter-2.png
new file mode 100644
index 00000000..538b126e
--- /dev/null
+++ b/doc/md/images/rss-filter-2.png
Binary files differ
diff --git a/doc/md/index.md b/doc/md/index.md
new file mode 100644
index 00000000..b10e3cf4
--- /dev/null
+++ b/doc/md/index.md
@@ -0,0 +1,115 @@
1# [Shaarli](https://github.com/shaarli/Shaarli/) documentation
2
3Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
4
5For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
6
7If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues).
8If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
9
10If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).
11
12_Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the `doc/html/` directory of your Shaarli installation._
13
14[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli)
15[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues)
16[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/)
17
18### Demo
19
20You can use this [public demo instance of Shaarli](https://demo.shaarli.org).
21It runs the latest development version of Shaarli and is updated/reset daily.
22
23Login: `demo`; Password: `demo`
24
25
26## Features
27
28### Interface
29- minimalist design (simple is beautiful)
30- FAST
31- ATOM and RSS feeds
32- views:
33 - paginated link list
34 - tag cloud
35 - picture wall: image and video thumbnails
36 - daily: newspaper-like daily digest
37 - daily RSS feed
38- permalinks for easy reference
39- links can be public or private
40- extensible through [plugins](https://github.com/shaarli/Shaarli/wiki/Plugins#plugin-usage)
41
42### Tag, view and search your links!
43- add a custom title and description to archived links
44- add tags to classify and search links
45 - features tag autocompletion, renaming, merging and deletion
46- full-text and tag search
47
48### Easy setup
49- dead-simple installation: drop the files, open the page
50- links are stored in a file
51 - compact storage
52 - no database required
53 - easy backup: simply copy the datastore file
54- import and export links as Netscape bookmarks
55
56### Accessibility
57- Firefox bookmarlet to share links in one click
58- support for mobile browsers
59- works with Javascript disabled
60- easy page customization through HTML/CSS/RainTPL
61
62### Security
63- bruteforce-proof login form
64- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery)
65and session cookie hijacking
66
67### Goodies
68- thumbnail generation for images and video services:
69dailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...
70 - lazy-loading with [bLazy](http://dinbror.dk/blazy/)
71- [PubSubHubbub](https://code.google.com/p/pubsubhubbub/) protocol support
72- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
73- discreet pop-up notification when a new release is available
74
75### REST API
76
77Easily extensible by any client using the REST API exposed by Shaarli.
78
79See the [API documentation](http://shaarli.github.io/api-documentation/).
80
81### Other usages
82Though Shaarli is primarily a bookmarking application, it can serve other purposes
83(see [Features](Features)):
84
85- micro-blogging
86- pastebin
87- online notepad
88- snippet archive
89
90## About
91### Shaarli community fork
92This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli
93
94This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/).
95
96The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191)
97that he would have no time to work on Shaarli in the near future.
98The Shaarli community has carried on the work to provide
99[many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master)
100for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+)
101in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
102
103### Contributing
104If you'd like to help, please:
105- have a look at the open [issues](https://github.com/shaarli/Shaarli/issues)
106and [pull requests](https://github.com/shaarli/Shaarli/pulls)
107- feel free to report bugs (feedback is much appreciated)
108- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/wiki)
109- propose solutions to existing problems
110- submit pull requests :-)
111
112
113### License
114Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](COPYING) for a detail of the contributors and licenses for each individual component.
115