From 4cf3564d28dc8e4d08a3e64f09ad045ffbde97ae Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 25 Sep 2020 13:29:36 +0200 Subject: Add a setting to retrieve bookmark metadata asynchrounously - There is a new standalone script (metadata.js) which requests a new controller to get bookmark metadata and fill the form async - This feature is enabled with the new setting: general.enable_async_metadata (enabled by default) - general.retrieve_description is now enabled by default - A small rotating loader animation has a been added to bookmark inputs when metadata is being retrieved (default template) - Custom JS htmlentities has been removed and mathiasbynens/he library is used instead Fixes #1563 --- doc/md/Shaarli-configuration.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md index 263fb761..dbfc3da9 100644 --- a/doc/md/Shaarli-configuration.md +++ b/doc/md/Shaarli-configuration.md @@ -150,6 +150,7 @@ _These settings should not be edited_ - **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). - **enabled_plugins**: List of enabled plugins. - **default_note_title**: Default title of a new note. +- **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown. - **retrieve_description** (boolean): If set to true, for every new Shaare Shaarli will try to retrieve the description and keywords from the HTML meta tags. - **root_url**: Overrides automatic discovery of Shaarli instance's URL (e.g.) `https://sub.domain.tld/shaarli-folder/`. -- cgit v1.2.3 From 2f87bfdc69052cd64e84b1d2b97a0af14991a385 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Wed, 21 Oct 2020 15:23:30 +0200 Subject: Fix: nginx - add rule to disable url-rewriting for the docs Related to #1603 --- doc/md/Server-configuration.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 8cb39934..4e74d80b 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -325,6 +325,11 @@ server { deny all; } + location ~ /doc/ { + default_type "text/html"; + try_files $uri $uri/ $uri.html =404; + } + location = /favicon.ico { # serve the Shaarli favicon from its custom location alias /var/www/shaarli/images/favicon.ico; -- cgit v1.2.3 From 740b32b520e6b1723512c6f9b78cef6575b1725b Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Tue, 3 Nov 2020 12:38:38 +0100 Subject: Default formatter: add a setting to disable auto-linkification + update documentation + single parameter for both URL and hashtags Fixes #1094 --- doc/md/Shaarli-configuration.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'doc') diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md index dbfc3da9..99084728 100644 --- a/doc/md/Shaarli-configuration.md +++ b/doc/md/Shaarli-configuration.md @@ -164,6 +164,22 @@ _These settings should not be edited_ - **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. - **allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`). +### Formatter + +Single string value. Default available: + + - `default`: supports line breaks, URL and hashtag auto-links. + - `markdown`: supports [Markdown](https://daringfireball.net/projects/markdown/syntax). + - `markdownExtra`: adds [extra](https://michelf.ca/projects/php-markdown/extra/) flavor to Markdown. + +### Formatter Settings + +Additional settings applied to formatters. + +#### default + + - **autolink**: boolean to enable or disable automatic linkification of URL and hashtags. + ### Resources - **data_dir**: Data directory. -- cgit v1.2.3 From b3bd8c3e8d367975980043e772f7cd78b7f96bc6 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 22 Oct 2020 16:21:03 +0200 Subject: Feature: support any tag separator So it allows to have multiple words tags. Breaking change: commas ',' are no longer a default separator. Fixes #594 --- doc/md/Shaarli-configuration.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md index 99084728..b1326cce 100644 --- a/doc/md/Shaarli-configuration.md +++ b/doc/md/Shaarli-configuration.md @@ -74,6 +74,7 @@ Some settings can be configured directly from a web browser by accesing the `Too "timezone": "Europe\/Paris", "title": "My Shaarli", "header_link": "?" + "tags_separator": " " }, "dev": { "debug": false, @@ -153,6 +154,7 @@ _These settings should not be edited_ - **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown. - **retrieve_description** (boolean): If set to true, for every new Shaare Shaarli will try to retrieve the description and keywords from the HTML meta tags. - **root_url**: Overrides automatic discovery of Shaarli instance's URL (e.g.) `https://sub.domain.tld/shaarli-folder/`. +- **tags_separator**: Defines your tags separator (default: whitespace). ### Security -- cgit v1.2.3 From ce901a58289c72bf7f4dc3515a2be70562cd618b Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sat, 7 Nov 2020 14:27:49 +0100 Subject: Reviewed nginx configuration Both in documentation and Docker image. For security purpose, it no longer allow to access static files through the main nginx *location*. Static files are served if their extension matches the whitelist. As a side effect, we no longer need specific restrictions, and therefore it fixes the nginx part of #1608. --- doc/md/Server-configuration.md | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 4e74d80b..5b8aff53 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -296,7 +296,7 @@ server { location / { # default index file when no file URI is requested index index.php; - try_files $uri /index.php$is_args$args; + try_files _ /index.php$is_args$args; } location ~ (index)\.php$ { @@ -309,23 +309,7 @@ server { include fastcgi.conf; } - location ~ \.php$ { - # deny access to all other PHP scripts - # disable this if you host other PHP applications on the same virtualhost - deny all; - } - - location ~ /\. { - # deny access to dotfiles - deny all; - } - - location ~ ~$ { - # deny access to temp editor files, e.g. "script.php~" - deny all; - } - - location ~ /doc/ { + location ~ /doc/html/ { default_type "text/html"; try_files $uri $uri/ $uri.html =404; } @@ -336,13 +320,12 @@ server { } # allow client-side caching of static files - location ~* \.(?:ico|css|js|gif|jpe?g|png)$ { + location ~* \.(?:ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$ { expires max; add_header Cache-Control "public, must-revalidate, proxy-revalidate"; # HTTP 1.0 compatibility add_header Pragma public; } - } ``` -- cgit v1.2.3 From 8a9796014ce6c842095a9d031c8cbf40da761e0f Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sun, 8 Nov 2020 13:13:13 +0100 Subject: Reviewed Apache configuration (in documentation) For security purpose, block access to any static file not matching the list of allowed extensions. It allows us to remove the specific retriction on dotfiles, and fix Apache part of #1608. --- doc/md/Server-configuration.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 4e74d80b..66db8c57 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -193,19 +193,24 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf Require all granted - - # Prevent accessing dotfiles - RedirectMatch 404 ".*" - + # BE CAREFUL: directives order matter! - + + Require all denied + + + + Require all granted + + + # allow client-side caching of static files Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate" - + + # serve the Shaarli favicon from its custom location Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico - ``` -- cgit v1.2.3 From b7c50a58dedc00a6d34793fc3393aaabf808ab94 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Mon, 9 Nov 2020 10:36:13 +0100 Subject: Docker-compose: fix SSL certificate + add parameter for Docker tag Use envvar SHAARLI_VIRTUAL_HOST for Traefik's docker.domain parameter instead of localhost (I'm not sure if did work at some point). Add an environment variable to choose which Docker tag to use instead of using master by default. Fixes #1632 --- doc/md/Docker.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/md/Docker.md b/doc/md/Docker.md index c152fe92..fc406c00 100644 --- a/doc/md/Docker.md +++ b/doc/md/Docker.md @@ -1,3 +1,4 @@ + # Docker [Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications @@ -113,9 +114,11 @@ $ mkdir shaarli && cd shaarli # Download the latest version of Shaarli's docker-compose.yml $ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/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) +# (replace , and with your actual information) $ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env $ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env +# Available Docker tags can be found at https://hub.docker.com/r/shaarli/shaarli/tags +$ echo 'SHAARLI_DOCKER_TAG=latest' >> .env # Pull the Docker images $ docker-compose pull # Run! @@ -224,4 +227,4 @@ $ docker system prune - [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) - [docker run](https://docs.docker.com/engine/reference/commandline/run/) - [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](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/) \ No newline at end of file +- Træfik: [Getting Started](https://docs.traefik.io/), [Docker backend](https://docs.traefik.io/configuration/backends/docker/), [Let's Encrypt](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/) -- cgit v1.2.3 From 2f4df753041088d788d1923692a7d530167a6840 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Mon, 9 Nov 2020 12:17:40 +0100 Subject: Update Static Analysis documentation --- doc/md/dev/Development.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md index 5c085e03..c42e8ffe 100644 --- a/doc/md/dev/Development.md +++ b/doc/md/dev/Development.md @@ -6,7 +6,7 @@ Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/ma - [Unit tests](Unit-tests) -- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). +- 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 @@ -51,12 +51,12 @@ PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/m ## Link structure -Every link available through the `LinkDB` object is represented as an array +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.). + * `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. @@ -66,7 +66,7 @@ containing the following fields: * `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. - + Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`. @@ -163,11 +163,13 @@ See [`.travis.yml`](https://github.com/shaarli/Shaarli/blob/master/.travis.yml). ## Static analysis -Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: +Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), and must follow: - [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 +- [PSR-12](http://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide +These are enforced on pull requests using our Continuous Integration tools. **Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) -- cgit v1.2.3 From 831e974ea5fa93d689e65313f84d0c80999674c3 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 12 Nov 2020 13:16:20 +0100 Subject: Doc: fix missing merge on Release page --- doc/md/dev/Release-Shaarli.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc') diff --git a/doc/md/dev/Release-Shaarli.md b/doc/md/dev/Release-Shaarli.md index 2c772406..d79be9ce 100644 --- a/doc/md/dev/Release-Shaarli.md +++ b/doc/md/dev/Release-Shaarli.md @@ -64,6 +64,14 @@ git pull upstream master # If releasing a new minor version, create a release branch $ git checkout -b v0.x +# Otherwise just use the existing one +$ git checkout v0.x + +# Get the latest changes +$ git merge master + +# Check that everything went fine: +$ make test # Bump shaarli_version.php from dev to 0.x.0, **without the v** $ vim shaarli_version.php -- cgit v1.2.3 From a6e9c08499f9f79dad88cb3ae9eacda0e0c34c96 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Tue, 27 Oct 2020 19:23:45 +0100 Subject: Plugin system: allow plugins to provide custom routes - each route will be prefixed by `/plugin/` - add a new template for plugins rendering - add a live example in the demo_plugin Check out the "Plugin System" documentation for more detail. Related to #143 --- doc/md/dev/Plugin-system.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'doc') diff --git a/doc/md/dev/Plugin-system.md b/doc/md/dev/Plugin-system.md index f09fadc2..79654011 100644 --- a/doc/md/dev/Plugin-system.md +++ b/doc/md/dev/Plugin-system.md @@ -139,6 +139,31 @@ Each file contain two keys: > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. +### Register plugin's routes + +Shaarli lets you register custom Slim routes for your plugin. + +To register a route, the plugin must include a function called `function _register_routes(): array`. + +This method must return an array of routes, each entry must contain the following keys: + + - `method`: HTTP method, `GET/POST/PUT/PATCH/DELETE` + - `route` (path): without prefix, e.g. `/up/{variable}` + It will be later prefixed by `/plugin//`. + - `callable` string, function name or FQN class's method to execute, e.g. `demo_plugin_custom_controller`. + +Callable functions or methods must have `Slim\Http\Request` and `Slim\Http\Response` parameters +and return a `Slim\Http\Response`. We recommend creating a dedicated class and extend either +`ShaarliVisitorController` or `ShaarliAdminController` to use helper functions they provide. + +A dedicated plugin template is available for rendering content: `pluginscontent.html` using `content` placeholder. + +> **Warning**: plugins are not able to use RainTPL template engine for their content due to technical restrictions. +> RainTPL does not allow to register multiple template folders, so all HTML rendering must be done within plugin +> custom controller. + +Check out the `demo_plugin` for a live example: `GET /plugin/demo_plugin/custom`. + ### Understanding relative paths Because Shaarli is a self-hosted tool, an instance can either be installed at the root directory, or under a subfolder. -- cgit v1.2.3 From 151fa1e450740b08ee783e819dd42cf2c48c335c Mon Sep 17 00:00:00 2001 From: leyrer Date: Sat, 26 Dec 2020 13:45:01 +0100 Subject: Typo fix line 76 'Authentication' -> Authorization --- doc/md/REST-API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index 01071d8e..2a36ea29 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -73,7 +73,7 @@ var_dump(getInfo($baseUrl, $secret)); ### Authentication - All requests to Shaarli's API must include a **JWT token** to verify their authenticity. -- This token must be included as an HTTP header called `Authentication: Bearer `. +- This token must be included as an HTTP header called `Authorization: Bearer `. - JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: ``` -- cgit v1.2.3