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

doc: update external links based on redirects, fix/remove dead links

Browse source 
- checked with python -m sphinx -b linkcheck -c doc doc/md doc/linkcheck
This commit is contained in:
nodiscc 2023-10-04 14:49:06 +02:00
parent e7a2d06a63
commit 00db4f6bcc
No known key found for this signature in database
GPG key ID: 067FC4266A4B6909
10 changed files with 107 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
doc/md/Community-and-related-software.md
View file

@ -19,7 +19,7 @@ See [REST API](REST-API.md) for a list of official and community clients.
- [disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli. - [disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
- [emojione](https://github.com/immanuelfodor/emojione) by [@immanuelfodor](https://github.com/immanuelfodor) - Resurrected fork of the original emojione project - [emojione](https://github.com/immanuelfodor/emojione) by [@immanuelfodor](https://github.com/immanuelfodor) - Resurrected fork of the original emojione project
- [favicons](https://github.com/trailjeep/shaarli-favicons) by [@trailjeep](https://github.com/trailjeep) - Shaarli plugin to add favicon/filetype icons to Shaares. - [favicons](https://github.com/trailjeep/shaarli-favicons) by [@trailjeep](https://github.com/trailjeep) - Shaarli plugin to add favicon/filetype icons to Shaares.
- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support - [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](https://github.com/ericjuden): Adds Google Analytics tracking support
- [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli. - [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
- [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 Shaare. - [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 Shaare.
- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related Shaares based on the number of identical tags. - [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related Shaares based on the number of identical tags.
@ -32,15 +32,9 @@ See [REST API](REST-API.md) for a list of official and community clients.
- [webhooks](https://gitlab.com/flow.gunso/shaarli-webhooks) by [@flow.gunso](https://gitlab.com/flow.gunso) - Shaarli plugin that enables user-defined callback URL, i.e. webhooks, for specific Shaarli events (link saving, deletion...) - [webhooks](https://gitlab.com/flow.gunso/shaarli-webhooks) by [@flow.gunso](https://gitlab.com/flow.gunso) - Shaarli plugin that enables user-defined callback URL, i.e. webhooks, for specific Shaarli events (link saving, deletion...)
### Custom CSS
- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli
- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)
### Themes ### Themes
- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli - [AkibaTech/Shaarli Superhero Theme](https://github.com/MarceauKa/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli - [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme - [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli - [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
@ -48,25 +42,26 @@ See [REST API](REST-API.md) for a list of official and community clients.
- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone - [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone
- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site - [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site
- [xfnw/shaarli-default-dark](https://github.com/xfnw/shaarli-default-dark) - The default theme but nice and dark for your eyeballs - [xfnw/shaarli-default-dark](https://github.com/xfnw/shaarli-default-dark) - The default theme but nice and dark for your eyeballs
- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli (custom CSS)
### Integration with other platforms ### Integration with other platforms
- [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 - [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](https://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 Shaares on the sidebar - [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli Shaares on the sidebar
- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle - [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) - [![](https://img.shields.io/badge/Cloudron-03A9F4?logo=Buffer)](https://cloudron.io/button.html?app=com.github.shaarli) Effortlessly run Shaarli with the help of [Cloudron](https://cloudron.io/) - [Shaarli app for Cloudron](https://www.cloudron.io/button.html?app=com.github.shaarli) - [![](https://img.shields.io/badge/Cloudron-03A9F4?logo=Buffer)](https://www.cloudron.io/button.html?app=com.github.shaarli) Effortlessly run Shaarli with the help of [Cloudron](https://www.cloudron.io/)
- [Shaarli_ynh](https://github.com/YunoHost-Apps/shaarli_ynh) - [![](https://img.shields.io/badge/YunoHost-black?logo=Buffer)](https://install-app.yunohost.org/?app=shaarli) Shaarli is available as a [Yunohost](https://yunohost.org) app - [Shaarli_ynh](https://github.com/YunoHost-Apps/shaarli_ynh) - [![](https://img.shields.io/badge/YunoHost-black?logo=Buffer)](https://install-app.yunohost.org/?app=shaarli) Shaarli is available as a [Yunohost](https://yunohost.org) app
- [shaarli_poster](https://github.com/getpelican/pelican-plugins/tree/master/shaarli_poster) - [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) - [pelican](https://getpelican.com) static blog generator plugin to auto-post articles on a Shaarli instance
- [shaarli .deb package](https://packages.debian.org/search?keywords=shaarli) - for [Debian](https://www.debian.org/) and [Freedombox](https://www.freedombox.org/) - [shaarli .deb package](https://packages.debian.org/search?keywords=shaarli) - for [Debian](https://www.debian.org/) and [Freedombox](https://www.freedombox.org/)
### Mobile apps ### Mobile apps
- [ShaarliOS](https://github.com/mro/ShaarliOS) - [![](https://img.shields.io/badge/App%20Store-black?logo=apple)](https://itunes.apple.com/app/ShaarliOS/id1027441388) Apple iOS share extension. - [ShaarliOS](https://github.com/mro/ShaarliOS) - [![](https://img.shields.io/badge/App%20Store-black?logo=apple)](https://apps.apple.com/app/shaarlios/id1027441388) Apple iOS share extension.
- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - [![](https://img.shields.io/badge/Play%20Store-3EB7C0?logo=Google%20Play)](https://play.google.com/store/apps/details?id=com.dimtion.shaarlier) Android application to simply add Shaares directly into your Shaarli via Sharing. Free software. - [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - [![](https://img.shields.io/badge/Play%20Store-3EB7C0?logo=Google%20Play)](https://play.google.com/store/apps/details?id=com.dimtion.shaarlier) Android application to simply add Shaares directly into your Shaarli via Sharing. Free software.
- [Stakali for Android](https://stakali.toneiv.eu) - [![](https://img.shields.io/badge/Play%20Store-3EB7C0?logo=Google%20Play)](https://play.google.com/store/apps/details?id=eu.toneiv.stakali) Stakali is a personal bookmark manager which synchronizes with Shaarli. Support offline work without instance, sync, browsing within app. Free use of up to 20 results. - [Stakali for Android](https://stakali.toneiv.eu) - [![](https://img.shields.io/badge/Play%20Store-3EB7C0?logo=Google%20Play)](https://play.google.com/store/apps/details?id=eu.toneiv.stakali) Stakali is a personal bookmark manager which synchronizes with Shaarli. Support offline work without instance, sync, browsing within app. Free use of up to 20 results.
- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider. - [Shaarli for Android](https://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider.
### Desktop apps ### Desktop apps
@ -76,10 +71,10 @@ See [REST API](REST-API.md) for a list of official and community clients.
### Browser extensions ### Browser extensions
- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - [![](https://img.shields.io/badge/Firefox%20Add--ons-414141?logo=Firefox)](https://addons.mozilla.org/firefox/addon/shaarli/) toolbar button to share your current tab with Shaarli. - [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - [![](https://img.shields.io/badge/Firefox%20Add--ons-414141?logo=Firefox)](https://addons.mozilla.org/en-US/firefox/addon/shaarli/) 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. [Removed](https://chrome.google.com/webstore/detail/shiny-shaarli/hajdfkmbdmadjmmpkkbbcnllepomekin) from Chrome web store.
- [Add to Shaarli](https://github.com/burgyl/AddToShaarli) - [![](https://img.shields.io/badge/Chrome%20Web%20Store-white?logo=Google%20Chrome)](https://chrome.google.com/webstore/detail/add-to-shaarli/jhfblapoehcfajokolimghdfmeeakbee) lets you add the current tab or a note to your Shaarli instance. - [Add to Shaarli](https://github.com/burgyl/AddToShaarli) - [![](https://img.shields.io/badge/Chrome%20Web%20Store-white?logo=Google%20Chrome)](https://chrome.google.com/webstore/detail/add-to-shaarli/jhfblapoehcfajokolimghdfmeeakbee) lets you add the current tab or a note to your Shaarli instance.
- [WebLinks Ext](https://chrome.google.com/webstore/detail/weblinks-ext/pnejcofgljlklmmjkocipnanfdbaclke) - [![](https://img.shields.io/badge/Chrome%20Web%20Store-white?logo=Google%20Chrome)](https://chrome.google.com/webstore/detail/weblinks-ext/pnejcofgljlklmmjkocipnanfdbaclke) Save, edit and use your Shaarli. Support work offline, sync, trash, etc. Free software. - [WebLinks Ext](https://chrome.google.com/webstore/detail/weblinks-ext/pnejcofgljlklmmjkocipnanfdbaclke) - [![](https://img.shields.io/badge/Chrome%20Web%20Store-white?logo=Google%20Chrome)](https://chrome.google.com/webstore/detail/weblinks-ext/pnejcofgljlklmmjkocipnanfdbaclke) Save, edit and use your Shaarli. Support work offline, sync, trash, etc. Free software.
- [Shaarli Chrome Extension](https://github.com/octplane/Shiny-Shaarli) - toolbar button to share your current tab with Shaarli. (Removed from Chrome web store).
### Server apps ### Server apps
@ -91,25 +86,24 @@ See [REST API](REST-API.md) for a list of official and community clients.
- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis - [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 - [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
- [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). - [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. - [Bookmark Archiver](https://github.com/ArchiveBox/ArchiveBox) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
## Alternatives to Shaarli ## Alternatives to Shaarli
See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing). See [awesome-selfhosted: bookmarks & link sharing](https://awesome-selfhosted.net/tags/bookmarks-and-link-sharing.html).
## Community ## Community
- [Liens en vrac de sebsauvage](http://sebsauvage.net/links/) - the original Shaarli - [Liens en vrac de sebsauvage](https://sebsauvage.net/links/) - the original Shaarli
- [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html) - [A large list of Shaarlis](http://porneia.free.fr/pub/links/ou-est-shaarli.html)
- [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json) - [A list of working Shaarli aggregators](https://raw.githubusercontent.com/Oros42/find_shaarlis/master/annuaires.json)
- [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list) - [A list of some known Shaarlis](https://github.com/Oros42/shaarlis_list)
- [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](http://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_ - [Adieu Delicious, Diigo et StumbleUpon. Salut Shaarli ! - sebsauvage.net](https://sebsauvage.net/rhaa/index.php?2011/09/16/09/29/58-adieu-delicious-diigo-et-stumbleupon-salut-shaarli-) (fr) _16/09/2011 - the original post about Shaarli_
- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas) - [Original ideas/fixme/TODO page](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr) - [Original discussion page](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
- [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history) - [Original revisions history](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
- [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)
### Articles and social media discussions ### Articles and social media discussions
@ -124,4 +118,4 @@ See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/a
It also appears in the following recommendation lists: It also appears in the following recommendation lists:
- [AlternativeTo](https://alternativeto.net/software/shaarli/) - [AlternativeTo](https://alternativeto.net/software/shaarli/)
- [FramaLibre](https://framalibre.org/content/shaarli) - [FramaLibre](https://framalibre.org/content/shaarli)
- [Project Awesome: Selfhosted Bookmarks and Link Sharing](https://project-awesome.org/Kickball/awesome-selfhosted) - [Awesome-Selfhosted - Bookmarks and Link Sharing](https://awesome-selfhosted.net/tags/bookmarks-and-link-sharing.html)

27
doc/md/Docker.md
View file

@ -49,10 +49,10 @@ Shaarli images are available on [GitHub Container Registry](https://github.com/s
These images are built automatically on Github Actions and rely on: These images are built automatically on Github Actions and rely on:
- [Alpine Linux](https://www.alpinelinux.org/) - [Alpine Linux](https://www.alpinelinux.org/)
- [PHP7-FPM](http://php-fpm.org/) - [PHP7-FPM](https://php-fpm.org/)
- [Nginx](http://nginx.org/) - [Nginx](https://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 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://blog.balena.io/building-arm-containers-on-any-x86-machine-even-dockerhub/).
Here is an example of how to run Shaarli latest image using Docker: Here is an example of how to run Shaarli latest image using Docker:
@ -98,7 +98,7 @@ A [Compose file](https://docs.docker.com/compose/compose-file/) is a common form
A `docker-compose.yml` file can be used to run a persistent/autostarted shaarli service using [Docker Compose](https://docs.docker.com/compose/) or in a [Docker stack](https://docs.docker.com/engine/reference/commandline/stack_deploy/). A `docker-compose.yml` file can be used to run a persistent/autostarted shaarli service using [Docker Compose](https://docs.docker.com/compose/) or in a [Docker stack](https://docs.docker.com/engine/reference/commandline/stack_deploy/).
Shaarli provides configuration file for Docker Compose, that will setup a Shaarli instance, a [Træfik](https://containo.us/traefik/) instance (reverse proxy) with [Let's Encrypt](https://letsencrypt.org/) certificates, a Docker network, and volumes for Shaarli data and Træfik TLS configuration and certificates. Shaarli provides configuration file for Docker Compose, that will setup a Shaarli instance, a [Træfik](https://traefik.io/traefik/) instance (reverse proxy) with [Let's Encrypt](https://letsencrypt.org/) certificates, a Docker network, and volumes for Shaarli data and Træfik TLS configuration and certificates.
Download docker-compose from the [release page](https://docs.docker.com/compose/install/): Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
@ -204,27 +204,24 @@ $ docker system prune
## References ## References
- [Docker: using volumes](https://docs.docker.com/storage/volumes/) - [Docker: using volumes](https://docs.docker.com/storage/volumes/)
- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/) - [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
- [Dockerfile reference](https://docs.docker.com/reference/builder/) - [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
- [GitHub Container Registry](https://github.com/features/packages) - [GitHub Container Registry](https://github.com/features/packages)
- [GithHub Packages documentation](https://docs.github.com/en/packages) - [GithHub Packages documentation](https://docs.github.com/en/packages)
- [DockerHub: Teams and organizations](https://docs.docker.com/docker-hub/orgs/), [End of Docker free teams](https://www.docker.com/blog/we-apologize-we-did-a-terrible-job-announcing-the-end-of-docker-free-teams/) - [DockerHub: Teams and organizations](https://docs.docker.com/docker-hub/orgs/), [End of Docker free teams](https://www.docker.com/blog/we-apologize-we-did-a-terrible-job-announcing-the-end-of-docker-free-teams/)
- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/) - [Get Docker CE for Debian](https://docs.docker.com/engine/install/debian/)
- [Install Docker Compose](https://docs.docker.com/compose/install/) - [Install Docker Compose](https://docs.docker.com/compose/install/)
- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/) - [Service management: Nginx in the foreground](https://nginx.org/en/docs/ngx_core_module.html#daemon)
- [Service management: Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon) - [Service management: Run multiple services in a container](https://docs.docker.com/config/containers/multi-service_container/)
- [Service management: Using supervisord](https://docs.docker.com/articles/using_supervisord/)
- [Volumes](https://docs.docker.com/storage/volumes/) - [Volumes](https://docs.docker.com/storage/volumes/)
- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/) - [Where are Docker images stored?](https://blog.thoward37.me/articles/where-are-docker-images-stored/)
- [docker create](https://docs.docker.com/engine/reference/commandline/create/) - [docker create](https://docs.docker.com/engine/reference/commandline/create/)
- [Docker Documentation](https://docs.docker.com/) - [Docker Documentation](https://docs.docker.com/)
- [docker exec](https://docs.docker.com/engine/reference/commandline/exec/) - [docker exec](https://docs.docker.com/engine/reference/commandline/exec/)
- [docker images](https://docs.docker.com/engine/reference/commandline/images/) - [docker images](https://docs.docker.com/engine/reference/commandline/images/)
- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) - [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) - [Docker Overview](https://docs.docker.com/get-started/overview/)
- [Docker Overview](https://docs.docker.com/engine/docker-overview/)
- [docker ps](https://docs.docker.com/engine/reference/commandline/ps/) - [docker ps](https://docs.docker.com/engine/reference/commandline/ps/)
- [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) - [docker pull](https://docs.docker.com/engine/reference/commandline/pull/)
- [docker run](https://docs.docker.com/engine/reference/commandline/run/) - [docker run](https://docs.docker.com/engine/reference/commandline/run/)
- [docker-compose logs](https://docs.docker.com/compose/reference/logs/) - Træfik: [Documentation](https://doc.traefik.io/traefik/), [Docker image](https://hub.docker.com/_/traefik/)
- 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/)

4
doc/md/Installation.md
View file

@ -17,8 +17,8 @@ sudo rsync -avP Shaarli/ /var/www/shaarli.mydomain.org/
These components are required to build Shaarli: These components are required to build Shaarli:
- [Composer](dev/Development.md#install-composer) to manage third-party [PHP dependencies](dev/Development#third-party-libraries). - [Composer](dev/Development.md#install-composer) to manage third-party [PHP dependencies](dev/Development#third-party-libraries).
- [yarn](https://yarnpkg.com/lang/en/docs/install/) to build frontend dependencies. - [yarn](https://classic.yarnpkg.com/en/docs/install/) to build frontend dependencies.
- [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build local HTML documentation. - [python3-virtualenv](https://pypi.org/project/virtualenv/) to build local HTML documentation.
```bash ```bash
# example from a Debian-based build machine # example from a Debian-based build machine

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

@ -2,7 +2,7 @@
## Server requirements ## Server requirements
See the **[REST API documentation](http://shaarli.github.io/api-documentation/)** for a list of available endpoints and parameters. See the **[REST API documentation](https://shaarli.github.io/api-documentation/)** for a list of available endpoints and parameters.
Please ensure that your server meets the requirements and is properly [configured](Server-configuration.md): Please ensure that your server meets the requirements and is properly [configured](Server-configuration.md):
@ -15,12 +15,12 @@ The host where the API client is invoked should also be synchronized with NTP, s
## Clients and examples ## Clients and examples
- **[python-shaarli-client](https://github.com/shaarli/python-shaarli-client)** - the reference API client ([Documentation](http://python-shaarli-client.readthedocs.io/en/latest/)) - **[python-shaarli-client](https://github.com/shaarli/python-shaarli-client)** - the reference API client ([Documentation](https://python-shaarli-client.readthedocs.io/en/latest/))
- [shaarli-client](https://www.npmjs.com/package/shaarli-client) - NodeJs client ([source code](https://github.com/laBecasse/shaarli-client)) by [laBecasse](https://github.com/laBecasse) - [shaarli-client](https://www.npmjs.com/package/shaarli-client) - NodeJs client ([source code](https://github.com/laBecasse/shaarli-client)) by [laBecasse](https://github.com/laBecasse)
- [Android client example with Kotlin](https://gitlab.com/snippets/1665808) by [Braincoke](https://github.com/Braincoke) - [Android client example with Kotlin](https://gitlab.com/-/snippets/1665808) by [Braincoke](https://github.com/Braincoke)
This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library. This example uses the [PHP cURL](https://www.php.net/manual/en/book.curl.php) library.
```php ```php
<?php <?php
@ -99,7 +99,7 @@ ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
##### Payload ##### Payload
Token expiration: To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at) field ([1](https://tools.ietf.org/html/rfc7519#section-4.1.6)). This token will be valid during **9 minutes**. Token expiration: To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at) field ([1](https://datatracker.ietf.org/doc/html/rfc7519)). This token will be valid during **9 minutes**.
```json ```json
{ {
@ -142,7 +142,7 @@ to get the actual error message in the HTTP response body with:
## References ## References
- [jwt.io](https://jwt.io) (including a list of client per language). - [jwt.io](https://jwt.io) (including a list of client per language).
- [RFC - JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) - [RFC - JSON Web Token (JWT)](https://datatracker.ietf.org/doc/html/rfc7519)
- [JSON Web Tokens (JWT) vs Sessions](https://float-middle.com/json-web-tokens-jwt-vs-sessions/), [HackerNews thread](https://news.ycombinator.com/item?id=11929267) - [JSON Web Tokens (JWT) vs Sessions](https://float-middle.com/json-web-tokens-jwt-vs-sessions/), [HackerNews thread](https://news.ycombinator.com/item?id=11929267)

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

@ -10,7 +10,7 @@ You need write access to the Shaarli installation directory - you should have re
Examples in this documentation are given for [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in server environments. Please adapt them to your specific Linux distribution. Examples in this documentation are given for [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in server environments. Please adapt them to your specific Linux distribution.
A $5/month VPS (1 CPU, 1 GiB RAM and 25 GiB SSD) will run any Shaarli installation without problems. Some hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://www.digitalocean.com/docs/droplets/overview/), [2](https://www.digitalocean.com/pricing/), [3](https://www.digitalocean.com/docs/droplets/how-to/create/), [4](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/), [5](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [6](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovh.co.uk/), [RackSpace](https://www.rackspace.com/), etc. A $5/month VPS (1 CPU, 1 GiB RAM and 25 GiB SSD) will run any Shaarli installation without problems. Some hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://docs.digitalocean.com/products/droplets/), [2](https://www.digitalocean.com/pricing/), [3](https://docs.digitalocean.com/products/droplets/how-to/create/), [4](https://docs.digitalocean.com/products/droplets/how-to/add-ssh-keys/), [5](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [6](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovhcloud.com/en-gb/), [RackSpace](https://www.rackspace.com/), etc.
### Network and domain name ### Network and domain name
@ -19,7 +19,7 @@ Try to host the server in a region that is geographically close to your users.
A **domain name** ([DNS record](https://opensource.com/article/17/4/introduction-domain-name-system-dns)) pointing to the server's public IP address is required to obtain a SSL/TLS certificate and setup HTTPS to secure client traffic to your Shaarli instance. A **domain name** ([DNS record](https://opensource.com/article/17/4/introduction-domain-name-system-dns)) pointing to the server's public IP address is required to obtain a SSL/TLS certificate and setup HTTPS to secure client traffic to your Shaarli instance.
You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovh.co.uk/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name)) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior). You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovhcloud.com/en-gb/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name)) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior).
Setup a **firewall** (using `iptables`, [ufw](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-debian-10), [firewalld](https://firewalld.org/) or any frontend of your choice) to deny all incoming traffic except `tcp/80` and `tcp/443`, which are needed to access the web server (and any other posrts you might need, like SSH). If the server is in a private network behind a NAT, ensure these **ports are forwarded** to the server. Setup a **firewall** (using `iptables`, [ufw](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-debian-10), [firewalld](https://firewalld.org/) or any frontend of your choice) to deny all incoming traffic except `tcp/80` and `tcp/443`, which are needed to access the web server (and any other posrts you might need, like SSH). If the server is in a private network behind a NAT, ensure these **ports are forwarded** to the server.
@ -50,26 +50,26 @@ Required PHP extensions:
Extension | Required? | Usage Extension | Required? | Usage
---|:---:|--- ---|:---:|---
[`openssl`](http://php.net/manual/en/book.openssl.php) | required | OpenSSL, HTTPS [`openssl`](https://www.php.net/manual/en/book.openssl.php) | required | OpenSSL, HTTPS
[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing [`php-json`](https://www.php.net/manual/en/book.json.php) | required | configuration parsing
[`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework) [`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework)
[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support [`php-mbstring`](https://www.php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
[`php-ctype`](https://www.php.net/manual/en/book.ctype.php) | required (bundled with most PHP installation) | Type checking [`php-ctype`](https://www.php.net/manual/en/book.ctype.php) | required (bundled with most PHP installation) | Type checking
[`php-iconv`](https://www.php.net/manual/en/book.iconv.php) | required (bundled with most PHP installation) | Character encoding used in translations [`php-iconv`](https://www.php.net/manual/en/book.iconv.php) | required (bundled with most PHP installation) | Character encoding used in translations
[`php-session`](https://www.php.net/manual/en/book.session.php) | required (bundled with most PHP installation) | User session [`php-session`](https://www.php.net/manual/en/book.session.php) | required (bundled with most PHP installation) | User session
[`php-zlib`](https://www.php.net/manual/en/book.zlib.php) | required (bundled with most PHP installation) | Datastore I/O compression [`php-zlib`](https://www.php.net/manual/en/book.zlib.php) | required (bundled with most PHP installation) | Datastore I/O compression
[`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails [`php-gd`](https://www.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-intl`](https://www.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-curl`](https://www.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) [`php-gettext`](https://www.php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
[`php-ldap`](https://www.php.net/manual/en/book.ldap.php) | optional | LDAP login support [`php-ldap`](https://www.php.net/manual/en/book.ldap.php) | optional | LDAP login support
Some [plugins](Plugins.md) may require additional configuration. Some [plugins](Plugins.md) may require additional configuration.
- [PHP: Supported versions](http://php.net/supported-versions.php) - [PHP: Supported versions](https://www.php.net/supported-versions.php)
- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php) - [PHP: Unsupported versions (EOL/End-of-life)](https://www.php.net/eol.php)
- [PHP 7 Changelog](http://php.net/ChangeLog-7.php) - [PHP 7 Changelog](https://www.php.net/ChangeLog-7.php)
- [PHP 5 Changelog](http://php.net/ChangeLog-5.php) - [PHP 5 Changelog](https://www.php.net/ChangeLog-5.php)
- [PHP: Bugs](https://bugs.php.net/) - [PHP: Bugs](https://bugs.php.net/)
@ -112,9 +112,8 @@ On apache `2.4.43+`, you can also delegate LE certificate management to [mod_md]
If you don't want to rely on a certificate authority, or the server can only be accessed from your own network, you can also generate self-signed certificates. Not that this will generate security warnings in web browsers/clients trying to access Shaarli: If you don't want to rely on a certificate authority, or the server can only be accessed from your own network, you can also generate self-signed certificates. Not that this will generate security warnings in web browsers/clients trying to access Shaarli:
- [How To Create a Self-Signed SSL Certificate for Apache](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-on-debian-10) - [How To Create a Self-Signed SSL Certificate for Apache](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-in-debian-10)
- [How To Create a Self-Signed SSL Certificate for Nginx](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-on-debian-10) - [How To Create a Self-Signed SSL Certificate for Nginx](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-on-debian-10)
- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) - [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
@ -236,9 +235,9 @@ sudo systemctl restart apache2
``` ```
- [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) - [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10)
- [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176) - [Apache/PHP - error log per VirtualHost - StackOverflow](https://stackoverflow.com/questions/176/error-log-per-virtual-host)
- [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/) - [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) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) - [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)
- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/) - [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
- [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) - [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
- [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) - [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
@ -337,12 +336,11 @@ sudo systemctl reload nginx
``` ```
- [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) - [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10)
- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) - [Nginx Beginner's guide](https://nginx.org/en/docs/beginners_guide.html)
- [Nginx documentation](https://nginx.org/en/docs/) - [Nginx documentation](https://nginx.org/en/docs/)
- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) - [Nginx ngx_http_fastcgi_module](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls) - [Nginx Pitfalls](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/)
- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/) - [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)
- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx)
## Reverse proxies ## Reverse proxies
@ -406,15 +404,15 @@ Disallow: /
By default Shaarli already disallows indexing of your local copy of the documentation by default, using `<meta name="robots">` HTML tags. Your Shaarli instance may still be indexed by various robots on the public Internet, that do not respect this header or the robots standard. By default Shaarli already disallows indexing of your local copy of the documentation by default, using `<meta name="robots">` HTML tags. Your Shaarli instance may still be indexed by various robots on the public Internet, that do not respect this header or the robots standard.
- [Robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard) - [Robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard)
- [Introduction to robots.txt](https://support.google.com/webmasters/answer/6062608?hl=en) - [Introduction to robots.txt](https://developers.google.com/search/docs/crawling-indexing/robots/intro?hl=en)
- [Robots meta tag, data-nosnippet, and X-Robots-Tag specifications](https://developers.google.com/search/reference/robots_meta_tag) - [Robots meta tag, data-nosnippet, and X-Robots-Tag specifications](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag)
- [About robots.txt](http://www.robotstxt.org) - [About robots.txt](https://www.robotstxt.org)
- [About the robots META tag](https://www.robotstxt.org/meta.html) - [About the robots META tag](https://www.robotstxt.org/meta.html)
## Fail2ban ## Fail2ban
[fail2ban](http://www.fail2ban.org/wiki/index.php/Main_Page) is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts. You need to create a filter to detect shaarli login failures in logs, and a jail configuation to configure the behavior when failed login attempts are detected: [fail2ban](https://github.com/fail2ban/fail2ban) is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts. You need to create a filter to detect shaarli login failures in logs, and a jail configuation to configure the behavior when failed login attempts are detected:
```ini ```ini
# /etc/fail2ban/filter.d/shaarli-auth.conf # /etc/fail2ban/filter.d/shaarli-auth.conf

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

@ -106,7 +106,7 @@ Some settings can be configured directly from a web browser by accesing the `Too
"mode": "common" "mode": "common"
}, },
"plugins": { "plugins": {
"WALLABAG_URL": "http://demo.wallabag.org", "WALLABAG_URL": "https://demo.wallabag.org",
"WALLABAG_VERSION": "1" "WALLABAG_VERSION": "1"
}, },
"translation": { "translation": {
@ -138,7 +138,7 @@ _These settings should not be edited_
- **title**: Shaarli's instance title. - **title**: Shaarli's instance title.
- **header_link**: Link to the homepage. - **header_link**: Link to the homepage.
- **links_per_page**: Number of Shaares displayed per page. - **links_per_page**: Number of Shaares displayed per page.
- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). - **timezone**: See [the list of supported timezones](https://www.php.net/manual/en/timezones.php).
- **enabled_plugins**: List of enabled plugins. - **enabled_plugins**: List of enabled plugins.
- **default_note_title**: Default title of a new note. - **default_note_title**: Default title of a new note.
- **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown. - **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown.

11
doc/md/Troubleshooting.md
View file

@ -94,7 +94,7 @@ If you hosting provider only provides apache 2.2 and no support for `mod_version
### Sessions do not seem to work correctly on your server ### 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)). 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](https://curl.se/rfc/cookie_spec.html)).
### Error 406 "Not acceptable" ### Error 406 "Not acceptable"
@ -144,8 +144,7 @@ Try to delete it and refresh your page while being logged in.
You may be interested in these Firefox addons to manage bookmarks imported from Shaarli You may be interested in these Firefox addons to manage bookmarks imported from Shaarli
- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks - [Bookmark Dupes](https://addons.mozilla.org/en-US/firefox/addon/bookmark-dupes/) - provides an easy way to deduplicate your bookmarks
- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
### Diigo ### Diigo
@ -157,7 +156,7 @@ See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tw
### SemanticScuttle ### 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). To correctly import the tags from a [SemanticScuttle](https://semanticscuttle.sourceforge.net/) HTML export, edit the HTML file before importing and replace all occurences of `tags=` (lowercase) to `TAGS=` (uppercase).
### Scuttle ### Scuttle
@ -177,7 +176,7 @@ You can use the third-party tool [Derefind](https://github.com/ShawnPConroy/Dere
### The bookmarklet doesn't work ### The bookmarklet doesn't work
Some websites may disallow usage of bookmarklets through [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). 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). Some websites may disallow usage of bookmarklets through [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). 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://bugs.chromium.org/p/chromium/issues/detail?id=233903).
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. 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.
@ -206,7 +205,7 @@ sudo systemctl restart apache2
If the solutions above did not help, please: If the solutions above did not help, please:
- Come and ask question on the [Gitter chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)) - Come and ask question on the [Gitter chat](https://app.gitter.im/#/room/#shaarli_Shaarli:gitter.im)
- Search for [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls) - Search for [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
- if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup...) - if you find one that is related to the issue, feel free to comment and provide additional details (host/Shaarli setup...)
- check 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 would like a feature added to Shaarli. - check 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 would like a feature added to Shaarli.

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

@ -164,7 +164,7 @@ $ make translate
If you use translations in gettext mode, reload your web server. 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/): Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install [yarn](https://classic.yarnpkg.com/en/docs/install/):
```bash ```bash
$ make build_frontend $ make build_frontend

70
doc/md/dev/Development.md
View file

@ -1,24 +1,24 @@
# Development # Development
Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/blob/master/CONTRIBUTING.md)
## Third-party libraries ## Third-party libraries
CSS: CSS:
- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - standardize cross-browser rendering - Yahoo UI [CSS Reset](https://clarle.github.io/yui3/yui/docs/cssreset/) - standardize cross-browser rendering
Javascript: Javascript:
- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms - [Awesomeplete](https://projects.verou.me/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 - [bLazy](https://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 - [qr.js](https://github.com/neocotic/qrious) - QR code generation
PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/master/composer.json)): PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/master/composer.json)):
- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP - [RainTPL](https://github.com/feulf/raintpl) - HTML templating for PHP
- [`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) - Import bookmarks from Netscape files - [`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 - [`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 - [`slim/slim`](https://packagist.org/packages/slim/slim) - Handle routes and middleware for the REST API
@ -31,7 +31,7 @@ PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/m
- The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks. - The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
- Directories are protected using `.htaccess` files - Directories are protected using `.htaccess` files
- Forms are protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery): - Forms are protected against [XSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery):
- Forms which act on data (save,delete…) contain a token generated by the server. - Forms which act on data (save,delete…) contain a token generated by the server.
- Any posted form which does not contain a valid token is rejected. - Any posted form which does not contain a valid token is rejected.
- Any token can only be used once. - Any token can only be used once.
@ -160,11 +160,11 @@ See [`.github/workflows/`](https://github.com/shaarli/Shaarli/tree/master/.githu
## Static analysis ## Static analysis
Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), and must follow: Patches should try to stick to the [PHP Standard Recommendations](https://www.php-fig.org/psr/) (PSR), and must follow:
- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard - [PSR-1](https://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
- [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide - [PSR-2](https://www.php-fig.org/psr/psr-2/) - Coding Style Guide
- [PSR-12](http://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide - [PSR-12](https://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide
These are enforced on pull requests using our Continuous Integration tools with [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer). These are enforced on pull requests using our Continuous Integration tools with [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer).
@ -202,7 +202,7 @@ $ make composer_dependencies_dev
### Install and enable Xdebug to generate PHPUnit coverage reports ### Install and enable Xdebug to generate PHPUnit coverage reports
[Xdebug](http://xdebug.org/docs/install) is a PHP extension which provides debugging and profiling capabilities. Install Xdebug: [Xdebug](https://xdebug.org/docs/install) is a PHP extension which provides debugging and profiling capabilities. Install Xdebug:
```bash ```bash
# for Debian-based distros: # for Debian-based distros:
@ -253,7 +253,7 @@ If Xdebug has been installed and activated, two coverage reports will be generat
### Executing specific tests ### Executing specific tests
Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment: Add a [`@group`](https://phpunit.de/manual/6.5/en/appendixes.annotations.html) annotation in a test class or method comment:
```php ```php
/** /**
@ -277,10 +277,10 @@ Unit tests can be run inside [Docker](../Docker.md) containers.
Test Dockerfiles are located under `tests/docker/<distribution>/Dockerfile`, and can be used to build Docker images to run Shaarli test suites under commonLinux environments. Dockerfiles are provided for the following environments: Test Dockerfiles are located under `tests/docker/<distribution>/Dockerfile`, and can be used to build Docker images to run Shaarli test suites under commonLinux environments. Dockerfiles are provided for the following environments:
- [`alpine316`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/alpine36/Dockerfile) - [Alpine Linux 3.16](https://www.alpinelinux.org/downloads/) - [`alpine316`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/alpine316/Dockerfile) - [Alpine Linux 3.16](https://www.alpinelinux.org/downloads/)
- [`debian8`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian8/Dockerfile) - [Debian 8 Jessie](https://www.debian.org/DebianJessie) (oldoldstable) - [`debian8`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian8/Dockerfile) - [Debian 8 Jessie](https://wiki.debian.org/DebianJessie) (oldoldstable)
- [`debian9`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian9/Dockerfile) - [Debian 9 Stretch](https://wiki.debian.org/DebianStretch) (oldstable) - [`debian9`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian9/Dockerfile) - [Debian 9 Stretch](https://wiki.debian.org/DebianStretch) (oldstable)
- [`ubuntu16`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/ubuntu16/Dockerfile) - [Ubuntu 16.04 Xenial Xerus](http://releases.ubuntu.com/16.04/) (old LTS) - [`ubuntu16`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/ubuntu16/Dockerfile) - [Ubuntu 16.04 Xenial Xerus](https://releases.ubuntu.com/16.04/) (old LTS)
Each image provides: Each image provides:
- a base Linux OS - a base Linux OS
@ -313,20 +313,20 @@ docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication, signature and encryption. It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify: [Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication, signature and encryption. It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master Keys](https://www.archlinux.org/master-keys/) - Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master Keys](https://archlinux.org/master-keys/)
- [Version control](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity - [Version control](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust) signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated. > You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust) signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
-- Phil Pennock (author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/) -- Phil Pennock (author of the SKS key server)
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party): [Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html), Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party): [Keysigning party HOWTO](https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html),
### Generate a GPG key ### Generate a GPG key
- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow) - [Generating a GPG key for Git tagging](https://stackoverflow.com/questions/12061645/generating-a-gpg-key-for-git-tagging/16725717#16725717) (StackOverflow)
- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub) - [Generating a GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification) (GitHub)
```bash ```bash
$ gpg --gen-key $ gpg --gen-key
@ -395,7 +395,7 @@ This guide assumes that you have:
### Release notes and `CHANGELOG.md` ### Release notes and `CHANGELOG.md`
GitHub allows drafting the release notes for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`. See http://keepachangelog.com/en/0.3.0/ for changelog formatting. GitHub allows drafting the release notes for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`. See https://keepachangelog.com/en/0.3.0/ for changelog formatting.
`CHANGELOG.md` should contain the same information as the release note draft for the upcoming version. Update it to: `CHANGELOG.md` should contain the same information as the release note draft for the upcoming version. Update it to:
@ -459,7 +459,7 @@ $ git push upstream v0.x
### Create and push a signed tag ### Create and push a signed tag
Git [tags](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases) are used to identify specific revisions with a unique version number that follows [semantic versioning](https://semver.org/) Git [tags](https://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project) are used to identify specific revisions with a unique version number that follows [semantic versioning](https://semver.org/)
```bash ```bash
# update your local copy # update your local copy
@ -750,8 +750,8 @@ Triggered on every page - allows plugins to add content in page headers.
- `buttons_toolbar`: after the list of buttons in the header. - `buttons_toolbar`: after the list of buttons in the header.
- `fields_toolbar`: after search fields in the header. Note: This will only be called in linklist. - `fields_toolbar`: after search fields in the header. Note: This will only be called in linklist.
![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png) ![buttons_toolbar_example](https://i.imgur.com/ssJUOrt.png)
![fields_toolbar_example](http://i.imgur.com/3GMifI2.png) ![fields_toolbar_example](https://i.imgur.com/3GMifI2.png)
#### render_includes #### render_includes
@ -773,7 +773,7 @@ Triggered on every page - allows plugins to add content in page footer and inclu
- `endofpage`: called at the end of the page. - `endofpage`: called at the end of the page.
- `js_files`: called at the end of the page, to include custom JS scripts. Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`. - `js_files`: called at the end of the page, to include custom JS scripts. Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
![text_example](http://i.imgur.com/L5S2YEH.png) ![text_example](https://i.imgur.com/L5S2YEH.png)
#### render_linklist #### render_linklist
@ -789,10 +789,10 @@ Triggered when `linklist` is displayed (list of links, permalink, search, tag fi
- `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content. - `plugin_end_zone`: after displaying the template content.
![action_plugin_example](http://i.imgur.com/Q12PWg0.png) ![action_plugin_example](https://i.imgur.com/Q12PWg0.png)
![link_plugin_example](http://i.imgur.com/3oDPhWx.png) ![link_plugin_example](https://i.imgur.com/3oDPhWx.png)
![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png) ![plugin_start_zone_example](https://i.imgur.com/OVBkGy3.png)
![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png) ![plugin_end_zone_example](https://i.imgur.com/6IoRuop.png)
#### render_editlink #### render_editlink
@ -805,7 +805,7 @@ Triggered when the link edition form is displayed - allows to add fields in the
- Template placeholders: items can be displayed in templates by adding an entry in `$data['<placeholder>']` array. List of placeholders: - Template placeholders: items can be displayed in templates by adding an entry in `$data['<placeholder>']` array. List of placeholders:
- `edit_link_plugin`: after tags field. - `edit_link_plugin`: after tags field.
![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png) ![edit_link_plugin_example](https://i.imgur.com/5u17Ens.png)
#### render_tools #### render_tools
@ -818,7 +818,7 @@ Triggered when the "tools" page is displayed - allows to add content at the end
- Template placeholders: items can be displayed in templates by adding an entry in `$data['<placeholder>']` array. List of placeholders: - Template placeholders: items can be displayed in templates by adding an entry in `$data['<placeholder>']` array. List of placeholders:
- `tools_plugin`: at the end of the page. - `tools_plugin`: at the end of the page.
![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png) ![tools_plugin_example](https://i.imgur.com/Bqhu9oQ.png)
#### render_picwall #### render_picwall
@ -832,7 +832,7 @@ Triggered when picwall is displayed - allows to add content at the top and botto
- `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content. - `plugin_end_zone`: after displaying the template content.
![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png) ![plugin_start_end_zone_example](https://i.imgur.com/tVTQFER.png)
#### render_tagcloud #### render_tagcloud
@ -848,7 +848,7 @@ Triggered when tagcloud is displayed - allows to add content at the top and bott
- For each tag, the following placeholder can be used: - For each tag, the following placeholder can be used:
- `tag_plugin`: after each tag - `tag_plugin`: after each tag
![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png) ![plugin_start_end_zone_example](https://i.imgur.com/vHmyT3a.png)
#### render_taglist #### render_taglist
@ -877,7 +877,7 @@ Triggered when tagcloud is displayed - allows to add content at the top and bott
- `plugin_start_zone`: before displaying the template content. - `plugin_start_zone`: before displaying the template content.
- `plugin_end_zone`: after displaying the template content. - `plugin_end_zone`: after displaying the template content.
![link_plugin_example](http://i.imgur.com/hzhMfSZ.png) ![link_plugin_example](https://i.imgur.com/hzhMfSZ.png)
#### render_feed #### render_feed

4
doc/md/index.md
View file

@ -105,7 +105,7 @@ Shaarli can be used:
## About ## About
This [community fork](https://github.com/shaarli/Shaarli) of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/) (now [unmaintained](https://github.com/sebsauvage/Shaarli/issues/191)) 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. This [community fork](https://github.com/shaarli/Shaarli) of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](https://sebsauvage.net/) (now [unmaintained](https://github.com/sebsauvage/Shaarli/issues/191)) has carried on the work to provide [many patches](https://github.com/sebsauvage/Shaarli/compare/master...shaarli:Shaarli: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 Shaarli instance is still available [here](https://sebsauvage.net/links/) (+25000 shaares!) The original Shaarli instance is still available [here](https://sebsauvage.net/links/) (+25000 shaares!)
@ -119,4 +119,4 @@ See [Support](Troubleshooting.md#support) to get in touch with the Shaarli commu
### License ### 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](https://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).