From: ArthurHoaro Date: Fri, 17 Jan 2020 17:27:42 +0000 (+0100) Subject: Merge pull request #1358 from shaarli/doc-add-screenshots X-Git-Tag: v0.12.0-beta~26 X-Git-Url: https://git.immae.eu/?p=github%2Fshaarli%2FShaarli.git;a=commitdiff_plain;h=ef028857531a6abe2d7180538b8510502ee2a467;hp=424ae4b001815f778e585b4e197220789d515488 Merge pull request #1358 from shaarli/doc-add-screenshots Doc: add screenshots of all pages --- diff --git a/application/Thumbnailer.php b/application/Thumbnailer.php index d5f5ac28..314baf0d 100644 --- a/application/Thumbnailer.php +++ b/application/Thumbnailer.php @@ -27,6 +27,7 @@ class Thumbnailer 'instagram.com', 'pinterest.com', 'pinterest.fr', + 'soundcloud.com', 'tumblr.com', 'deviantart.com', ]; diff --git a/application/feed/FeedBuilder.php b/application/feed/FeedBuilder.php index 7c859474..957c8273 100644 --- a/application/feed/FeedBuilder.php +++ b/application/feed/FeedBuilder.php @@ -157,7 +157,7 @@ class FeedBuilder $permalink = '' . t('Permalink') . ''; } $link['description'] = format_description($link['description'], $pageaddr); - $link['description'] .= PHP_EOL . '
— ' . $permalink; + $link['description'] .= PHP_EOL . PHP_EOL . '
— ' . $permalink; $pubDate = $link['created']; $link['pub_iso_date'] = $this->getIsoDate($pubDate); diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md index c66d1c70..4193c045 100644 --- a/doc/md/Community-&-Related-software.md +++ b/doc/md/Community-&-Related-software.md @@ -12,8 +12,6 @@ See [REST API](REST-API) for a list of official and community clients. - [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown. - [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter. - [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli. -- [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli. -- [twemoji](https://github.com/NerosTie/twemoji) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli (Twemoji version) - [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support - [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli. - [markdown-toolbar](https://github.com/immanuelfodor/shaarli-markdown-toolbar) by [@immanuelfodor](https://github.com/immanuelfodor) - Easily insert markdown syntax into the Description field when editing a link. @@ -35,6 +33,7 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal - [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) - [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) +- [pelican](https://blog.getpelican.com) static blog generator plugin to auto-post articles on a Shaarli instance: [shaarli_poster](https://github.com/getpelican/pelican-plugins/tree/master/shaarli_poster) ### Mobile Apps - [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension. diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md index 4ca6bdc7..f7819d5a 100644 --- a/doc/md/Continuous-integration-tools.md +++ b/doc/md/Continuous-integration-tools.md @@ -27,3 +27,6 @@ After all jobs have finished, Travis returns the results to GitHub: - Green: all tests have passed - Red: some tests failed - Orange: tests are pending + +## Documentation +[mkdocs](https://www.mkdocs.org/) is used to convert markdown documentation to HTML pages. The [public documentation](https://shaarli.readthedocs.io/en/master/) website is rendered and hosted by [readthedocs.org](https://readthedocs.org/). A copy of the documentation is also included in prebuilt [release archives](https://github.com/shaarli/Shaarli/releases) (`doc/html/` path in your Shaarli installation). To generate the HTML documentation locally, install a recent version of Python `setuptools` and run `make doc`. diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 88eed8e6..bd293c37 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -28,12 +28,12 @@ Version | Status | Shaarli compatibility Extension | Required? | Usage ---|:---:|--- [`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS +[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing [`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 | 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) - -------------------------------------------------------------------------------- ### SSL/TLS configuration diff --git a/doc/md/Theming.md b/doc/md/Theming.md index bd400776..eb84e11c 100644 --- a/doc/md/Theming.md +++ b/doc/md/Theming.md @@ -16,8 +16,6 @@ This file allows overriding rules defined in the template CSS files (only add ch **Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli. -See also [Download CSS styles from an OPML list](Download CSS styles from an OPML list) - ## Themes Installation: diff --git a/doc/md/Troubleshooting.md b/doc/md/Troubleshooting.md index 570f6956..01fd9840 100644 --- a/doc/md/Troubleshooting.md +++ b/doc/md/Troubleshooting.md @@ -1,64 +1,5 @@ # Troubleshooting -## Browser - -### Redirection issues (HTTP Referer) - -Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages. - -See: - -- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia) -- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/) -- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/) - -### Firefox HTTP Referer options - -HTTP settings are available by browsing `about:config`, here are the available settings and their values. - -`network.http.sendRefererHeader` - determines when to send the Referer HTTP header - -- `0`: Never send the referring URL - - not recommended, may break some sites -- `1`: Send only on clicked links -- `2` (default): Send for links and images - -`network.http.referer.XOriginPolicy` - Cross-domain origin policy - -- `0` (default): Always send -- `1`: Send if base domains match -- `2`: Send if hosts match - -`network.http.referer.spoofSource` - Referer spoofing (~faking) - -- `false` (default): real referer -- `true`: spoof referer (use target URI as referer) - - known to break some functionality in Shaarli - -`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer - -- `0`: (default): send full URI -- `1`: scheme+host+port+path -- `2`: scheme+host+port - -### Firefox, localhost and redirections - -`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has -been set up to spoof referers, or only accept requests from the same base domain/host, -Shaarli redirections will not work properly. - -To solve this, assign a local domain to your host, e.g. -``` -127.0.0.1 localhost desktop localhost.lan -::1 localhost desktop localhost.lan -``` - -and browse Shaarli at http://localhost.lan/. - -Related threads: -- [What is localhost.localdomain for?](https://bbs.archlinux.org/viewtopic.php?id=156064) -- [Stop returning to the first page after editing a bookmark from another page](https://github.com/shaarli/Shaarli/issues/311) - ## Login ### I forgot my password! @@ -69,12 +10,19 @@ Delete the file `data/config.json.php` and display the page again. You will be a Login form is protected against brute force attacks: 4 failed logins will ban the IP address from login for 30 minutes. Banned IPs can still browse links. -To remove the current IP bans, delete the file `data/ipbans.php` +- To remove the current IP bans, delete the file `data/ipbans.php` +- To list all login attempts, see `data/log.txt` (succesful/failed logins, bans/lifted bans) -### List of all login attempts +## Browser issues -The file `data/log.txt` shows all logins (successful or failed) and bans/lifted bans. -Search for `failed` in this file to look for unauthorized login attempts. +### Redirection issues (HTTP Referer) + +Depending on its configuration and installed plugins, the browser may remove or alter (spoof) [HTTP referers](https://en.wikipedia.org/wiki/HTTP_referer), thus preventing Shaarli from properly redirecting between pages. Referer settings are available by browsing `about:config` and are documented [here](https://wiki.mozilla.org/Security/Referrer). `network.http.referer.spoofSource = true` in particular is known to break some functionality in Shaarli. + +### Firefox, localhost and redirections + +`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, +Shaarli redirections will not work properly. To solve this, assign a local domain to your host, e.g. `localhost.lan` in your [hosts file](https://en.wikipedia.org/wiki/Hosts_(file)) and browse Shaarli at http://localhost.lan/. ## Hosting problems @@ -123,6 +71,11 @@ This can be caused by several things: - You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time. - If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions. +### Old apache versions, Internal Server Error + +If you hosting provider only provides apache 2.2 and no support for `mod_version`, `.htaccess` files may cause 500 errors (Internal Server Error). See [this workaround](https://github.com/shaarli/Shaarli/issues/1196#issuecomment-412271085). + ## 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)). + diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md index 5948949a..14971d54 100644 --- a/doc/md/docker/shaarli-images.md +++ b/doc/md/docker/shaarli-images.md @@ -12,18 +12,12 @@ repository. - `master`: master branch - `stable`: stable branch -The `latest` and `master` images rely on: +The `latest`, `master` and `stable` images rely on: - [Alpine Linux](https://www.alpinelinux.org/) - [PHP7-FPM](http://php-fpm.org/) - [Nginx](http://nginx.org/) -The `stable` image relies on: - -- [Debian 8 Jessie](https://hub.docker.com/_/debian/) -- [PHP5-FPM](http://php-fpm.org/) -- [Nginx](http://nginx.org/) - 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 diff --git a/doc/md/guides/various-hacks.md b/doc/md/guides/various-hacks.md index 0074ae9f..b3aa869d 100644 --- a/doc/md/guides/various-hacks.md +++ b/doc/md/guides/various-hacks.md @@ -28,6 +28,5 @@ php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/ ### 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/plugins/demo_plugin/demo_plugin.php b/plugins/demo_plugin/demo_plugin.php index 71ba7495..8ae1b479 100644 --- a/plugins/demo_plugin/demo_plugin.php +++ b/plugins/demo_plugin/demo_plugin.php @@ -2,8 +2,8 @@ /** * Demo Plugin. * - * This plugin try to cover Shaarli's plugin API entirely. - * Can be used by plugin developper to make their own. + * This plugin tries to completely cover Shaarli's plugin API. + * Can be used by plugin developers to make their own plugin. */ /* @@ -61,7 +61,7 @@ function demo_plugin_init($conf) /** * Hook render_header. - * Executed on every page redering. + * Executed on every page render. * * Template placeholders: * - buttons_toolbar @@ -145,7 +145,7 @@ function hook_demo_plugin_render_header($data) /** * Hook render_includes. - * Executed on every page redering. + * Executed on every page render. * * Template placeholders: * - css_files @@ -169,7 +169,7 @@ function hook_demo_plugin_render_includes($data) /** * Hook render_footer. - * Executed on every page redering. + * Executed on every page render. * * Template placeholders: * - text @@ -186,7 +186,7 @@ function hook_demo_plugin_render_includes($data) */ function hook_demo_plugin_render_footer($data) { - // footer text + // Footer text $data['text'][] = '
'. demo_plugin_t('Shaarli is now enhanced by the awesome demo_plugin.'); // Free elements at the end of the page. @@ -277,7 +277,7 @@ function hook_demo_plugin_render_editlink($data) // Load HTML into a string $html = file_get_contents(PluginManager::$PLUGINS_PATH .'/demo_plugin/field.html'); - // replace value in HTML if it exists in $data + // Replace value in HTML if it exists in $data if (!empty($data['link']['stuff'])) { $html = sprintf($html, $data['link']['stuff']); } else { @@ -324,9 +324,7 @@ function hook_demo_plugin_render_tools($data) */ function hook_demo_plugin_render_picwall($data) { - // plugin_start_zone $data['plugin_start_zone'][] = '
BEFORE
'; - // plugin_end_zone $data['plugin_end_zone'][] = '
AFTER
'; return $data; @@ -348,9 +346,7 @@ function hook_demo_plugin_render_picwall($data) */ function hook_demo_plugin_render_tagcloud($data) { - // plugin_start_zone $data['plugin_start_zone'][] = '
BEFORE
'; - // plugin_end_zone $data['plugin_end_zone'][] = '
AFTER
'; return $data; @@ -372,9 +368,7 @@ function hook_demo_plugin_render_tagcloud($data) */ function hook_demo_plugin_render_daily($data) { - // plugin_start_zone $data['plugin_start_zone'][] = '
BEFORE
'; - // plugin_end_zone $data['plugin_end_zone'][] = '
AFTER
'; @@ -465,7 +459,8 @@ function hook_demo_plugin_render_feed($data) */ function hook_demo_plugin_save_plugin_parameters($data) { - // Here we edit the provided value, but we can use this to generate config files, etc. + // Here we edit the provided value. + // This hook can also be used to generate config files, etc. if (! empty($data['DEMO_PLUGIN_PARAMETER']) && ! endsWith($data['DEMO_PLUGIN_PARAMETER'], '_SUFFIX')) { $data['DEMO_PLUGIN_PARAMETER'] .= '_SUFFIX'; } diff --git a/tpl/default/includes.html b/tpl/default/includes.html index 6c30d1bf..428b8ee2 100644 --- a/tpl/default/includes.html +++ b/tpl/default/includes.html @@ -22,12 +22,12 @@ {$ogDescription=isset($link.description_src) ? $link.description_src : $link.description} - {if="$link.thumbnail"} + {if="!empty($link.thumbnail)"} {/if} {if="!$hide_timestamps || $is_logged_in"} - {if="$link.updated"} + {if="!empty($link.updated)"} {/if} {/if} diff --git a/tpl/vintage/includes.html b/tpl/vintage/includes.html index 2efb6b10..1c4ff79c 100644 --- a/tpl/vintage/includes.html +++ b/tpl/vintage/includes.html @@ -19,12 +19,12 @@ {$ogDescription=isset($link.description_src) ? $link.description_src : $link.description} - {if="$link.thumbnail"} + {if="!empty($link.thumbnail)"} {/if} {if="!$hide_timestamps || $is_logged_in"} - {if="$link.updated"} + {if="!empty($link.updated)"} {/if} {/if} diff --git a/yarn.lock b/yarn.lock index 1aa94f42..96f854c1 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3428,9 +3428,9 @@ lodash.uniq@^4.5.0: integrity sha1-0CJTc662Uq3BvILklFM5qEJ1R3M= lodash@^4.0.0, lodash@^4.17.11, lodash@^4.17.4, lodash@^4.3.0, lodash@~4.17.10: - version "4.17.11" - resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.11.tgz#b39ea6229ef607ecd89e2c8df12536891cac9b8d" - integrity sha512-cQKh8igo5QUhZ7lg38DYWAxMvjSAKG0A8wGSVimP07SIUEK2UO+arSRKbRZWtelMtN5V0Hkwh5ryOto/SshYIg== + version "4.17.15" + resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.15.tgz#b447f6670a0455bbfeedd11392eff330ea097548" + integrity sha512-8xOcRHvCjnocdS5cpwXQXVzmmh5e5+saE2QGoeQmbKmRS6J3VQppPOIt0MnmE+4xlZoumy0GPG0D0MVIQbNA1A== longest@^1.0.1: version "1.0.1" @@ -3631,9 +3631,9 @@ minizlib@^1.1.1: minipass "^2.2.1" mixin-deep@^1.2.0: - version "1.3.1" - resolved "https://registry.yarnpkg.com/mixin-deep/-/mixin-deep-1.3.1.tgz#a49e7268dce1a0d9698e45326c5626df3543d0fe" - integrity sha512-8ZItLHeEgaqEvd5lYBXfm4EZSFCX29Jb9K+lAHhDKzReKBQKj3R+7NOF6tjqYi9t4oI8VUfaWITJQm86wnXGNQ== + version "1.3.2" + resolved "https://registry.yarnpkg.com/mixin-deep/-/mixin-deep-1.3.2.tgz#1120b43dc359a785dce65b55b82e257ccf479566" + integrity sha512-WRoDn//mXBiJ1H40rqa3vH0toePwSsGb45iInWlTySa+Uu4k3tYUSxa2v1KqAiLtvlrSzaExqS1gtk96A9zvEA== dependencies: for-in "^1.0.2" is-extendable "^1.0.1"