From 4c1bcd8b254e3376ee1a6d1108a0e56b550f28db Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Wed, 14 Feb 2018 21:58:41 +0100 Subject: doc: update Directory Structure Signed-off-by: VirtualTam --- doc/md/Directory-structure.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Directory-structure.md b/doc/md/Directory-structure.md index eb50965b..937a076d 100644 --- a/doc/md/Directory-structure.md +++ b/doc/md/Directory-structure.md @@ -1,4 +1,4 @@ -TODO: This page is out of date +## Directory structure Here is the directory structure of Shaarli and the purpose of the different files: @@ -6,10 +6,16 @@ Here is the directory structure of Shaarli and the purpose of the different file index.php # Main program application/ # Shaarli classes ├── LinkDB.php + + ... + └── Utils.php - tests/ # Shaarli unitary & functional tests + tests/ # Shaarli unitary & functional tests ├── LinkDBTest.php - ├── utils # utilities to ease testing + + ... + + ├── utils # utilities to ease testing │ └── ReferenceLinkDB.php └── UtilsTest.php COPYING # Shaarli license @@ -18,17 +24,18 @@ Here is the directory structure of Shaarli and the purpose of the different file ├── blazy.* # picture wall lazy image loading library ├── shaarli.css, reset.css # Shaarli stylesheet. ├── qr.* # qr code generation library - └──rain.tpl.class.php # RainTPL templating library - tpl/ # RainTPL templates for Shaarli. They are used to build the pages. + └── rain.tpl.class.php # RainTPL templating library images/ # Images and icons used in Shaarli - data/ # data storage: bookmark database, configuration, logs, banlist… - ├── config.php # Shaarli configuration (login, password, timezone, title…) + data/ # data storage: bookmark database, configuration, logs, banlist... + ├── config.json.php # Shaarli configuration (login, password, timezone, title...) ├── datastore.php # Your link database (compressed). ├── ipban.php # IP address ban system data ├── lastupdatecheck.txt # Update check timestamp file - └──log.txt # login/IPban log. + └── log.txt # login/IPban log. + tpl/ # RainTPL templates for Shaarli. They are used to build the pages. cache/ # thumbnails cache # This directory is automatically created. You can erase it anytime you want. tmp/ # Temporary directory for compiled RainTPL templates. # This directory is automatically created. You can erase it anytime you want. + vendor/ # Third-party dependencies. This directory is created by Composer ``` -- cgit v1.2.3 From 48679a159ed2e419f207d0be2e03e1a4f0e24f1d Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Wed, 14 Feb 2018 22:02:34 +0100 Subject: doc: update references to config(.json)?.php Closes https://github.com/shaarli/Shaarli/issues/1082 Signed-off-by: VirtualTam --- doc/md/Plugins.md | 4 ++-- doc/md/Troubleshooting.md | 18 +++++++----------- doc/md/Upgrade-and-migration.md | 11 +++++++---- 3 files changed, 16 insertions(+), 17 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Plugins.md b/doc/md/Plugins.md index 463dae17..954442e2 100644 --- a/doc/md/Plugins.md +++ b/doc/md/Plugins.md @@ -37,7 +37,7 @@ This is important in case plugins are depending on each other. Read plugins READ ## File mode -Enabled plugin are stored in your `config.php` parameters file, under the `array`: +Enabled plugin are stored in your `config.json.php` parameters file, under the `array`: ```php $GLOBALS['config']['ENABLED_PLUGINS'] @@ -48,7 +48,7 @@ Example: ```php $GLOBALS['config']['ENABLED_PLUGINS'] = array( - 'qrcode', + 'qrcode', 'archiveorg', 'wallabag', 'markdown', diff --git a/doc/md/Troubleshooting.md b/doc/md/Troubleshooting.md index b2d86d40..570f6956 100644 --- a/doc/md/Troubleshooting.md +++ b/doc/md/Troubleshooting.md @@ -63,7 +63,7 @@ Related threads: ### I forgot my password! -Delete the file `data/config.php` and display the page again. You will be asked for a new login/password. +Delete the file `data/config.json.php` and display the page again. You will be asked for a new login/password. ### I'm locked out - Login bruteforce protection @@ -97,7 +97,7 @@ php56 1 ```php //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive. -// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) in html +// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) in html //if (strpos($status,'200 OK')) $title=html_extract_title($data); ``` @@ -106,11 +106,11 @@ php56 1 ### Dates are not properly formatted -Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( ) - -### Problems on CentOS servers - -On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package. +Shaarli tries to sniff the language of the browser (using `HTTP_ACCEPT_LANGUAGE` headers) +and choose a date format accordingly. But Shaarli can only use the date formats +(and more generally 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 :-( ) ### My session expires! I can't stay logged in @@ -126,7 +126,3 @@ This can be caused by several things: ## Sessions do not seem to work correctly on your server Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)). - -### pubsubhubbub support - -Download [publisher.php](https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php) at the root of your Shaarli installation and set `$GLOBALS['config']['PUBSUBHUB_URL']` in your `config.php` diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md index 1dc07339..f666be75 100644 --- a/doc/md/Upgrade-and-migration.md +++ b/doc/md/Upgrade-and-migration.md @@ -2,14 +2,14 @@ ### Note your current version -If anything goes wrong, it's important for us to know which version you're upgrading from. +If anything goes wrong, it's important for us to know which version you're upgrading from. The current version is present in the `version.php` file. ### Backup your data Shaarli stores all user data under the `data` directory: -- `data/config.php` - main configuration file +- `data/config.json.php` (or `data/config.php` for older Shaarli versions) - main configuration file - `data/datastore.php` - bookmarked links - `data/ipbans.php` - banned IP addresses - `data/updates.txt` - contains all automatic update to the configuration and datastore files already run @@ -39,7 +39,7 @@ We recommend that you use the latest release tarball with the `-full` suffix. It Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! -If you use translations in gettext mode - meaning you manually changed the default mode -, +If you use translations in gettext mode - meaning you manually changed the default mode -, reload your web server. After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details). @@ -192,7 +192,10 @@ Total 3317 (delta 2050), reused 3301 (delta 2034)to #### Step 3: configuration -After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration) for more details). +After migrating, access your fresh Shaarli installation from a web browser; the +configuration will then be automatically updated, and new settings added to +`data/config.json.php` (see [Shaarli configuration](Shaarli-configuration) for more +details). ## Troubleshooting -- cgit v1.2.3 From 6c4cc14e005604b2ab8a1ae7a9190b6a287f6f8d Mon Sep 17 00:00:00 2001 From: "Alexandre G.-Raymond" Date: Sun, 25 Mar 2018 14:08:07 +0200 Subject: Fix current version file name in docs --- doc/md/Upgrade-and-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md index f666be75..ac24ff34 100644 --- a/doc/md/Upgrade-and-migration.md +++ b/doc/md/Upgrade-and-migration.md @@ -3,7 +3,7 @@ ### Note your current version If anything goes wrong, it's important for us to know which version you're upgrading from. -The current version is present in the `version.php` file. +The current version is present in the `shaarli_version.php` file. ### Backup your data -- cgit v1.2.3 From ee242ae3213224f218afa05729afba6bd3e7271f Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sun, 25 Mar 2018 20:09:26 +0200 Subject: Documentation: release v0.9.6 Signed-off-by: VirtualTam --- doc/md/Download-and-Installation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md index 0fdbd27d..05f0c8f2 100644 --- a/doc/md/Download-and-Installation.md +++ b/doc/md/Download-and-Installation.md @@ -25,11 +25,11 @@ Using one of the following methods: In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies. -The current latest released version is `v0.9.3` +The current latest released version is `v0.9.6` ```bash -$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.3/shaarli-v0.9.3-full.zip -$ unzip shaarli-v0.9.3-full.zip +$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.6/shaarli-v0.9.6-full.zip +$ unzip shaarli-v0.9.6-full.zip $ mv Shaarli /path/to/shaarli/ ``` -- cgit v1.2.3 From 68c6afc56f3758154cfb96cba6fd48a6b5535590 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Mon, 26 Feb 2018 22:53:00 +0100 Subject: Load theme translations files automatically Fixes #1077 Take a look at the docs update to see how it works --- doc/md/Translations.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc/md') diff --git a/doc/md/Translations.md b/doc/md/Translations.md index 54a36655..c7d33855 100644 --- a/doc/md/Translations.md +++ b/doc/md/Translations.md @@ -76,6 +76,18 @@ Then click on the "Update" button, and you can start to translate every availabl Save when you're done, then you can submit a pull request containing the new `shaarli.po`. +### Theme translations + +Theme translation extensions are loaded automatically if they're present. + +As a theme developer, all you have to do is to add the `.po` and `.mo` compiled file like this: + + tpl//language//LC_MESSAGES/.po + tpl//language//LC_MESSAGES/.mo + +Where `` is the ISO 3166-1 alpha-2 language code. +Read the following section "Extend Shaarli's translation" to learn how to generate those files. + ### Extend Shaarli's translation If you're writing a custom theme, or a non official plugin, you might want to use the translation system, -- cgit v1.2.3 From d7eb06bd7c4d01bbdf67f4f100af7a3e300098d3 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sat, 24 Feb 2018 18:46:11 +0100 Subject: Webpack / Documentation update --- doc/md/Continuous-integration-tools.md | 7 ++++--- doc/md/Development-guidelines.md | 9 ++++++--- doc/md/Directory-structure.md | 21 +++++++++++++++++---- doc/md/Download-and-Installation.md | 7 ++++++- doc/md/Upgrade-and-migration.md | 14 ++++++++++++++ 5 files changed, 47 insertions(+), 11 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md index 4bd7a0ba..4ca6bdc7 100644 --- a/doc/md/Continuous-integration-tools.md +++ b/doc/md/Continuous-integration-tools.md @@ -2,8 +2,8 @@ A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations: - Documentation - generate a local HTML copy of the GitHub wiki -- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions -- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits +- [Static analysis](Static-analysis) - check that the code is compliant to PHP conventions +- [Unit tests](Unit-tests) - ensure there are no regressions introduced by new commits ## Automatic builds [Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build: @@ -17,7 +17,8 @@ Each build job: - updates Composer - installs 3rd-party test dependencies with Composer -- runs [Unit tests](Unit tests) +- runs [Unit tests](Unit-tests) +- runs ESLint check After all jobs have finished, Travis returns the results to GitHub: diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md index 532ec2e4..46b7c6f8 100644 --- a/doc/md/Development-guidelines.md +++ b/doc/md/Development-guidelines.md @@ -3,8 +3,11 @@ Please have a look at the following pages: - [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) -- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: +- [Static analysis](Static-analysis) - patches should try to stick to the +[PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide -- [Unit tests](Unit tests) -- [GnuPG signature](GnuPG signature) for tags/releases +- [Unit tests](Unit-tests) +- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). +Run `make eslint` to check JS style. +- [GnuPG signature](GnuPG-signature) for tags/releases diff --git a/doc/md/Directory-structure.md b/doc/md/Directory-structure.md index 937a076d..c0b49393 100644 --- a/doc/md/Directory-structure.md +++ b/doc/md/Directory-structure.md @@ -18,12 +18,18 @@ Here is the directory structure of Shaarli and the purpose of the different file ├── utils # utilities to ease testing │ └── ReferenceLinkDB.php └── UtilsTest.php + assets/ + ├── common/ # Assets shared by multiple themes + ├── ... + ├── default/ # Assets for the default template, before compilation + ├── fonts/ # Font files + ├── img/ # Images used by the default theme + ├── js/ # JavaScript files in ES6 syntax + ├── scss/ # SASS files + └── vintage/ # Assets for the vintage template, before compilation + └── ... COPYING # Shaarli license inc/ # static assets and 3rd party libraries - ├── awesomplete.* # tags autocompletion library - ├── blazy.* # picture wall lazy image loading library - ├── shaarli.css, reset.css # Shaarli stylesheet. - ├── qr.* # qr code generation library └── rain.tpl.class.php # RainTPL templating library images/ # Images and icons used in Shaarli data/ # data storage: bookmark database, configuration, logs, banlist... @@ -33,6 +39,13 @@ Here is the directory structure of Shaarli and the purpose of the different file ├── lastupdatecheck.txt # Update check timestamp file └── log.txt # login/IPban log. tpl/ # RainTPL templates for Shaarli. They are used to build the pages. + ├── default/ # Default Shaarli theme + ├── fonts/ # Font files + ├── img/ # Images + ├── js/ # JavaScript files compiled by Babel and compatible with all browsers + ├── css/ # CSS files compiled with SASS + └── vintage/ # Legacy Shaarli theme + └── ... cache/ # thumbnails cache # This directory is automatically created. You can erase it anytime you want. tmp/ # Temporary directory for compiled RainTPL templates. diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md index 05f0c8f2..20138f49 100644 --- a/doc/md/Download-and-Installation.md +++ b/doc/md/Download-and-Installation.md @@ -38,12 +38,14 @@ $ mv Shaarli /path/to/shaarli/ Cloning using `git` or downloading Github branches as zip files requires additional steps: * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. + * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies. * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation. ``` $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ $ git clone -b latest https://github.com/shaarli/Shaarli.git . $ composer install --no-dev --prefer-dist +$ make build_frontend $ make translate $ make htmldoc ``` @@ -91,7 +93,9 @@ $ composer install --no-dev --prefer-dist _Use at your own risk!_ -Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. +Install [Composer](Unit-tests.md#install_composer) to manage Shaarli PHP dependencies, +and [yarn](https://yarnpkg.com/lang/en/docs/install/) +for front-end dependencies. To get the latest changes from the `master` branch: @@ -101,6 +105,7 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/ # install/update third-party dependencies $ cd /path/to/shaarli $ composer install --no-dev --prefer-dist +$ make build_frontend $ make translate $ make htmldoc ``` diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md index ac24ff34..451ca36d 100644 --- a/doc/md/Upgrade-and-migration.md +++ b/doc/md/Upgrade-and-migration.md @@ -83,6 +83,13 @@ $ make translate If you use translations in gettext mode, reload your web server. +Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install +[yarn](https://yarnpkg.com/lang/en/docs/install/): + +```bash +$ make build_frontend +``` + ### Migrating and upgrading from Sebsauvage's repository If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy. @@ -170,6 +177,13 @@ $ make translate If you use translations in gettext mode, reload your web server. +Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install +[yarn](https://yarnpkg.com/lang/en/docs/install/): + +```bash +$ make build_frontend +``` + Optionally, you can delete information related to the legacy version: ```bash -- cgit v1.2.3 From d66b5acb24af1049fb471bad0911939de97b91c5 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Thu, 5 Apr 2018 20:54:23 +0200 Subject: Update documentation and Doxygen icon location Signed-off-by: VirtualTam --- doc/md/Bookmarklet.md | 4 ++-- doc/md/images/edit_icon.png | Bin 0 -> 1548 bytes doc/md/images/logo.png | Bin 0 -> 5456 bytes 3 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 doc/md/images/edit_icon.png create mode 100644 doc/md/images/logo.png (limited to 'doc/md') diff --git a/doc/md/Bookmarklet.md b/doc/md/Bookmarklet.md index c899e3cf..6c7f1c6a 100644 --- a/doc/md/Bookmarklet.md +++ b/doc/md/Bookmarklet.md @@ -13,8 +13,8 @@ _This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. U - When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added. - A window opens. - You can freely edit title, description, tags... to find it later using the text search or tag filtering. - - You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button. - - You can also check the “Private” box so that the link is saved but only visible to you. + - You will be able to edit this link later using the ![](images/edit_icon.png) edit button. + - You can also check the “Private” box so that the link is saved but only visible to you. - Click `Save`.**Voilà! Your link is now shared.** ## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com) diff --git a/doc/md/images/edit_icon.png b/doc/md/images/edit_icon.png new file mode 100644 index 00000000..16c440c8 Binary files /dev/null and b/doc/md/images/edit_icon.png differ diff --git a/doc/md/images/logo.png b/doc/md/images/logo.png new file mode 100644 index 00000000..f8b0c94f Binary files /dev/null and b/doc/md/images/logo.png differ -- cgit v1.2.3 From 80786e150d03409435bcd63601c4d95e27cac225 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Wed, 7 Feb 2018 20:10:05 +0100 Subject: doc: merge all sharing methods under a single "Sharing content" page * formatting, wording, reordering, general improvements * move blog/pastebin/notepad item from index.md to this page * add TODOs * add the new page to mkdocs TOC Part of https://github.com/shaarli/Shaarli/issues/598 --- doc/md/Bookmarklet.md | 29 ---------------- doc/md/Firefox-share.md | 20 ----------- doc/md/Sharing-content.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++ doc/md/index.md | 7 ---- 4 files changed, 88 insertions(+), 56 deletions(-) delete mode 100644 doc/md/Bookmarklet.md delete mode 100644 doc/md/Firefox-share.md create mode 100644 doc/md/Sharing-content.md (limited to 'doc/md') diff --git a/doc/md/Bookmarklet.md b/doc/md/Bookmarklet.md deleted file mode 100644 index 6c7f1c6a..00000000 --- a/doc/md/Bookmarklet.md +++ /dev/null @@ -1,29 +0,0 @@ -## Add the sharing button (_bookmarklet_) to your browser - -- Open your Shaarli and `Login` -- Click the `Tools` button in the top bar -- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar. - -_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._ - -![](images/bookmarklet.png) - -## Share links using the _bookmarklet_ - -- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added. -- A window opens. - - You can freely edit title, description, tags... to find it later using the text search or tag filtering. - - You will be able to edit this link later using the ![](images/edit_icon.png) edit button. - - You can also check the “Private” box so that the link is saved but only visible to you. -- Click `Save`.**Voilà! Your link is now shared.** - -## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com) - -Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it. - -See [#196](https://github.com/shaarli/Shaarli/issues/196). - -There is an open bug for both Firefox and Chromium: - -- https://bugzilla.mozilla.org/show_bug.cgi?id=866522 -- https://code.google.com/p/chromium/issues/detail?id=233903 diff --git a/doc/md/Firefox-share.md b/doc/md/Firefox-share.md deleted file mode 100644 index 9a46b185..00000000 --- a/doc/md/Firefox-share.md +++ /dev/null @@ -1,20 +0,0 @@ -| Note | Firefox Share is no longer available for Firefox 57 and later versions. | -|---------|---------| - -### Add Shaarli as a sharing service to Firefox - -- Open your Shaarli and `Login` -- Click the `Tools` button in the top bar -- Click the `✚Add to Firefox social` button and accept the activation. - - -### Sharing links using Firefox share - -- Add the sharing service as described above -- When you are visiting a webpage you would like to share with Shaarli, - click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png) -- You can edit your link before and after saving, just like the bookmarklet above. - -_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) -enabled server for Firefox Share to work. Firefox Share will not work over -plain HTTP connections._ diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md new file mode 100644 index 00000000..8d8c15a9 --- /dev/null +++ b/doc/md/Sharing-content.md @@ -0,0 +1,88 @@ +Content posted to Shaarli is separated in items called _Shaares_. For each Shaare, +you can customize the following aspects: + + * URL to link to + * Title + * Free-text description + * Tags + * Public/private status + +-------------------------------------------------------------------------------- + +## Adding new Shaares + +While logged in to your Shaarli, you can add new Shaares in several ways: + + * [+Shaare button] + * [Bookmarklet] + * [Firefox Share](#firefox-share) + * Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps) + + +### +Shaare button + + * While logged in to your Shaarli, click the **`+Shaare`** button located in the toolbar. + * Enter the URL of a link you want to share. + * Click `Add link` + * The `New Shaare` dialog appears, allowing you to fill in the details of your Shaare. + * The Description, Title, and Tags will help you find your Shaare later using tags or full-text search. + * You can also check the “Private” box so that the link is saved but only visible to you (the logged-in user). + * Click `Save`. + + + +### Bookmarklet + +The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special +browser bookmark you can use to add new content to your Shaarli. This bookmarklet is +compatible with Firefox, Opera, Chrome and Safari. To set it up: + + * Access the `Tools` page from the button in the toolbar. + * Drag the **`✚Shaare link` button** to your browser's bookmarks bar. + +Once this is done, you can shaare any URL you are visiting simply by clicking the +bookmarklet in your browser! The same `New Shaare` dialog as above is displayed. + +| Note | Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunately, there is nothing Shaarli can do about it. \[[1](https://github.com/shaarli/Shaarli/issues/196)]\ \[[2](https://bugzilla.mozilla.org/show_bug.cgi?id=866522)]\ \[[3](https://code.google.com/p/chromium/issues/detail?id=233903)]\ | +|---------|---------| + +| Note | Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar. | +|---------|---------| + +![](images/bookmarklet.png) + + +### Firefox Share + +Before using Firefox Share, you must first add Shaarli as a sharing provider: + +- Click the `Tools` button in the top bar +- Click the `✚Add to Firefox social` button and accept the activation. + +Once this is done, you can share any URL you are visiting by clicking the Firefox +_Share_ button [images/firefoxshare.png](images/firefoxshare.png) + +| Note | Firefox Share is no longer available for Firefox 57 and later versions. | +|---------|---------| + +| Note | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plaintext HTTP connections. | +|---------|---------| + +-------------------------------------------------------------------------------- + +## Editing Shaares + +Any Shaare can edited by clicking its ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) `Edit` button. + +Editing a Shaare will not change it's permalink, each permalink always points to the +latest revision of a Shaare. + +-------------------------------------------------------------------------------- + +## Using shaarli as a blog, notepad, pastebin... + +While adding or editing a link, leave the URL field blank to create a text-only +("note") post. This allows you to post any kind of text content, such as blog +articles, private or public notes, snippets... There is no character limit! You can +access your Shaare from its permalink. + diff --git a/doc/md/index.md b/doc/md/index.md index e77b4d3a..224070cb 100644 --- a/doc/md/index.md +++ b/doc/md/index.md @@ -94,13 +94,6 @@ Easily extensible by any client using the REST API exposed by Shaarli. See the [API documentation](http://shaarli.github.io/api-documentation/). -### Using Shaarli as a blog, notepad, pastebin... -- Go to your Shaarli setup and log in -- Click the `Add Link` button -- To share text only, do not enter any URL in the corresponding input field and click `Add Link` -- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save` -- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink. - ## About ### Shaarli community fork This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli -- cgit v1.2.3 From bf7993dcebe1518f8c4759f397309937ebc4de71 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Fri, 9 Feb 2018 18:44:06 +0100 Subject: doc: add edit_icon.png to git repository optimize icon with optipng/pngcrush (3.30%) --- doc/md/Sharing-content.md | 2 +- doc/md/images/edit_icon.png | Bin 1548 -> 2040 bytes 2 files changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md index 8d8c15a9..b185164c 100644 --- a/doc/md/Sharing-content.md +++ b/doc/md/Sharing-content.md @@ -72,7 +72,7 @@ _Share_ button [images/firefoxshare.png](images/firefoxshare.png) ## Editing Shaares -Any Shaare can edited by clicking its ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) `Edit` button. +Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button. Editing a Shaare will not change it's permalink, each permalink always points to the latest revision of a Shaare. diff --git a/doc/md/images/edit_icon.png b/doc/md/images/edit_icon.png index 16c440c8..777f3253 100644 Binary files a/doc/md/images/edit_icon.png and b/doc/md/images/edit_icon.png differ -- cgit v1.2.3 From 630790a1aa78d4b7e7fec0a84c23571f6dfd9df2 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Fri, 9 Feb 2018 18:46:28 +0100 Subject: doc: optimize PNGs with pngcrush 164k -> 156k --- doc/md/images/doc-logo.png | Bin 19543 -> 19520 bytes doc/md/images/edit_icon.png | Bin 2040 -> 1548 bytes doc/md/images/firefoxshare.png | Bin 757 -> 715 bytes doc/md/images/install-shaarli.png | Bin 44376 -> 33827 bytes doc/md/images/rss-filter-1.png | Bin 18682 -> 18534 bytes doc/md/images/rss-filter-2.png | Bin 15604 -> 15440 bytes 6 files changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/md') diff --git a/doc/md/images/doc-logo.png b/doc/md/images/doc-logo.png index 3d8d1787..3da7ba57 100644 Binary files a/doc/md/images/doc-logo.png and b/doc/md/images/doc-logo.png differ diff --git a/doc/md/images/edit_icon.png b/doc/md/images/edit_icon.png index 777f3253..16c440c8 100644 Binary files a/doc/md/images/edit_icon.png and b/doc/md/images/edit_icon.png differ diff --git a/doc/md/images/firefoxshare.png b/doc/md/images/firefoxshare.png index 98c2fdd3..8f8fdba4 100644 Binary files a/doc/md/images/firefoxshare.png and b/doc/md/images/firefoxshare.png differ diff --git a/doc/md/images/install-shaarli.png b/doc/md/images/install-shaarli.png index 7ae33816..d5d5baa7 100644 Binary files a/doc/md/images/install-shaarli.png and b/doc/md/images/install-shaarli.png differ diff --git a/doc/md/images/rss-filter-1.png b/doc/md/images/rss-filter-1.png index d2a03f67..0cf1591c 100644 Binary files a/doc/md/images/rss-filter-1.png and b/doc/md/images/rss-filter-1.png differ diff --git a/doc/md/images/rss-filter-2.png b/doc/md/images/rss-filter-2.png index 538b126e..5a40755a 100644 Binary files a/doc/md/images/rss-filter-2.png and b/doc/md/images/rss-filter-2.png differ -- cgit v1.2.3 From 2e47af897e4f84d5f5266219385a8e930fc113d2 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Fri, 9 Feb 2018 19:03:42 +0100 Subject: doc: sharing: add link to REST API documentation --- doc/md/Sharing-content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md index b185164c..faacc1f9 100644 --- a/doc/md/Sharing-content.md +++ b/doc/md/Sharing-content.md @@ -17,7 +17,7 @@ While logged in to your Shaarli, you can add new Shaares in several ways: * [Bookmarklet] * [Firefox Share](#firefox-share) * Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps) - + * [REST API](https://shaarli.github.io/api-documentation/) ### +Shaare button -- cgit v1.2.3 From 4de024d7c3100f769d12fbfb24ae3599823b47af Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sun, 13 May 2018 12:32:41 +0200 Subject: Adds Stakali Android app to 3rd party lists --- doc/md/Community-&-Related-software.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md index 207153b6..7c570acf 100644 --- a/doc/md/Community-&-Related-software.md +++ b/doc/md/Community-&-Related-software.md @@ -38,9 +38,11 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal - [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension. - [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider - [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli +- [Stakali for Android](https://stakali.toneiv.eu) - Stakali is a personal bookmark manager which synchronizes with Shaarli ### Browser addons - * [Shaarli Web Extension](https://github.com/ikipatang/shaarli-web-extension) - toolbar button to share your current tab with Shaarli. +- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - toolbar button to share your current tab with Shaarli. +- [Shaarli Chrome Extension](https://github.com/octplane/Shiny-Shaarli) - toolbar button to share your current tab with Shaarli. ### Server apps - [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content -- cgit v1.2.3 From c064d3179e0396983bdf8dee545388e4142ed842 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sun, 17 Jun 2018 13:45:39 +0200 Subject: docker: update image and usage documentation Relates to https://github.com/shaarli/Shaarli/issues/1153 Signed-off-by: VirtualTam --- doc/md/Unit-tests-Docker.md | 6 +++--- doc/md/docker/shaarli-images.md | 14 ++++++++++---- 2 files changed, 13 insertions(+), 7 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Unit-tests-Docker.md b/doc/md/Unit-tests-Docker.md index c2de7cc7..59bd5b45 100644 --- a/doc/md/Unit-tests-Docker.md +++ b/doc/md/Unit-tests-Docker.md @@ -8,7 +8,7 @@ Read first: ### Docker test images -Test Dockerfiles are located under `docker/tests//Dockerfile`, +Test Dockerfiles are located under `tests/docker//Dockerfile`, and can be used to build Docker images to run Shaarli test suites under common Linux environments. @@ -27,7 +27,7 @@ What's behind the curtains: - test PHP dependencies (OS packages) - Composer - the local workspace is mapped to the container's `/shaarli/` directory, -- the files are rsync'd to so tests are run using a standard Linux user account +- the files are rsync'd so tests are run using a standard Linux user account (running tests as `root` would bypass permission checks and may hide issues) - the tests are run inside the container. @@ -36,7 +36,7 @@ What's behind the curtains: ```bash # build the Debian 9 Docker image $ cd /path/to/shaarli -$ cd docker/test/debian9 +$ cd tests/docker/debian9 $ docker build -t shaarli-test:debian9 . ``` diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md index 12f7b5d1..e6fbff64 100644 --- a/doc/md/docker/shaarli-images.md +++ b/doc/md/docker/shaarli-images.md @@ -8,9 +8,9 @@ The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaa repository. ### Available image tags -- `latest`: latest branch (tarball release) -- `master`: master branch (tarball release) -- `stable`: stable branch (tarball release) +- `latest`: latest branch +- `master`: master branch +- `stable`: stable branch The `latest` and `master` images rely on: @@ -24,7 +24,13 @@ The `stable` image relies on: - [PHP5-FPM](http://php-fpm.org/) - [Nginx](http://nginx.org/) -Additional [Dockerfiles](https://github.com/shaarli/Shaarli/tree/master/docker) are provided for the `arm32v7` platform, relying on [Linuxserver.io Alpine armhf images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be built using [`docker build`](https://docs.docker.com/engine/reference/commandline/build/) on an `arm32v7` machine or using an emulator such as [qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/). +Additional Dockerfiles are provided for the `arm32v7` platform, relying on +[Linuxserver.io Alpine armhf +images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be +built using [`docker +build`](https://docs.docker.com/engine/reference/commandline/build/) on an +`arm32v7` machine or using an emulator such as +[qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/). ### Download from DockerHub ```bash -- cgit v1.2.3 From bdfb967ca2f9d75791a2da2bb189d63df33638cc Mon Sep 17 00:00:00 2001 From: nodiscc Date: Fri, 20 Apr 2018 23:16:59 +0200 Subject: Improve documentation (#598, #1105) * rework/simplify server configuration/requirements pages (consolidate/simplify SSL/TLS/apache configuration) * update index.md introduction * remove external images (badges) * Fix COPYING link and documentation links * Update features list * dedpulicate information * remove server-requirements.md and move relevant doc to other files * TODO: rework nginx configuration (single configuration example, with commented out blocks for special cases) * TODO: consolidate download/install/configuration pages * remove blank lighttpd configuration section * remove Required? column for composer packages, all libraries are mandatory * php 7.2 compatibilty * clarify that certbot binary and paths may vary depending on install method --- doc/md/3rd-party-libraries.md | 16 ++- doc/md/Download-and-Installation.md | 7 +- doc/md/Server-configuration.md | 211 ++++++++++++++++++++---------------- doc/md/Server-requirements.md | 42 ------- doc/md/index.md | 74 ++++++++----- 5 files changed, 178 insertions(+), 172 deletions(-) delete mode 100644 doc/md/Server-requirements.md (limited to 'doc/md') diff --git a/doc/md/3rd-party-libraries.md b/doc/md/3rd-party-libraries.md index ebab7a46..7e7dd334 100644 --- a/doc/md/3rd-party-libraries.md +++ b/doc/md/3rd-party-libraries.md @@ -1,13 +1,21 @@ ## CSS -- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - - resets default CSS properties for all HTML elements (overriding browsers' default values) - - ensures custom CSS stylessheets will provide the same results on all browsers + +- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - standardize cross-browser rendering ## Javascript + - [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms - [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails - [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation ## PHP -- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser + - [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP + +### Composer + +Library | Usage +---|--- +[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | Import bookmarks from Netscape files +[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | Parse MarkDown syntax for the MarkDown plugin +[`slim/slim`](https://packagist.org/packages/slim/slim) | Handle routes and middleware for the REST API diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md index 20138f49..ebda2e8a 100644 --- a/doc/md/Download-and-Installation.md +++ b/doc/md/Download-and-Installation.md @@ -1,8 +1,7 @@ To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). -Also, please make sure your server meets the [requirements](Server-requirements) -and is properly [configured](Server-configuration). +Also, please make sure your server is properly [configured](Server-configuration). Multiple releases branches are available: @@ -23,7 +22,7 @@ Using one of the following methods: ### Download as an archive -In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies. +In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. Download our **shaarli-full** archive to include dependencies. The current latest released version is `v0.9.6` @@ -37,7 +36,7 @@ $ mv Shaarli /path/to/shaarli/ Cloning using `git` or downloading Github branches as zip files requires additional steps: - * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. + * Install [Composer](Unit-tests.md#install_composer) to manage third-party [PHP dependencies](3rd-party-libraries.md#composer). * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies. * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation. diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 25dd49fe..ca82b2ec 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -1,139 +1,130 @@ -*Example virtual host configurations for popular web servers* +- [Prerequisites](#prerequisistes) - [Apache](#apache) - [Nginx](#nginx) +- [Proxies](#proxies) +- [See also](#see-also) ## Prerequisites ### Shaarli -- Shaarli is installed in a directory readable/writeable by the user -- the correct read/write permissions have been granted to the web server _user and/or group_ -- for HTTPS / SSL: - - a key pair (public, private) and a certificate have been generated - - the appropriate server SSL extension is installed and active -### HTTPS, TLS and self-signed certificates -Related guides: +- A web server and PHP interpreter module/service have been installed. +- You have write access to the Shaarli installation directory. +- The correct read/write permissions have been granted to the web server user and group. +- Your PHP interpreter is compatible with supported PHP versions: -- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) -- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) -- Generate a self-signed certificate (will trigger browser warnings) with apache2: - `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key` +Version | Status | Shaarli compatibility +:---:|:---:|:---: +7.2 | Supported | Yes +7.1 | Supported | Yes +7.0 | Supported | Yes +5.6 | Supported | Yes +5.5 | EOL: 2016-07-10 | Yes +5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x) +5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x) -### Proxies -If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set: +- The following PHP extensions are installed on the server: -- `X-Forwarded-Proto` -- `X-Forwarded-Host` -- `X-Forwarded-For` +Extension | Required? | Usage +---|:---:|--- +[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS +[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support +[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing +[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) +[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way +[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster) -See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. +-------------------------------------------------------------------------------- -## Apache -### Minimal -```apache - - ServerName shaarli.my-domain.org - DocumentRoot /absolute/path/to/shaarli/ - -``` -### Debug - Log all the things! -This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors. +### SSL/TLS configuration -See: +To setup HTTPS / SSL on your webserver (recommended), you must generate a public/private **key pair** and a **certificate**, and install, configure and activate the appropriate **webserver SSL extension**. -- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow) -- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/) +#### Let's Encrypt -```apache - - ServerName shaarli.my-domain.org - DocumentRoot /absolute/path/to/shaarli/ +[Let's Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt) is a certificate authority that provides free TLS/X.509 certificates via an automated process. - LogLevel warn - ErrorLog /var/log/apache2/shaarli-error.log - CustomLog /var/log/apache2/shaarli-access.log combined + * Install `certbot` using the appropriate method described on https://certbot.eff.org/. + +Location of the `certbot` program and template configuration files may vary depending on which installation method was used. Change the file paths below accordingly. Here is an easy way to create a signed certificate using `certbot`, it assumes `certbot` was installed through APT on a Debian-based distribution: - php_flag log_errors on - php_flag display_errors on - php_value error_reporting 2147483647 - php_value error_log /var/log/apache2/shaarli-php-error.log - -``` + * Stop the apache2/nginx service. + * Run `certbot --agree-tos --standalone --preferred-challenges tls-sni --email "youremail@example.com" --domain yourdomain.example.com` + * For the Apache webserver, copy `/usr/lib/python2.7/dist-packages/certbot_apache/options-ssl-apache.conf` to `/etc/letsencrypt/options-ssl-apache.conf` (paths may vary depending on installation method) + * For Nginx: TODO + * Setup your webserver as described below + * Restart the apache2/nginx service. + +#### Self-signed certificates + +If you don't want to request a certificate from Let's Encrypt, or are unable to (for example, webserver on a LAN, or domain name not registered in the public DNS system), you can generate a self-signed certificate. This certificate will trigger security warnings in web browsers, unless you add it to the browser's SSL store manually. + +* Apache: run `make-ssl-cert generate-default-snakeoil --force-overwrite` +* Nginx: TODO + +-------------------------------------------------------------------------------- + +## Apache + +Here is a basic configuration example for the Apache web server with `mod_php`. + +In `/etc/apache2/sites-available/shaarli.conf`: -### Standard - Keep access and error logs ```apache - + ServerName shaarli.my-domain.org DocumentRoot /absolute/path/to/shaarli/ + # Logging + # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. LogLevel warn ErrorLog /var/log/apache2/shaarli-error.log CustomLog /var/log/apache2/shaarli-access.log combined - -``` -### Paranoid - Redirect HTTP (:80) to HTTPS (:443) -See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla). + # Let's Encrypt SSL configuration (recommended) + SSLEngine on + SSLCertificateFile /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.example.com/privkey.pem + Include /etc/letsencrypt/options-ssl-apache.conf -```apache - - ServerName shaarli.my-domain.org - DocumentRoot /absolute/path/to/shaarli/ + # Self-signed SSL cert configuration + #SSLEngine on + #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem + #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key - SSLEngine on - SSLCertificateFile /absolute/path/to/the/website/certificate.pem - SSLCertificateKeyFile /absolute/path/to/the/website/key.key + # Optional, log PHP errors, useful for debugging + #php_flag log_errors on + #php_flag display_errors on + #php_value error_reporting 2147483647 + #php_value error_log /var/log/apache2/shaarli-php-error.log + #Required for .htaccess support AllowOverride All - Options Indexes FollowSymLinks MultiViews Order allow,deny - allow from all - + Allow from all - LogLevel warn - ErrorLog /var/log/apache2/shaarli-error.log - CustomLog /var/log/apache2/shaarli-access.log combined - - - ServerName shaarli.my-domain.org - Redirect 301 / https://shaarli.my-domain.org + Options Indexes FollowSymLinks MultiViews #TODO is Indexes/Multiviews required? + + # Optional - required for playvideos plugin + #Header set Content-Security-Policy "script-src 'self' 'unsafe-inline' https://www.youtube.com https://s.ytimg.com 'unsafe-eval'" + - LogLevel warn - ErrorLog /var/log/apache2/shaarli-error.log - CustomLog /var/log/apache2/shaarli-access.log combined ``` -### .htaccess +Enable this configuration with `sudo a2ensite shaarli` -Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work. +_Note: 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._ -**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled. - -Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file. +_Note: Apache module `mod_rewrite` must be enabled to use the REST API._ -## LightHttpd ## Nginx -### Foreword -Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources. - -Required packages: -- [nginx](http://nginx.org) -- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager +Here is a basic configuration example for the Nginx web server, using the [php-fpm](http://php-fpm.org) PHP FastCGI Process Manager, and Nginx's [FastCGI](https://en.wikipedia.org/wiki/FastCGI) module. -Official documentation: - -- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) -- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) -- [Pitfalls](http://wiki.nginx.org/Pitfalls) - -Community resources: - -- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla) -- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing) + ### Common setup Once Nginx and PHP-FPM are installed, we need to ensure: @@ -404,3 +395,39 @@ http { } } ``` + +## Proxies +If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set: + +- `X-Forwarded-Proto` +- `X-Forwarded-Host` +- `X-Forwarded-For` + +See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. + + +## See also + + * [Server security](Server-security.md) + +#### Webservers + +- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow) +- [Apache - 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/) +- [Server-side TLS (Apache)](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla) +- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) +- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) +- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls) +- [Nginx PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing) +- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla) +- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) +- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) + +#### PHP + +- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml) +- [PHP: Supported versions](http://php.net/supported-versions.php) +- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_ +- [PHP 7 Changelog](http://php.net/ChangeLog-7.php) +- [PHP 5 Changelog](http://php.net/ChangeLog-5.php) +- [PHP: Bugs](https://bugs.php.net/) diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md deleted file mode 100644 index 2dc442df..00000000 --- a/doc/md/Server-requirements.md +++ /dev/null @@ -1,42 +0,0 @@ -## PHP - -### Release information -- [PHP: Supported versions](http://php.net/supported-versions.php) -- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_ -- [PHP 7 Changelog](http://php.net/ChangeLog-7.php) -- [PHP 5 Changelog](http://php.net/ChangeLog-5.php) -- [PHP: Bugs](https://bugs.php.net/) - -### Supported versions -Version | Status | Shaarli compatibility -:---:|:---:|:---: -7.1 | Supported (v0.9.x) | Yes -7.0 | Supported | Yes -5.6 | Supported | Yes -5.5 | EOL: 2016-07-10 | Yes -5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x) -5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x) - -See also: - -- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml) - -### Dependency management -Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve, -download and install third-party PHP dependencies. - -Library | Required? | Usage ----|:---:|--- -[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files -[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin -[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API - -### Extensions -Extension | Required? | Usage ----|:---:|--- -[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS -[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support -[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing -[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) -[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way -[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster) diff --git a/doc/md/index.md b/doc/md/index.md index 224070cb..21a63d3c 100644 --- a/doc/md/index.md +++ b/doc/md/index.md @@ -1,19 +1,27 @@ # [Shaarli](https://github.com/shaarli/Shaarli/) documentation -Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. +The personal, minimalist, super-fast, database free, bookmarking service. + +Do you want to share the links you discover? +Shaarli is a minimalist link sharing service that you can install on your own server. +It is designed to be personal (single-user), fast and handy. + + -For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md). +Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. +For general information, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md). If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues). + If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new). If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin). -_Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the `doc/html/` directory of your Shaarli installation._ +* [GitHub project page](https://github.com/shaarli/Shaarli) +* [Online documentation](https://shaarli.readthedocs.io/) (this page) +* [Latest Shaarli releases](https://github.com/shaarli/Shaarli/releases) +* [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md) -[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli) -[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues) -[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/) ### Demo @@ -22,6 +30,9 @@ It runs the latest development version of Shaarli and is updated/reset daily. Login: `demo`; Password: `demo` + + + ## Features Shaarli can be used: @@ -42,26 +53,31 @@ Shaarli can be used: - to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...). ### Interface + - minimalist design (simple is beautiful) - FAST - ATOM and RSS feeds - views: - - paginated link list + - paginated link list (with image and video thumbnails) - tag cloud - - picture wall: image and video thumbnails + - picture wall: image and video thumbnails (with lazy loading) - daily: newspaper-like daily digest - daily RSS feed - permalinks for easy reference - links can be public or private +- thumbnail generation for images and video services +- URL cleanup: automatic removal of `?utm_source=...`, `fb=...` - extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage) -### Tag, view and search your links! +### Tag, view and search your links + - add a custom title and description to archived links - add tags to classify and search links - - features tag autocompletion, renaming, merging and deletion + - features tag autocompletion, renaming, merging and deletion - full-text and tag search ### Easy setup + - dead-simple installation: drop the files, open the page - links are stored in a file - compact storage @@ -70,23 +86,19 @@ Shaarli can be used: - import and export links as Netscape bookmarks ### Accessibility -- Firefox bookmarlet to share links in one click + +- bookmarlet to share links in one click - support for mobile browsers -- works with Javascript disabled +- degrades gracefully with Javascript disabled - easy page customization through HTML/CSS/RainTPL ### Security -- bruteforce-proof login form -- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) -and session cookie hijacking - -### Goodies -- thumbnail generation for images and video services: -dailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube... - - lazy-loading with [bLazy](http://dinbror.dk/blazy/) -- [PubSubHubbub](https://code.google.com/p/pubsubhubbub/) protocol support -- URL cleanup: automatic removal of `?utm_source=...`, `fb=...` + - discreet pop-up notification when a new release is available +- bruteforce protection on the login form +- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking + + ### REST API @@ -95,28 +107,30 @@ Easily extensible by any client using the REST API exposed by Shaarli. See the [API documentation](http://shaarli.github.io/api-documentation/). ## About + ### Shaarli community fork + This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/). -The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) -that he would have no time to work on Shaarli in the near future. -The Shaarli community has carried on the work to provide -[many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) -for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) -in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient. +The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) that he would have no time to work on Shaarli in the near future. + +The Shaarli community has carried on the work to provide [many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient. + ### Contributing + If you'd like to help, please: - have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) and [pull requests](https://github.com/shaarli/Shaarli/pulls) - feel free to report bugs (feedback is much appreciated) -- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/wiki) +- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/tree/master/doc/md/) - propose solutions to existing problems - submit pull requests :-) ### License -Shaarli 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. + +Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail of the contributors and licenses for each individual component. A list of contributors is available [here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS). -- cgit v1.2.3 From 6e1df6013e8b448d83c4b7fceb86877c53e81f1c Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Wed, 20 Jun 2018 17:14:30 +0200 Subject: Update version badges and installation instructions Signed-off-by: VirtualTam --- doc/md/Download-and-Installation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md index 20138f49..b82590f2 100644 --- a/doc/md/Download-and-Installation.md +++ b/doc/md/Download-and-Installation.md @@ -25,11 +25,11 @@ Using one of the following methods: In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies. -The current latest released version is `v0.9.6` +The current latest released version is `v0.9.7` ```bash -$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.6/shaarli-v0.9.6-full.zip -$ unzip shaarli-v0.9.6-full.zip +$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.7/shaarli-v0.9.7-full.zip +$ unzip shaarli-v0.9.7-full.zip $ mv Shaarli /path/to/shaarli/ ``` @@ -94,7 +94,7 @@ $ composer install --no-dev --prefer-dist _Use at your own risk!_ Install [Composer](Unit-tests.md#install_composer) to manage Shaarli PHP dependencies, -and [yarn](https://yarnpkg.com/lang/en/docs/install/) +and [yarn](https://yarnpkg.com/lang/en/docs/install/) for front-end dependencies. To get the latest changes from the `master` branch: -- cgit v1.2.3 From de15ed1def225b878274d548733012cf54ac4b57 Mon Sep 17 00:00:00 2001 From: lapineige Date: Mon, 25 Jun 2018 09:28:29 +0200 Subject: Other platform integration: add Yunohost install badge Add a button to install with Yunohost in a one-click way. --- doc/md/Community-&-Related-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md index 7c570acf..715a9022 100644 --- a/doc/md/Community-&-Related-software.md +++ b/doc/md/Community-&-Related-software.md @@ -32,7 +32,7 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal - [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli - [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar - [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle - +- [Shaarli_ynh](https://github.com/YunoHost-Apps/shaarli_ynh) - Shaarli is available as a [Yunohost](https://yunohost.org) app [![Install Shaarli with YunoHost](https://install-app.yunohost.org/install-with-yunohost.png)](https://install-app.yunohost.org/?app=shaarli) ### Mobile Apps - [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension. -- cgit v1.2.3 From 359696dcbb5073be82bb18f7b557b9ba0176d7c9 Mon Sep 17 00:00:00 2001 From: Felix Bartels Date: Mon, 25 Jun 2018 10:05:04 +0200 Subject: add Cloudron to related software --- doc/md/Community-&-Related-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md index 7c570acf..862970d4 100644 --- a/doc/md/Community-&-Related-software.md +++ b/doc/md/Community-&-Related-software.md @@ -32,7 +32,7 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal - [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli - [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar - [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle - +- [Shaarli app for Cloudron](https://git.cloudron.io/cloudron/shaarli-app) - Effortlessly run Shaarli with the help of [Cloudron](https://cloudron.io/) [![Install](https://cloudron.io/img/button.svg)](https://cloudron.io/button.html?app=com.github.shaarli) ### Mobile Apps - [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension. -- cgit v1.2.3 From 87f14312470ca51b936896b41413c96edfe3b18f Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Tue, 26 Jun 2018 22:18:51 +0200 Subject: Fix broken documentation links and list formatting Signed-off-by: VirtualTam --- doc/md/FAQ.md | 4 +++- doc/md/REST-API.md | 5 +++-- doc/md/Sharing-content.md | 26 +++++++++++++------------- doc/md/index.md | 19 ++++++++++++++----- 4 files changed, 33 insertions(+), 21 deletions(-) (limited to 'doc/md') diff --git a/doc/md/FAQ.md b/doc/md/FAQ.md index 77faf117..a2ec7d57 100644 --- a/doc/md/FAQ.md +++ b/doc/md/FAQ.md @@ -22,7 +22,9 @@ With Shaarli: Shaarli stands for _shaaring_ your _links_. ### My Shaarli is broken! -First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements). +First of all, ensure that both the [web server](Server-configuration) and +[Shaarli](Shaarli-configuration) are correctly configured, and that your +installation is [supported](Server-configuration). If everything looks right but the issue(s) remain(s), please: diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index 68a83c00..c016de56 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -3,8 +3,9 @@ See the [REST API documentation](http://shaarli.github.io/api-documentation/) for a list of available endpoints and parameters. -Please ensure that your server meets the [requirements](Server-requirements) -and is properly [configured](Server-configuration): +Please ensure that your server meets the +[requirements](Server-configuration#prerequisites) and is properly +[configured](Server-configuration): - URL rewriting is enabled (see specific Apache and Nginx sections) - the server's timezone is properly defined diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md index faacc1f9..4910ff6c 100644 --- a/doc/md/Sharing-content.md +++ b/doc/md/Sharing-content.md @@ -1,4 +1,4 @@ -Content posted to Shaarli is separated in items called _Shaares_. For each Shaare, +Content posted to Shaarli is separated in items called _Shaares_. For each Shaare, you can customize the following aspects: * URL to link to @@ -13,10 +13,10 @@ you can customize the following aspects: While logged in to your Shaarli, you can add new Shaares in several ways: - * [+Shaare button] - * [Bookmarklet] + * [+Shaare button](#shaare-button) + * [Bookmarklet](#bookmarklet) * [Firefox Share](#firefox-share) - * Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps) + * Third-party [apps and browser addons](Community-&-Related-software.md#mobile-apps) * [REST API](https://shaarli.github.io/api-documentation/) ### +Shaare button @@ -33,14 +33,14 @@ While logged in to your Shaarli, you can add new Shaares in several ways: ### Bookmarklet -The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special -browser bookmark you can use to add new content to your Shaarli. This bookmarklet is +The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special +browser bookmark you can use to add new content to your Shaarli. This bookmarklet is compatible with Firefox, Opera, Chrome and Safari. To set it up: * Access the `Tools` page from the button in the toolbar. * Drag the **`✚Shaare link` button** to your browser's bookmarks bar. -Once this is done, you can shaare any URL you are visiting simply by clicking the +Once this is done, you can shaare any URL you are visiting simply by clicking the bookmarklet in your browser! The same `New Shaare` dialog as above is displayed. | Note | Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunately, there is nothing Shaarli can do about it. \[[1](https://github.com/shaarli/Shaarli/issues/196)]\ \[[2](https://bugzilla.mozilla.org/show_bug.cgi?id=866522)]\ \[[3](https://code.google.com/p/chromium/issues/detail?id=233903)]\ | @@ -59,8 +59,8 @@ Before using Firefox Share, you must first add Shaarli as a sharing provider: - Click the `Tools` button in the top bar - Click the `✚Add to Firefox social` button and accept the activation. -Once this is done, you can share any URL you are visiting by clicking the Firefox -_Share_ button [images/firefoxshare.png](images/firefoxshare.png) +Once this is done, you can share any URL you are visiting by clicking the Firefox +_Share_ button ![images/firefoxshare.png](images/firefoxshare.png) | Note | Firefox Share is no longer available for Firefox 57 and later versions. | |---------|---------| @@ -74,15 +74,15 @@ _Share_ button [images/firefoxshare.png](images/firefoxshare.png) Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button. -Editing a Shaare will not change it's permalink, each permalink always points to the +Editing a Shaare will not change it's permalink, each permalink always points to the latest revision of a Shaare. -------------------------------------------------------------------------------- ## Using shaarli as a blog, notepad, pastebin... -While adding or editing a link, leave the URL field blank to create a text-only -("note") post. This allows you to post any kind of text content, such as blog -articles, private or public notes, snippets... There is no character limit! You can +While adding or editing a link, leave the URL field blank to create a text-only +("note") post. This allows you to post any kind of text content, such as blog +articles, private or public notes, snippets... There is no character limit! You can access your Shaare from its permalink. diff --git a/doc/md/index.md b/doc/md/index.md index 21a63d3c..c18332b4 100644 --- a/doc/md/index.md +++ b/doc/md/index.md @@ -6,7 +6,7 @@ Do you want to share the links you discover? Shaarli is a minimalist link sharing service that you can install on your own server. It is designed to be personal (single-user), fast and handy. - + Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. For general information, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md). @@ -30,7 +30,7 @@ It runs the latest development version of Shaarli and is updated/reset daily. Login: `demo`; Password: `demo` - + ## Features @@ -98,7 +98,7 @@ Shaarli can be used: - bruteforce protection on the login form - protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking - + ### REST API @@ -116,12 +116,17 @@ This is a community fork of the original [Shaarli](https://github.com/sebsauvage The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) that he would have no time to work on Shaarli in the near future. -The Shaarli community has carried on the work to provide [many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient. +The Shaarli community has carried on the work to provide [many +patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for +[bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) +in this repository, and will keep maintaining the project for the foreseeable +future, while keeping Shaarli simple and efficient. ### Contributing If you'd like to help, please: + - have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) and [pull requests](https://github.com/shaarli/Shaarli/pulls) - feel free to report bugs (feedback is much appreciated) @@ -132,5 +137,9 @@ and [pull requests](https://github.com/shaarli/Shaarli/pulls) ### License -Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail of the contributors and licenses for each individual component. A list of contributors is available [here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS). +Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See +[COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail +of the contributors and licenses for each individual component. A list of +contributors is available +[here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS). -- cgit v1.2.3 From 186d9eaa5737a7631df89b40be75c55e5b976e48 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Thu, 5 Jul 2018 18:15:17 +0200 Subject: Docker: expose a volume for the thumbnail cache Signed-off-by: VirtualTam --- doc/md/docker/shaarli-images.md | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) (limited to 'doc/md') diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md index e6fbff64..5948949a 100644 --- a/doc/md/docker/shaarli-images.md +++ b/doc/md/docker/shaarli-images.md @@ -32,9 +32,10 @@ build`](https://docs.docker.com/engine/reference/commandline/build/) on an `arm32v7` machine or using an emulator such as [qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/). -### Download from DockerHub -```bash +### Download from Docker Hub +```shell $ docker pull shaarli/shaarli + latest: Pulling from shaarli/shaarli 32716d9fcddb: Pull complete 84899d045435: Pull complete @@ -52,7 +53,7 @@ Status: Downloaded newer image for shaarli/shaarli:latest ``` ### Create and start a new container from the image -```bash +```shell # map the host's :8000 port to the container's :80 port $ docker create -p 8000:80 shaarli/shaarli d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 @@ -68,7 +69,7 @@ d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds ``` ### Stop and destroy a container -```bash +```shell $ docker stop backstabbing_galileo # those docker guys are really rude to physicists! backstabbing_galileo @@ -90,12 +91,34 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS ``` ### Automatic builds +Docker users can start a personal instance from an +[autobuild image](https://hub.docker.com/r/shaarli/shaarli/). +For example to start a temporary Shaarli at ``localhost:8000``, and keep session +data (config, storage): -Docker users can start a personal instance from an [autobuild image](https://hub.docker.com/r/shaarli/shaarli/). For example to start a temporary Shaarli at ``localhost:8000``, and keep session data (config, storage): -``` +```shell MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P) docker run -ti --rm \ -p 8000:80 \ -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \ shaarli/shaarli ``` + +### Volumes and data persistence +Data can be persisted by [using volumes](https://docs.docker.com/storage/volumes/). +Volumes allow to keep your data when renewing and/or updating container images: + +```shell +# Create data volumes +$ docker volume create shaarli-data +$ docker volume create shaarli-cache + +# Create and start a Shaarli container using these volumes to persist data +$ docker create \ + --name shaarli \ + -v shaarli-cache:/var/www/shaarli/cache \ + -v shaarli-data:/var/www/shaarli/data \ + -p 8000:80 \ + shaarli/shaarli:master +$ docker start shaarli +``` -- cgit v1.2.3 From 8b5b7dcc831a0ff1c660a0c0bca5d3cec376a5fc Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sat, 31 Mar 2018 12:39:43 +0200 Subject: Add Link structure page to the documentation --- doc/md/Link-structure.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 doc/md/Link-structure.md (limited to 'doc/md') diff --git a/doc/md/Link-structure.md b/doc/md/Link-structure.md new file mode 100644 index 00000000..0a2d0f88 --- /dev/null +++ b/doc/md/Link-structure.md @@ -0,0 +1,18 @@ +## Link structure + +Every link available through the `LinkDB` object is represented as an array +containing the following fields: + + * `id` (integer): Unique identifier. + * `title` (string): Title of the link. + * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). + Can be absolute or relative for Notes. + * `real_url` (string): Real destination URL, can be redirected, encoded, etc. + * `shorturl` (string): Permalink small hash. + * `description` (string): Link text description. + * `private` (boolean): whether the link is private or not. + * `tags` (string): all link tags separated by a single space + * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any. + * `created` (DateTime): link creation date time. + * `updated` (DateTime): last modification date time. + \ No newline at end of file -- cgit v1.2.3 From 787faa42f3a2bcbf83a7853f23f3667a6febf9da Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 6 Apr 2018 18:21:47 +0200 Subject: Take code review into account Upgrade web-thumbnailer and display thumbs right after download --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index ca82b2ec..e281dc85 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -29,7 +29,7 @@ Extension | Required? | Usage ---|:---:|--- [`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support -[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing +[`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way [`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster) -- cgit v1.2.3 From e7f4a03d24470ecf329d31375bceab2ad98f1a0d Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 5 Jul 2018 21:13:09 +0200 Subject: Include ProxyPreserveHost directive in Apache's proxy doc --- doc/md/docker/reverse-proxy-configuration.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md index 6066140e..d44aa39f 100644 --- a/doc/md/docker/reverse-proxy-configuration.md +++ b/doc/md/docker/reverse-proxy-configuration.md @@ -19,6 +19,8 @@ The following HTTP headers are set by using the `ProxyPass` directive: - `X-Forwarded-Host` - `X-Forwarded-Server` +The original `SERVER_NAME` can be send to the proxied host using the `ProxyPreserveHost` directive. + ```apache ServerName shaarli.domain.tld @@ -37,7 +39,8 @@ The following HTTP headers are set by using the `ProxyPass` directive: CustomLog /var/log/apache2/shaarli-access.log combined RequestHeader set X-Forwarded-Proto "https" - + ProxyPreserveHost On + ProxyPass / http://127.0.0.1:10080/ ProxyPassReverse / http://127.0.0.1:10080/ -- cgit v1.2.3 From 5045585f24543efd1ac507e37a854219b1328a9a Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 8 Jul 2018 19:54:48 +0200 Subject: doc: reverse proxy config: proxypreservehost: wording, link to apache documentation, typo --- doc/md/docker/reverse-proxy-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/md') diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md index d44aa39f..e53c9422 100644 --- a/doc/md/docker/reverse-proxy-configuration.md +++ b/doc/md/docker/reverse-proxy-configuration.md @@ -13,13 +13,13 @@ This guide assumes that: - [mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) - [Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) -The following HTTP headers are set by using the `ProxyPass` directive: +The following HTTP headers are set when the `ProxyPass` directive is set: - `X-Forwarded-For` - `X-Forwarded-Host` - `X-Forwarded-Server` -The original `SERVER_NAME` can be send to the proxied host using the `ProxyPreserveHost` directive. +The original `SERVER_NAME` can be sent to the proxied host by setting the [`ProxyPreserveHost`](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#ProxyPreserveHost) directive to `On`. ```apache -- cgit v1.2.3 From 3028a84c13ba402377b99429b032b0c48bb1a078 Mon Sep 17 00:00:00 2001 From: pips Date: Tue, 10 Jul 2018 00:29:24 +0200 Subject: Upgrade-and-migration.md: typo installation link Install page is not correctly linked --- doc/md/Upgrade-and-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md index 451ca36d..95a07b5d 100644 --- a/doc/md/Upgrade-and-migration.md +++ b/doc/md/Upgrade-and-migration.md @@ -27,7 +27,7 @@ As all user data is kept under `data`, this is the only directory you need to wo - backup the `data` directory - install or update Shaarli: - - fresh installation - see [Download and installation](Download-and-installation) + - fresh installation - see [Download and Installation](Download-and-Installation) - update - see the following sections - check or restore the `data` directory -- cgit v1.2.3 From f39b1242a8bf43441b35a5e4a530b0ec7058dca3 Mon Sep 17 00:00:00 2001 From: pips Date: Tue, 10 Jul 2018 00:38:59 +0200 Subject: Upgrade-and-migration.md: install link typo second one --- doc/md/Upgrade-and-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md index 95a07b5d..d5682a34 100644 --- a/doc/md/Upgrade-and-migration.md +++ b/doc/md/Upgrade-and-migration.md @@ -35,7 +35,7 @@ As all user data is kept under `data`, this is the only directory you need to wo All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page. -We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation) for `git` complete instructions. +We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and Installation](Download-and-Installation) for `git` complete instructions. Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! -- cgit v1.2.3 From 1cafacfedd41ebd7bbf442a24a81b33cc24b1838 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sun, 1 Jul 2018 12:27:55 +0200 Subject: Docs: rename 'How-to' section to 'Guides' Signed-off-by: VirtualTam --- doc/md/Backup,-restore,-import-and-export.md | 64 --------------------------- doc/md/Various-hacks.md | 33 -------------- doc/md/guides/backup-restore-import-export.md | 64 +++++++++++++++++++++++++++ doc/md/guides/various-hacks.md | 33 ++++++++++++++ 4 files changed, 97 insertions(+), 97 deletions(-) delete mode 100644 doc/md/Backup,-restore,-import-and-export.md delete mode 100644 doc/md/Various-hacks.md create mode 100644 doc/md/guides/backup-restore-import-export.md create mode 100644 doc/md/guides/various-hacks.md (limited to 'doc/md') diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/Backup,-restore,-import-and-export.md deleted file mode 100644 index bb790074..00000000 --- a/doc/md/Backup,-restore,-import-and-export.md +++ /dev/null @@ -1,64 +0,0 @@ -## Backup and restore the datastore file - -Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place. - -Example command: -```bash -rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php -``` - -## Export links as... - -To export links as an HTML file, under _Tools > Export_, choose: - -- _Export all_ to export both public and private links -- _Export public_ to export public links only -- _Export private_ to export private links only - -Restore by using the `Import` feature. - -- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool. - -Example command: -```bash -./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all -``` - -## Import links from... - -### Diigo - -If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.) - -### Mister Wong - -See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks. - -### SemanticScuttle - -To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase). - -### Scuttle - -Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). - -However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli) -tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer. - -### Refind - -You can use the third-party tool [Derefind](https://github.com/ShawnPConroy/Derefind) to convert refind.com bookmark exports to a format that can be imported into Shaarli. - -## Import Shaarli links to Firefox - -- Export your Shaarli links as described above. - - For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)` -- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`) -- Select `Import and Backup > Import bookmarks in HTML format` - -Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time. - -You may be interested in these Firefox addons to manage links imported from Shaarli - -- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks -- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags diff --git a/doc/md/Various-hacks.md b/doc/md/Various-hacks.md deleted file mode 100644 index 0074ae9f..00000000 --- a/doc/md/Various-hacks.md +++ /dev/null @@ -1,33 +0,0 @@ -### Decode datastore content - -To display the array representing the data saved in `data/datastore.php`, use the following snippet: - -```php -$data = "tZNdb9MwFIb... "; -$out = unserialize(gzinflate(base64_decode($data))); -echo "
"; // Pretty printing is love, pretty printing is life
-print_r($out);
-echo "
"; -exit; -``` -This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation). - -Alternatively, you can transform to JSON format (and pretty-print if you have `jq` installed): -``` -php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/\* (.+) \*/.*!", "$1", file_get_contents("data/datastore.php")))))));' | jq . -``` - -### Changing the timestamp for a shaare - -- Look for `` in `tpl/editlink.tpl` (line 14) -- Replace `type="hidden"` with `type="text"` from this line -- A new date/time field becomes available in the edit/new link dialog. -- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`. - - -### See also - -- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c) -- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012) -- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77) -- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20) diff --git a/doc/md/guides/backup-restore-import-export.md b/doc/md/guides/backup-restore-import-export.md new file mode 100644 index 00000000..bb790074 --- /dev/null +++ b/doc/md/guides/backup-restore-import-export.md @@ -0,0 +1,64 @@ +## Backup and restore the datastore file + +Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place. + +Example command: +```bash +rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +%Y-%m-%d_%H%M).php +``` + +## Export links as... + +To export links as an HTML file, under _Tools > Export_, choose: + +- _Export all_ to export both public and private links +- _Export public_ to export public links only +- _Export private_ to export private links only + +Restore by using the `Import` feature. + +- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool. + +Example command: +```bash +./export-bookmarks.py --url=https://my.server.com/shaarli --username=myusername --password=mysupersecretpassword --download-dir=./ --type=all +``` + +## Import links from... + +### Diigo + +If you export your bookmark from Diigo, make sure you use the Delicious export, not the Netscape export. (Their Netscape export is broken, and they don't seem to be interested in fixing it.) + +### Mister Wong + +See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tweaks. + +### SemanticScuttle + +To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase). + +### Scuttle + +Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). + +However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli) +tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer. + +### Refind + +You can use the third-party tool [Derefind](https://github.com/ShawnPConroy/Derefind) to convert refind.com bookmark exports to a format that can be imported into Shaarli. + +## Import Shaarli links to Firefox + +- Export your Shaarli links as described above. + - For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)` +- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`) +- Select `Import and Backup > Import bookmarks in HTML format` + +Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time. + +You may be interested in these Firefox addons to manage links imported from Shaarli + +- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks +- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags diff --git a/doc/md/guides/various-hacks.md b/doc/md/guides/various-hacks.md new file mode 100644 index 00000000..0074ae9f --- /dev/null +++ b/doc/md/guides/various-hacks.md @@ -0,0 +1,33 @@ +### Decode datastore content + +To display the array representing the data saved in `data/datastore.php`, use the following snippet: + +```php +$data = "tZNdb9MwFIb... "; +$out = unserialize(gzinflate(base64_decode($data))); +echo "
"; // Pretty printing is love, pretty printing is life
+print_r($out);
+echo "
"; +exit; +``` +This will output the internal representation of the datastore, "unobfuscated" (if this can really be considered obfuscation). + +Alternatively, you can transform to JSON format (and pretty-print if you have `jq` installed): +``` +php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/\* (.+) \*/.*!", "$1", file_get_contents("data/datastore.php")))))));' | jq . +``` + +### Changing the timestamp for a shaare + +- Look for `` in `tpl/editlink.tpl` (line 14) +- Replace `type="hidden"` with `type="text"` from this line +- A new date/time field becomes available in the edit/new link dialog. +- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`. + + +### See also + +- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c) +- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012) +- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77) +- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20) -- cgit v1.2.3 From a0c34a49765ecc2559ac51b62966b9785ff3a5a3 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sun, 1 Jul 2018 16:02:35 +0200 Subject: Docs: Add an installation guide for Debian 9 + Docker Signed-off-by: VirtualTam --- doc/md/guides/images/01-create-droplet-distro.jpg | Bin 0 -> 20909 bytes doc/md/guides/images/02-create-droplet-region.jpg | Bin 0 -> 21603 bytes doc/md/guides/images/03-create-droplet-size.jpg | Bin 0 -> 20860 bytes doc/md/guides/images/04-finalize.jpg | Bin 0 -> 28233 bytes doc/md/guides/images/05-droplet.jpg | Bin 0 -> 11977 bytes doc/md/guides/images/06-domain.jpg | Bin 0 -> 4499 bytes doc/md/guides/images/07-installation.jpg | Bin 0 -> 42832 bytes .../install-shaarli-with-debian9-and-docker.md | 257 +++++++++++++++++++++ 8 files changed, 257 insertions(+) create mode 100644 doc/md/guides/images/01-create-droplet-distro.jpg create mode 100644 doc/md/guides/images/02-create-droplet-region.jpg create mode 100644 doc/md/guides/images/03-create-droplet-size.jpg create mode 100644 doc/md/guides/images/04-finalize.jpg create mode 100644 doc/md/guides/images/05-droplet.jpg create mode 100644 doc/md/guides/images/06-domain.jpg create mode 100644 doc/md/guides/images/07-installation.jpg create mode 100644 doc/md/guides/install-shaarli-with-debian9-and-docker.md (limited to 'doc/md') diff --git a/doc/md/guides/images/01-create-droplet-distro.jpg b/doc/md/guides/images/01-create-droplet-distro.jpg new file mode 100644 index 00000000..63682ba8 Binary files /dev/null and b/doc/md/guides/images/01-create-droplet-distro.jpg differ diff --git a/doc/md/guides/images/02-create-droplet-region.jpg b/doc/md/guides/images/02-create-droplet-region.jpg new file mode 100644 index 00000000..135a78be Binary files /dev/null and b/doc/md/guides/images/02-create-droplet-region.jpg differ diff --git a/doc/md/guides/images/03-create-droplet-size.jpg b/doc/md/guides/images/03-create-droplet-size.jpg new file mode 100644 index 00000000..aa5b2fd2 Binary files /dev/null and b/doc/md/guides/images/03-create-droplet-size.jpg differ diff --git a/doc/md/guides/images/04-finalize.jpg b/doc/md/guides/images/04-finalize.jpg new file mode 100644 index 00000000..68ec0dc5 Binary files /dev/null and b/doc/md/guides/images/04-finalize.jpg differ diff --git a/doc/md/guides/images/05-droplet.jpg b/doc/md/guides/images/05-droplet.jpg new file mode 100644 index 00000000..44e93a1e Binary files /dev/null and b/doc/md/guides/images/05-droplet.jpg differ diff --git a/doc/md/guides/images/06-domain.jpg b/doc/md/guides/images/06-domain.jpg new file mode 100644 index 00000000..5827dd93 Binary files /dev/null and b/doc/md/guides/images/06-domain.jpg differ diff --git a/doc/md/guides/images/07-installation.jpg b/doc/md/guides/images/07-installation.jpg new file mode 100644 index 00000000..42cc9f10 Binary files /dev/null and b/doc/md/guides/images/07-installation.jpg differ diff --git a/doc/md/guides/install-shaarli-with-debian9-and-docker.md b/doc/md/guides/install-shaarli-with-debian9-and-docker.md new file mode 100644 index 00000000..f1b26d47 --- /dev/null +++ b/doc/md/guides/install-shaarli-with-debian9-and-docker.md @@ -0,0 +1,257 @@ +_Last updated on 2018-07-01._ + +## Goals +- Getting a Virtual Private Server (VPS) +- Running Shaarli: + - as a Docker container, + - using the Træfik reverse proxy, + - securized with TLS certificates from Let's Encrypt. + + +The following components and tools will be used: + +- [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in + server environments; +- [Docker](https://docs.docker.com/engine/docker-overview/), an open platform + for developing, shipping, and running applications; +- [Docker Compose](https://docs.docker.com/compose/), a tool for defining and + running multi-container Docker applications. + + +More information can be found in the [Resources](#resources) section at the +bottom of the guide. + +## Getting a Virtual Private Server +For this guide, I went for the smallest VPS available from DigitalOcean, +a Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD storage, which costs +$5/month ($0.007/hour): + +- [Droplets Overview](https://www.digitalocean.com/docs/droplets/overview/) +- [Pricing](https://www.digitalocean.com/pricing/) +- [How to Create a Droplet from the DigitalOcean Control Panel](https://www.digitalocean.com/docs/droplets/how-to/create/) +- [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/) +- [Initial Server Setup with Debian 8](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8) (also applies to Debian 9) +- [An Introduction to Securing your Linux VPS](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps) + +### Creating a Droplet +Select `Debian 9` as the Droplet distribution: + +Droplet distribution + +Choose a region that is geographically close to you: + +Droplet region + +Choose a Droplet size that corresponds to your usage and budget: + +Droplet size + +Finalize the Droplet creation: + +Droplet finalization + +Droplet information is displayed on the Control Panel: + +Droplet summary + +Once your VPS has been created, you will receive an e-mail with connection +instructions. + +## Obtaining a domain name +After creating your VPS, it will be reachable using its IP address; some hosting +providers also create a DNS record, e.g. `ns4853142.ip-01-47-127.eu`. + +A domain name (DNS record) is required to obtain a certificate and setup HTTPS +(HTTP with TLS encryption). + +Domain names can be obtained from registrars through hosting providers such as +[Gandi](https://www.gandi.net/en/domain). + +Once you have your own domain, you need to create a new DNS record that points +to your VPS' IP address: + +Domain configuration + +## Host setup +Now's the time to connect to your freshly created VPS! + +```shell +$ ssh root@188.166.85.8 + +Linux stretch-shaarli-02 4.9.0-6-amd64 #1 SMP Debian 4.9.88-1+deb9u1 (2018-05-07) x86_64 + +The programs included with the Debian GNU/Linux system are free software; +the exact distribution terms for each program are described in the +individual files in /usr/share/doc/*/copyright. + +Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent +permitted by applicable law. +Last login: Sun Jul 1 11:20:18 2018 from + +root@stretch-shaarli-02:~$ +``` + +### Updating the system +```shell +root@stretch-shaarli-02:~$ apt update && apt upgrade -y +``` + +### Setting up Docker +_The following instructions are from the +[Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/) +guide._ + +Install package dependencies: + +```shell +root@stretch-shaarli-02:~$ apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common +``` + +Add Docker's package repository GPG key: + +```shell +root@stretch-shaarli-02:~$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - +``` + +Add Docker's package repository: + +```shell +root@stretch-shaarli-02:~$ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian stretch stable" +``` + +Update package lists and install Docker: + +```shell +root@stretch-shaarli-02:~$ apt update && apt install -y docker-ce +``` + +Verify Docker is properly configured by running the `hello-world` image: + +```shell +root@stretch-shaarli-02:~$ docker run hello-world +``` + +### Setting up Docker Compose +_The following instructions are from the +[Install Docker Compose](https://docs.docker.com/compose/install/) +guide._ + +Download the current version from the release page: + +```shell +root@stretch-shaarli-02:~$ curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose +root@stretch-shaarli-02:~$ chmod +x /usr/local/bin/docker-compose +``` + +## Running Shaarli +Shaarli comes with a configuration file for Docker Compose, that will setup: + +- a local Docker network +- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Shaarli data +- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Træfik TLS configuration and certificates +- a [Shaarli](https://hub.docker.com/r/shaarli/shaarli/) instance +- a [Træfik](https://hub.docker.com/_/traefik/) instance + +[Træfik](https://docs.traefik.io/) is a modern HTTP reverse proxy, with native +support for Docker and [Let's Encrypt](https://letsencrypt.org/). + +### Compose configuration +Create a new directory to store the configuration: + +```shell +root@stretch-shaarli-02:~$ mkdir shaarli && cd shaarli +root@stretch-shaarli-02:~/shaarli$ +``` + +Download the current version of Shaarli's `docker-compose.yml`: + +```shell +root@stretch-shaarli-02:~/shaarli$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml +``` + +Create the `.env` file and fill in your VPS and domain information (replace +`` and `` with your actual information): + +```shell +root@stretch-shaarli-02:~/shaarli$ vim .env +``` + +```shell +SHAARLI_VIRTUAL_HOST= +SHAARLI_LETSENCRYPT_EMAIL= +``` + +### Pull the Docker images +```shell +root@stretch-shaarli-02:~/shaarli$ docker-compose pull +Pulling shaarli ... done +Pulling traefik ... done +``` + +### Run! +```shell +root@stretch-shaarli-02:~/shaarli$ docker-compose up -d +Creating network "shaarli_http-proxy" with the default driver +Creating volume "shaarli_traefik-acme" with default driver +Creating volume "shaarli_shaarli-data" with default driver +Creating shaarli_shaarli_1 ... done +Creating shaarli_traefik_1 ... done +``` + +## Conclusion +Congratulations! Your Shaarli instance should be up and running, and available +at `https://`. + +Shaarli installation page + +## Resources +### Related Shaarli documentation +- [Docker 101](../docker/docker-101.md) +- [Shaarli images](../docker/shaarli-images.md) + +### Hosting providers +- [DigitalOcean](https://www.digitalocean.com/) +- [Gandi](https://www.gandi.net/en) +- [OVH](https://www.ovh.co.uk/) +- [RackSpace](https://www.rackspace.com/) +- etc. + +### Domain Names and Registrars +- [Introduction to the Domain Name System (DNS)](https://opensource.com/article/17/4/introduction-domain-name-system-dns) +- [ICANN](https://www.icann.org/) +- [Domain name registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) +- [OVH Domain Registration](https://www.ovh.co.uk/domains/) +- [Gandi Domain Registration](https://www.gandi.net/en/domain) + +### HTTPS and Security +- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) +- [Let's Encrypt](https://letsencrypt.org/) + +### Docker +- [Docker Overview](https://docs.docker.com/engine/docker-overview/) +- [Docker Documentation](https://docs.docker.com/) +- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/) +- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) +- [Volumes](https://docs.docker.com/storage/volumes/) +- [Install Docker Compose](https://docs.docker.com/compose/install/) +- [docker-compose logs](https://docs.docker.com/compose/reference/logs/) + +### Træfik +- [Getting Started](https://docs.traefik.io/) +- [Docker backend](https://docs.traefik.io/configuration/backends/docker/) +- [Let's Encrypt and Docker](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/) +- [traefik](https://hub.docker.com/_/traefik/) Docker image -- cgit v1.2.3 From 40f0ff2236a92e2f2fb1631d1ffe62c56d5425ed Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Tue, 17 Jul 2018 13:53:53 +0200 Subject: Documentation - REST API - Mention dev.debug mode --- doc/md/REST-API.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'doc/md') diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index c016de56..11bd1cd2 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -152,3 +152,22 @@ See the reference API client: - [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs - [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github + +## Troubleshooting + +### Debug mode + +> This should never be used in a production environment. + +For security reasons, authentication issues will always return an `HTTP 401` error code without any detail. + +It is possible to enable the debug mode in `config.json.php` +to get the actual error message in the HTTP response body with: + +```json +{ + "dev": { + "debug": true + } +} +``` -- cgit v1.2.3 From b817fb0d95f576a33d6582aa6e9b51f85e0ef345 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 30 Aug 2018 20:37:52 +0200 Subject: documentation: refactor documentation homepage - simplify/organize feature list and contributing section - move bug reporting/contact information to Contributing section - unclutter Ref https://github.com/shaarli/Shaarli/issues/1148#issuecomment-397871451 and https://github.com/shaarli/Shaarli/issues/598 --- doc/md/index.md | 120 +++++++++++++++++++++++--------------------------------- 1 file changed, 48 insertions(+), 72 deletions(-) (limited to 'doc/md') diff --git a/doc/md/index.md b/doc/md/index.md index c18332b4..725d33ac 100644 --- a/doc/md/index.md +++ b/doc/md/index.md @@ -1,25 +1,19 @@ -# [Shaarli](https://github.com/shaarli/Shaarli/) documentation +# Shaarli The personal, minimalist, super-fast, database free, bookmarking service. Do you want to share the links you discover? -Shaarli is a minimalist link sharing service that you can install on your own server. +Shaarli is a minimalist bookmark manager and link sharing service that you can install on your own server. It is designed to be personal (single-user), fast and handy. -Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. -For general information, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md). +Visit the pages in the sidebar to find information on how to setup, use, configure, tweak and troubleshoot Shaarli. -If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues). - -If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new). - -If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin). * [GitHub project page](https://github.com/shaarli/Shaarli) -* [Online documentation](https://shaarli.readthedocs.io/) (this page) -* [Latest Shaarli releases](https://github.com/shaarli/Shaarli/releases) +* [Online documentation](https://shaarli.readthedocs.io/) +* [Latest releases](https://github.com/shaarli/Shaarli/releases) * [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md) @@ -30,87 +24,70 @@ It runs the latest development version of Shaarli and is updated/reset daily. Login: `demo`; Password: `demo` - - - ## Features Shaarli can be used: -- to share, comment and save interesting links and news. -- to bookmark useful/frequent personal links (as private links) and share them between computers. -- as a minimal blog/microblog/writing platform (no character limit). -- as a read-it-later list (for example items tagged `readlater`). -- to draft and save articles/posts/ideas. -- to keep code snippets. -- to keep notes and documentation. -- as a shared clipboard/notepad/pastebin between machines. -- as a todo list. -- to store playlists (e.g. with the `music` or `video` tags). +- to share, comment and save interesting links and news +- to bookmark useful/frequent links and share them between computers +- as a minimal blog/microblog/writing platform +- as a read-it-later list +- to draft and save articles/posts/ideas +- to keep notes, documentation and code snippets +- as a shared clipboard/notepad/pastebin between machines +- as a todo list +- to store media playlists - to keep extracts/comments from webpages that may disappear. -- to keep track of ongoing discussions (for example items tagged `discussion`). -- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags. -- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...). +- to keep track of ongoing discussions +- to feed other blogs, aggregators, social networks... using RSS feeds -### Interface +### Edit, view and search your links -- minimalist design (simple is beautiful) +- Minimalist design - FAST -- ATOM and RSS feeds -- views: - - paginated link list (with image and video thumbnails) - - tag cloud - - picture wall: image and video thumbnails (with lazy loading) - - daily: newspaper-like daily digest - - daily RSS feed -- permalinks for easy reference -- links can be public or private -- thumbnail generation for images and video services +- Customizable link titles and descriptions +- Tags to organize your links (features tag autocompletion, renaming, merging and deletion) +- Search by tag or using the full-text search +- Public and private links (visible only to logged-in users) +- Unique permalinks for easy reference +- Paginated link list (with image and video thumbnails) +- Tag cloud and list views +- Picture wall: image and video thumbnails view (with lazy loading) +- ATOM and RSS feeds (can also be filtered using tags or text search) +- Daily: newspaper-like daily digest (and daily RSS feed) - URL cleanup: automatic removal of `?utm_source=...`, `fb=...` -- extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage) - -### Tag, view and search your links - -- add a custom title and description to archived links -- add tags to classify and search links - - features tag autocompletion, renaming, merging and deletion -- full-text and tag search +- Extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage) ### Easy setup -- dead-simple installation: drop the files, open the page -- links are stored in a file - - compact storage - - no database required - - easy backup: simply copy the datastore file -- import and export links as Netscape bookmarks +- Dead-simple installation: drop the files, open the page +- Links are stored in a file (no database required, easy backup: simply copy the datastore file) +- Import and export links as Netscape bookmarks compatible with most Web browsers ### Accessibility -- bookmarlet to share links in one click -- support for mobile browsers -- degrades gracefully with Javascript disabled -- easy page customization through HTML/CSS/RainTPL +- Bookmarklet and other tools to share links in one click +- Support for mobile browsers +- Degrades gracefully with Javascript disabled +- Easy page customization through HTML/CSS/RainTPL ### Security -- discreet pop-up notification when a new release is available -- bruteforce protection on the login form -- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking +- Discreet pop-up notification when a new release is available +- Bruteforce protection on the login form +- Protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking ### REST API -Easily extensible by any client using the REST API exposed by Shaarli. - -See the [API documentation](http://shaarli.github.io/api-documentation/). +- Easily extensible by any client using the REST API exposed by Shaarli ([API documentation](http://shaarli.github.io/api-documentation/)). ## About ### Shaarli community fork -This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli +This friendly fork is maintained by the Shaarli community at This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/). @@ -123,16 +100,15 @@ in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient. -### Contributing +### Contributing and getting help -If you'd like to help, please: +Feedback is very appreciated! -- have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) -and [pull requests](https://github.com/shaarli/Shaarli/pulls) -- feel free to report bugs (feedback is much appreciated) -- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/tree/master/doc/md/) -- propose solutions to existing problems -- submit pull requests :-) +- If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues). +- Have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) and [pull requests](https://github.com/shaarli/Shaarli/pulls) +- If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin). +- If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new). +- Feel free to propose solutions to existing problems, help us improve the documentation and translations, and submit pull requests :-) ### License -- cgit v1.2.3 From 6c44d604a1ee0360a2eaf24b9cac18ca95edcb5f Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 30 Aug 2018 20:03:00 +0200 Subject: doc: server config: basic usage of robots.txt/HTML robots meta-tag/crawler control mechanisms --- doc/md/Server-configuration.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index e281dc85..cf44ecf5 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -397,6 +397,7 @@ http { ``` ## Proxies + If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set: - `X-Forwarded-Proto` @@ -405,6 +406,12 @@ If Shaarli is served behind a proxy (i.e. there is a proxy server between client See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. +## Robots and crawlers + +Shaarli disallows indexing and crawling of your local documentation pages by search engines, using `` HTML tags. +Your Shaarli instance and other pages you host may still be indexed by various robots on the public Internet. +You may want to setup a robots.txt file or other crawler control mechanism on your server. +See [[1]](https://en.wikipedia.org/wiki/Robots_exclusion_standard), [[2]](https://support.google.com/webmasters/answer/6062608?hl=en) and [[3]](https://developers.google.com/search/reference/robots_meta_tag) ## See also -- cgit v1.2.3 From 37bbfb5f65f2d36e00042f233abdc27a7de341e9 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 11 Oct 2018 09:51:14 +0200 Subject: remove firefox share documentation Firefox Share integration has been removed in https://github.com/shaarli/Shaarli/pull/1026 Firefox Share is not available anymore in any ESR/release versions of Firefox --- doc/md/Sharing-content.md | 17 ----------------- 1 file changed, 17 deletions(-) (limited to 'doc/md') diff --git a/doc/md/Sharing-content.md b/doc/md/Sharing-content.md index 4910ff6c..9a16fc62 100644 --- a/doc/md/Sharing-content.md +++ b/doc/md/Sharing-content.md @@ -15,7 +15,6 @@ While logged in to your Shaarli, you can add new Shaares in several ways: * [+Shaare button](#shaare-button) * [Bookmarklet](#bookmarklet) - * [Firefox Share](#firefox-share) * Third-party [apps and browser addons](Community-&-Related-software.md#mobile-apps) * [REST API](https://shaarli.github.io/api-documentation/) @@ -52,22 +51,6 @@ bookmarklet in your browser! The same `New Shaare` dialog as above is displayed. ![](images/bookmarklet.png) -### Firefox Share - -Before using Firefox Share, you must first add Shaarli as a sharing provider: - -- Click the `Tools` button in the top bar -- Click the `✚Add to Firefox social` button and accept the activation. - -Once this is done, you can share any URL you are visiting by clicking the Firefox -_Share_ button ![images/firefoxshare.png](images/firefoxshare.png) - -| Note | Firefox Share is no longer available for Firefox 57 and later versions. | -|---------|---------| - -| Note | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plaintext HTTP connections. | -|---------|---------| - -------------------------------------------------------------------------------- ## Editing Shaares -- cgit v1.2.3 From 6fd287a0a24c1930f4e9eed834a689748d21e69d Mon Sep 17 00:00:00 2001 From: "Alexandre G.-Raymond" Date: Sat, 20 Oct 2018 11:58:49 +0200 Subject: Dead link on dead link detector tool Author's repo moved to Framagit --- doc/md/Community-&-Related-software.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md index 49c20c9c..67fdd70f 100644 --- a/doc/md/Community-&-Related-software.md +++ b/doc/md/Community-&-Related-software.md @@ -51,7 +51,7 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal - [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among French shaarliers: [shaarli.fr](http://shaarli.fr/)) - [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis - [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli -- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming). +- [Self dead link](https://framagit.org/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://framagit.org/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming). - [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html. ## Alternatives to Shaarli -- cgit v1.2.3 From 7062ef4ddd1864f0d5eaff7146de54ea1fd9fe1e Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 9 Dec 2018 14:40:04 +0000 Subject: doc: update PHP compatibility table Ref https://github.com/shaarli/Shaarli/issues/1249 --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index cf44ecf5..78083a46 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -18,7 +18,7 @@ Version | Status | Shaarli compatibility 7.2 | Supported | Yes 7.1 | Supported | Yes 7.0 | Supported | Yes -5.6 | Supported | Yes +5.6 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x) 5.5 | EOL: 2016-07-10 | Yes 5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x) 5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x) -- cgit v1.2.3 From 02c70f624ef314ac5d4692fe9c1b70aa8a3a440d Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 11 Oct 2018 08:16:52 +0000 Subject: doc: fix homepage icon The icon did not display properly on https://shaarli.readthedocs.io/en/master/ --- doc/md/images/icon.png | Bin 0 -> 1266 bytes doc/md/index.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 doc/md/images/icon.png (limited to 'doc/md') diff --git a/doc/md/images/icon.png b/doc/md/images/icon.png new file mode 100644 index 00000000..530d7469 Binary files /dev/null and b/doc/md/images/icon.png differ diff --git a/doc/md/index.md b/doc/md/index.md index 725d33ac..220eeec1 100644 --- a/doc/md/index.md +++ b/doc/md/index.md @@ -1,4 +1,4 @@ -# Shaarli +# Shaarli The personal, minimalist, super-fast, database free, bookmarking service. -- cgit v1.2.3