Merge pull request #2025 from nodiscc/doc-sphinx
replace mkdocs with sphinx/myst-parser for HTML documentation generation, documentation improvements
This commit is contained in:
nodiscc
GitHub
commit
ba21aa60d9
4
.gitattributes
vendored
4
.gitattributes
vendored
|
|
@ -40,6 +40,8 @@ Dockerfile* export-ignore
|
|||
Doxyfile export-ignore
|
||||
Makefile export-ignore
|
||||
node_modules/ export-ignore
|
||||
mkdocs.yml export-ignore
|
||||
doc/conf.py export-ignore
|
||||
doc/requirements.txt export-ignore
|
||||
doc/html/.doctrees/ export-ignore
|
||||
phpunit.xml export-ignore
|
||||
tests/ export-ignore
|
||||
|
|
|
|||
5
.github/workflows/ci.yml
vendored
5
.github/workflows/ci.yml
vendored
|
|
@ -93,11 +93,8 @@ jobs:
|
|||
with:
|
||||
python-version: 3.8
|
||||
|
||||
- name: Install dependencies
|
||||
run: pip install mkdocs
|
||||
|
||||
- name: Build documentation
|
||||
run: mkdocs build --clean
|
||||
run: make htmldoc
|
||||
|
||||
trivy-repo:
|
||||
runs-on: ubuntu-latest
|
||||
|
|
|
|||
|
|
@ -5,11 +5,19 @@
|
|||
# Required
|
||||
version: 2
|
||||
|
||||
# Build documentation with MkDocs
|
||||
mkdocs:
|
||||
configuration: mkdocs.yml
|
||||
# Build documentation in the "docs/" directory with Sphinx
|
||||
sphinx:
|
||||
configuration: doc/conf.py
|
||||
builder: html
|
||||
|
||||
build:
|
||||
os: ubuntu-22.04
|
||||
tools:
|
||||
python: "3.11"
|
||||
commands:
|
||||
- pip install sphinx==7.1.0 furo==2023.7.26 myst-parser sphinx-design
|
||||
- sphinx-build -b html -c doc/ doc/md/ _readthedocs/html/
|
||||
|
||||
# Optionally set the version of Python and requirements required to build your docs
|
||||
# https://github.com/rtfd/readthedocs.org/issues/5250
|
||||
python:
|
||||
version: 3.5
|
||||
install:
|
||||
- requirements: doc/requirements.txt
|
||||
|
|
|
|||
|
|
@ -4,9 +4,8 @@
|
|||
FROM python:3-alpine as docs
|
||||
ADD . /usr/src/app/shaarli
|
||||
RUN cd /usr/src/app/shaarli \
|
||||
&& apk add --no-cache gcc musl-dev \
|
||||
&& pip install --no-cache-dir mkdocs \
|
||||
&& mkdocs build --clean
|
||||
&& apk add --no-cache gcc musl-dev make bash \
|
||||
&& make htmldoc
|
||||
|
||||
# Stage 2:
|
||||
# - Resolve PHP dependencies with Composer
|
||||
|
|
|
|||
6
Makefile
6
Makefile
|
|
@ -159,13 +159,13 @@ generate_authors:
|
|||
phpdoc: clean
|
||||
@docker run --rm -v $(PWD):/data -u `id -u`:`id -g` phpdoc/phpdoc
|
||||
|
||||
### generate HTML documentation from Markdown pages with MkDocs
|
||||
### generate HTML documentation from Markdown pages with Sphinx
|
||||
htmldoc:
|
||||
python3 -m venv venv/
|
||||
bash -c 'source venv/bin/activate; \
|
||||
pip install wheel; \
|
||||
pip install mkdocs; \
|
||||
mkdocs build --clean'
|
||||
pip install sphinx==7.1.0 furo==2023.7.26 myst-parser sphinx-design; \
|
||||
sphinx-build -b html -c doc/ doc/md/ doc/html/'
|
||||
find doc/html/ -type f -exec chmod a-x '{}' \;
|
||||
rm -r venv
|
||||
|
||||
|
|
|
|||
49
doc/conf.py
Normal file
49
doc/conf.py
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
# Configuration file for the Sphinx documentation builder.
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
project = 'shaarli'
|
||||
author = 'shaarli community'
|
||||
version = '0.12.2'
|
||||
release = '0.12.2'
|
||||
copyright = '2011-2023, the shaarli community'
|
||||
language = 'en'
|
||||
html_title = 'Shaarli documentation'
|
||||
html_theme = 'furo'
|
||||
html_show_sphinx = False
|
||||
html_show_search_summary = True
|
||||
html_copy_source = False
|
||||
html_show_copyright = True
|
||||
html_use_opensearch = 'https://shaarli.readthedocs.io/'
|
||||
html_logo = 'md/images/doc-logo.svg'
|
||||
html_favicon = 'md/images/icon.png'
|
||||
extensions = ['myst_parser', 'sphinx_design']
|
||||
source_suffix = ['.md']
|
||||
templates_path = ['_templates']
|
||||
exclude_patterns = []
|
||||
suppress_warnings = ["myst.xref_missing"]
|
||||
|
||||
# myst-parser configuration (https://myst-parser.readthedocs.io/en/latest/configuration.html)
|
||||
myst_enable_extensions = ['fieldlist']
|
||||
myst_html_meta = {
|
||||
"description lang=en": "The personal, minimalist, super fast, database-free bookmarking service",
|
||||
"charset": "UTF-8"
|
||||
}
|
||||
|
||||
# theme configuration (https://pradyunsg.me/furo/customisation/)
|
||||
html_theme_options = {
|
||||
"top_of_page_button": None,
|
||||
# "announcement": "Example announcement!"
|
||||
"source_repository": "https://github.com/shaarli/shaarli",
|
||||
"source_branch": "master",
|
||||
"footer_icons": [
|
||||
{
|
||||
"name": "GitHub",
|
||||
"url": "https://github.com/shaarli/shaarli",
|
||||
"html": """
|
||||
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
|
||||
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
|
||||
</svg>
|
||||
""",
|
||||
"class": "",
|
||||
},
|
||||
]
|
||||
}
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
{% extends "base.html" %}
|
||||
|
||||
{#
|
||||
The entry point for the ReadTheDocs Theme.
|
||||
|
||||
Any theme customisations should override this file to redefine blocks defined in
|
||||
the various templates. The custom theme should only need to define a main.html
|
||||
which `{% extends "base.html" %}` and defines various blocks which will replace
|
||||
the blocks defined in base.html and its included child templates.
|
||||
#}
|
||||
|
||||
{%- block site_meta %}
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
{%- if config.extra_css|length and 'media.readthedocs.org' not in config.extra_css[0] %}
|
||||
<meta name="robots" content="noindex, nofollow">
|
||||
{%- endif %}
|
||||
|
||||
{% if page and page.is_homepage %}<meta name="description" content="{{ config.site_description }}">{% endif %}
|
||||
{% if config.site_author %}<meta name="author" content="{{ config.site_author }}">{% endif %}
|
||||
{%- endblock %}
|
||||
|
|
@ -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.
|
||||
- [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.
|
||||
- [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.
|
||||
- [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.
|
||||
|
|
@ -32,28 +32,36 @@ 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...)
|
||||
|
||||
|
||||
### Third-party themes
|
||||
### Themes
|
||||
|
||||
See [Theming](dev/Theming.md) for a list of community-contributed themes, and an installation guide.
|
||||
- [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
|
||||
- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
|
||||
- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
|
||||
- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
|
||||
- [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
|
||||
- [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
|
||||
|
||||
- [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
|
||||
- [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://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://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://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/)
|
||||
|
||||
|
||||
### Mobile apps
|
||||
|
||||
- [ShaarliOS](https://github.com/mro/ShaarliOS) - [](https://itunes.apple.com/app/ShaarliOS/id1027441388) Apple iOS share extension.
|
||||
- [ShaarliOS](https://github.com/mro/ShaarliOS) - [](https://apps.apple.com/app/shaarlios/id1027441388) Apple iOS share extension.
|
||||
- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - [](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://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
|
||||
|
|
@ -63,10 +71,10 @@ See [Theming](dev/Theming.md) for a list of community-contributed themes, and an
|
|||
|
||||
### Browser extensions
|
||||
|
||||
- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - [](https://addons.mozilla.org/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.
|
||||
- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - [](https://addons.mozilla.org/en-US/firefox/addon/shaarli/) toolbar button to share your current tab with Shaarli.
|
||||
- [Add to Shaarli](https://github.com/burgyl/AddToShaarli) - [](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://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
|
||||
|
|
@ -78,25 +86,24 @@ See [Theming](dev/Theming.md) for a list of community-contributed themes, and an
|
|||
- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
|
||||
- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
|
||||
- [Self dead link](https://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
|
||||
|
||||
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
|
||||
|
||||
- [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 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)
|
||||
- [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_
|
||||
- [Original ideas/fixme/TODO page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
|
||||
- [Original discussion page](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
|
||||
- [Original revisions history](http://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)
|
||||
- [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](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:ideas)
|
||||
- [Original discussion page](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:discussion) (fr)
|
||||
- [Original revisions history](https://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)
|
||||
|
||||
|
||||
### Articles and social media discussions
|
||||
|
|
@ -111,4 +118,4 @@ See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/a
|
|||
It also appears in the following recommendation lists:
|
||||
- [AlternativeTo](https://alternativeto.net/software/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)
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
- [Alpine Linux](https://www.alpinelinux.org/)
|
||||
- [PHP7-FPM](http://php-fpm.org/)
|
||||
- [Nginx](http://nginx.org/)
|
||||
- [PHP7-FPM](https://php-fpm.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:
|
||||
|
||||
|
|
@ -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/).
|
||||
|
||||
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/):
|
||||
|
||||
|
|
@ -204,27 +204,24 @@ $ docker system prune
|
|||
## References
|
||||
|
||||
- [Docker: using volumes](https://docs.docker.com/storage/volumes/)
|
||||
- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
|
||||
- [Dockerfile reference](https://docs.docker.com/reference/builder/)
|
||||
- [Dockerfile best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
|
||||
- [Dockerfile reference](https://docs.docker.com/engine/reference/builder/)
|
||||
- [GitHub Container Registry](https://github.com/features/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/)
|
||||
- [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/)
|
||||
- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
|
||||
- [Service management: Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
|
||||
- [Service management: Using supervisord](https://docs.docker.com/articles/using_supervisord/)
|
||||
- [Service management: Nginx in the foreground](https://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/)
|
||||
- [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 Documentation](https://docs.docker.com/)
|
||||
- [docker exec](https://docs.docker.com/engine/reference/commandline/exec/)
|
||||
- [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 Overview](https://docs.docker.com/engine/docker-overview/)
|
||||
- [Docker Overview](https://docs.docker.com/get-started/overview/)
|
||||
- [docker ps](https://docs.docker.com/engine/reference/commandline/ps/)
|
||||
- [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/)
|
||||
- Træfik: [Documentation](https://doc.traefik.io/traefik/), [Docker image](https://hub.docker.com/_/traefik/)
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ sudo rsync -avP Shaarli/ /var/www/shaarli.mydomain.org/
|
|||
These components are required to build Shaarli:
|
||||
|
||||
- [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.
|
||||
- [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build local HTML documentation.
|
||||
- [yarn](https://classic.yarnpkg.com/en/docs/install/) to build frontend dependencies.
|
||||
- [python3-virtualenv](https://pypi.org/project/virtualenv/) to build local HTML documentation.
|
||||
|
||||
```bash
|
||||
# example from a Debian-based build machine
|
||||
|
|
|
|||
|
|
@ -59,4 +59,4 @@ Usage of each plugin is documented in it's README file:
|
|||
|
||||
### Third party plugins
|
||||
|
||||
See [Community & related software](https://shaarli.readthedocs.io/en/master/Community-and-related-software/)
|
||||
See [Community & related software](Community-and-related-software.md)
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## 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):
|
||||
|
||||
|
|
@ -15,12 +15,12 @@ The host where the API client is invoked should also be synchronized with NTP, s
|
|||
|
||||
## 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)
|
||||
- [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
|
||||
|
|
@ -99,7 +99,7 @@ ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
|
|||
|
||||
##### 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
|
||||
{
|
||||
|
|
@ -142,7 +142,7 @@ to get the actual error message in the HTTP response body with:
|
|||
## References
|
||||
|
||||
- [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)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9
|
|||
## HAProxy
|
||||
|
||||
|
||||
```conf
|
||||
```
|
||||
global
|
||||
[...]
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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
|
||||
|
|
@ -19,19 +19,12 @@ 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.
|
||||
|
||||
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), [fireHOL](https://firehol.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.
|
||||
|
||||
Shaarli makes outbound HTTP/HTTPS connections to websites you bookmark to fetch page information (title, thumbnails), the server must then have access to the Internet as well, and a working DNS resolver.
|
||||
|
||||
|
||||
### Screencast
|
||||
|
||||
Here is a screencast of the installation procedure
|
||||
|
||||
[](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO)
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
### PHP
|
||||
|
|
@ -57,26 +50,26 @@ Required PHP extensions:
|
|||
|
||||
Extension | Required? | Usage
|
||||
---|:---:|---
|
||||
[`openssl`](http://php.net/manual/en/book.openssl.php) | required | OpenSSL, HTTPS
|
||||
[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing
|
||||
[`openssl`](https://www.php.net/manual/en/book.openssl.php) | required | OpenSSL, HTTPS
|
||||
[`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-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-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-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-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)
|
||||
[`php-gd`](https://www.php.net/manual/en/book.image.php) | optional | required to use thumbnails
|
||||
[`php-intl`](https://www.php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
|
||||
[`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`](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
|
||||
|
||||
Some [plugins](Plugins.md) may require additional configuration.
|
||||
|
||||
- [PHP: Supported versions](http://php.net/supported-versions.php)
|
||||
- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php)
|
||||
- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
|
||||
- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
|
||||
- [PHP: Supported versions](https://www.php.net/supported-versions.php)
|
||||
- [PHP: Unsupported versions (EOL/End-of-life)](https://www.php.net/eol.php)
|
||||
- [PHP 7 Changelog](https://www.php.net/ChangeLog-7.php)
|
||||
- [PHP 5 Changelog](https://www.php.net/ChangeLog-5.php)
|
||||
- [PHP: Bugs](https://bugs.php.net/)
|
||||
|
||||
|
||||
|
|
@ -119,16 +112,15 @@ 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:
|
||||
|
||||
- [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 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)
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
## Examples
|
||||
|
||||
The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). In these examples we assume the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`:
|
||||
The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). In these examples we assume that the web server and the `php-fpm` PHP interpreter are running as the same user, and the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`,:
|
||||
|
||||
```bash
|
||||
# create the document root (replace with your own domain name)
|
||||
|
|
@ -141,9 +133,14 @@ You can install Shaarli at the root of your virtualhost, or in a subdirectory as
|
|||
### Apache
|
||||
|
||||
```bash
|
||||
# Install apache + mod_php and PHP modules
|
||||
# Install apache + php-fpm
|
||||
sudo apt update
|
||||
sudo apt install apache2 libapache2-mod-php php-json php-mbstring php-gd php-intl php-curl php-gettext
|
||||
sudo apt install apache2 libapache2-mod-md libapache2-mod-fcgid php8.2-fpm php8.2-mbstring php8.2-gd php8.2-intl php8.2-curl php8.2-gettext php8.2-ldap
|
||||
|
||||
# Enable required modules
|
||||
sudo a2enmod ssl # SSL/TLS certificates https://httpd.apache.org/docs/current/mod/mod_ssl.html
|
||||
sudo a2enmod rewrite # REST API support https://httpd.apache.org/docs/current/mod/mod_rewrite.html
|
||||
sudo a2enmod headers # custom HTTP headers
|
||||
|
||||
# Edit the virtualhost configuration file with your favorite editor (replace the example domain name)
|
||||
sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
|
||||
|
|
@ -154,7 +151,7 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
|
|||
ServerName shaarli.mydomain.org
|
||||
DocumentRoot /var/www/shaarli.mydomain.org/
|
||||
|
||||
# For SSL/TLS certificates acquired with certbot or self-signed certificates
|
||||
# If using certbot or self-signed certificates:
|
||||
# Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests
|
||||
RewriteEngine on
|
||||
RewriteRule ^.well-known/acme-challenge/ - [L]
|
||||
|
|
@ -162,31 +159,25 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
|
|||
RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent]
|
||||
</VirtualHost>
|
||||
|
||||
# SSL/TLS configuration for Let's Encrypt certificates managed with mod_md
|
||||
#MDomain shaarli.mydomain.org
|
||||
#MDCertificateAgreement accepted
|
||||
#MDContactEmail admin@shaarli.mydomain.org
|
||||
#MDPrivateKeys RSA 4096
|
||||
# If using mod_md:
|
||||
MDomain shaarli.mydomain.org
|
||||
MDCertificateAgreement accepted
|
||||
MDContactEmail admin@shaarli.mydomain.org
|
||||
MDPrivateKeys RSA 4096
|
||||
|
||||
<VirtualHost *:443>
|
||||
ServerName shaarli.mydomain.org
|
||||
DocumentRoot /var/www/shaarli.mydomain.org/
|
||||
|
||||
# SSL/TLS configuration for Let's Encrypt certificates acquired with certbot standalone
|
||||
SSLEngine on
|
||||
|
||||
# If using certbot:
|
||||
SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem
|
||||
# Let's Encrypt settings from https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/_internal/tls_configs/current-options-ssl-apache.conf
|
||||
SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
|
||||
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384
|
||||
SSLHonorCipherOrder off
|
||||
SSLSessionTickets off
|
||||
SSLOptions +StrictRequire
|
||||
|
||||
# SSL/TLS configuration for self-signed certificates
|
||||
#SSLEngine on
|
||||
#SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
|
||||
#SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
|
||||
# If using self-signed certificates:
|
||||
SSLEngine on
|
||||
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
|
||||
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
|
||||
|
||||
# Optional, log PHP errors, useful for debugging
|
||||
#php_flag log_errors on
|
||||
|
|
@ -194,6 +185,10 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
|
|||
#php_value error_reporting 2147483647
|
||||
#php_value error_log /var/log/apache2/shaarli-php-error.log
|
||||
|
||||
<FilesMatch \.php$>
|
||||
SetHandler "proxy:unix:/run/php/php8.2-fpm.sock|fcgi://localhost"
|
||||
</FilesMatch>
|
||||
|
||||
<Directory /var/www/shaarli.mydomain.org/>
|
||||
# Required for .htaccess support
|
||||
AllowOverride All
|
||||
|
|
@ -207,8 +202,6 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
|
|||
</FilesMatch>
|
||||
</Directory>
|
||||
|
||||
# BE CAREFUL: directives order matter!
|
||||
|
||||
<FilesMatch ".*\.(?!(ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$)[^\.]*$">
|
||||
Require all denied
|
||||
</FilesMatch>
|
||||
|
|
@ -237,29 +230,14 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
|
|||
# Enable the virtualhost
|
||||
sudo a2ensite shaarli.mydomain.org
|
||||
|
||||
# mod_ssl must be enabled to use TLS/SSL certificates
|
||||
# https://httpd.apache.org/docs/current/mod/mod_ssl.html
|
||||
sudo a2enmod ssl
|
||||
|
||||
# mod_rewrite must be enabled to use the REST API
|
||||
# https://httpd.apache.org/docs/current/mod/mod_rewrite.html
|
||||
sudo a2enmod rewrite
|
||||
|
||||
# mod_headers must be enabled to set custom headers from the server config
|
||||
sudo a2enmod headers
|
||||
|
||||
# mod_version must only be enabled if you use Apache 2.2 or lower
|
||||
# https://httpd.apache.org/docs/current/mod/mod_version.html
|
||||
# sudo a2enmod version
|
||||
|
||||
# restart the apache service
|
||||
# Restart the apache service
|
||||
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)
|
||||
- [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/)
|
||||
- [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 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)
|
||||
|
|
@ -267,12 +245,8 @@ sudo systemctl restart apache2
|
|||
|
||||
### Nginx
|
||||
|
||||
This examples uses nginx and the [PHP-FPM](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mariadb-php-lemp-stack-on-debian-10#step-3-%E2%80%94-installing-php-for-processing) PHP interpreter. Nginx and PHP-FPM must be running using the same user and group, here we assume the user/group to be `www-data:www-data`.
|
||||
|
||||
|
||||
```bash
|
||||
# install nginx and php-fpm
|
||||
sudo apt update
|
||||
# Install nginx and php-fpm
|
||||
sudo apt install nginx php-fpm
|
||||
|
||||
# Edit the virtualhost configuration file with your favorite editor
|
||||
|
|
@ -362,36 +336,30 @@ sudo systemctl reload nginx
|
|||
```
|
||||
|
||||
- [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 ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
|
||||
- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
|
||||
- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/)
|
||||
- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx)
|
||||
|
||||
- [Nginx ngx_http_fastcgi_module](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
|
||||
- [Nginx Pitfalls](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/)
|
||||
- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)
|
||||
|
||||
|
||||
## Reverse proxies
|
||||
|
||||
If Shaarli is hosted on a server behind a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) (i.e. there is a proxy server between clients and the web server hosting Shaarli), configure it accordingly. See [Reverse proxy](Reverse-proxy.md) configuration.
|
||||
|
||||
|
||||
## Using Shaarli without URL rewriting
|
||||
|
||||
By default, Shaarli uses Slim framework's URL, which requires
|
||||
URL rewriting.
|
||||
By default, Shaarli uses Slim framework's URL, which requires URL rewriting.
|
||||
|
||||
If you can't use URL rewriting for any reason (not supported by
|
||||
your web server, shared hosting, etc.), you *can* use Shaarli
|
||||
without URL rewriting.
|
||||
If you can't use URL rewriting for any reason (not supported by your web server, shared hosting, etc.), you *can* use Shaarli without URL rewriting.
|
||||
|
||||
You just need to prefix your URL by `/index.php/`.
|
||||
Example: instead of accessing `https://shaarli.mydomain.org/`,
|
||||
use `https://shaarli.mydomain.org/index.php/`.
|
||||
You just need to prefix your URL by `/index.php/`. Example: instead of accessing `https://shaarli.mydomain.org/`, use `https://shaarli.mydomain.org/index.php/`.
|
||||
|
||||
**Recommended:**
|
||||
* after installation, in the configuration page, set your header link to `/index.php/`.
|
||||
* in your configuration file `config.json.php` set `general.root_url` to
|
||||
`https://shaarli.mydomain.org/index.php/`.
|
||||
* after installation, in the configuration page, set your header link to `/index.php/`.
|
||||
* in your configuration file `config.json.php` set `general.root_url` to `https://shaarli.mydomain.org/index.php/`.
|
||||
|
||||
|
||||
## Allow import of large browser bookmarks export
|
||||
|
||||
|
|
@ -436,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.
|
||||
|
||||
- [Robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard)
|
||||
- [Introduction to robots.txt](https://support.google.com/webmasters/answer/6062608?hl=en)
|
||||
- [Robots meta tag, data-nosnippet, and X-Robots-Tag specifications](https://developers.google.com/search/reference/robots_meta_tag)
|
||||
- [About robots.txt](http://www.robotstxt.org)
|
||||
- [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/docs/crawling-indexing/robots-meta-tag)
|
||||
- [About robots.txt](https://www.robotstxt.org)
|
||||
- [About the robots META tag](https://www.robotstxt.org/meta.html)
|
||||
|
||||
|
||||
## 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
|
||||
# /etc/fail2ban/filter.d/shaarli-auth.conf
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ Some settings can be configured directly from a web browser by accesing the `Too
|
|||
|
||||
## Configuration file example
|
||||
|
||||
```json
|
||||
```
|
||||
<?php /*
|
||||
{
|
||||
"credentials": {
|
||||
|
|
@ -106,7 +106,7 @@ Some settings can be configured directly from a web browser by accesing the `Too
|
|||
"mode": "common"
|
||||
},
|
||||
"plugins": {
|
||||
"WALLABAG_URL": "http://demo.wallabag.org",
|
||||
"WALLABAG_URL": "https://demo.wallabag.org",
|
||||
"WALLABAG_VERSION": "1"
|
||||
},
|
||||
"translation": {
|
||||
|
|
@ -138,7 +138,7 @@ _These settings should not be edited_
|
|||
- **title**: Shaarli's instance title.
|
||||
- **header_link**: Link to the homepage.
|
||||
- **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.
|
||||
- **default_note_title**: Default title of a new note.
|
||||
- **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown.
|
||||
|
|
@ -188,7 +188,7 @@ Additional settings applied to formatters.
|
|||
|
||||
### Translation
|
||||
|
||||
- **language**: translation language (also see [Translations](dev/Translations.md))
|
||||
- **language**: translation language (also see [Translations](dev/Development.md#translations))
|
||||
- **auto** (default): The translation language is chosen from the browser locale.
|
||||
It means that the language can be different for 2 different visitors depending on their locale.
|
||||
- **en**: Use the English translation.
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ Shaarli redirections will not work properly. To solve this, assign a local domai
|
|||
|
||||
- On hosts (such as **free.fr**) which only support PHP 5.6, Shaarli [v0.10.4](https://github.com/shaarli/Shaarli/releases/tag/v0.10.4) is the maximum supported version. At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
|
||||
|
||||
```xml
|
||||
```apacheconf
|
||||
<IfDefine Free>
|
||||
php56 1
|
||||
</IfDefine>
|
||||
|
|
@ -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
|
||||
|
||||
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"
|
||||
|
|
@ -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
|
||||
|
||||
- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
|
||||
- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
|
||||
- [Bookmark Dupes](https://addons.mozilla.org/en-US/firefox/addon/bookmark-dupes/) - provides an easy way to deduplicate your bookmarks
|
||||
|
||||
### Diigo
|
||||
|
||||
|
|
@ -157,7 +156,7 @@ See [this issue](https://github.com/sebsauvage/Shaarli/issues/146) for import tw
|
|||
|
||||
### 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
|
||||
|
||||
|
|
@ -177,7 +176,7 @@ You can use the third-party tool [Derefind](https://github.com/ShawnPConroy/Dere
|
|||
|
||||
### 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.
|
||||
|
||||
|
|
@ -206,7 +205,7 @@ sudo systemctl restart apache2
|
|||
|
||||
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)
|
||||
- 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.
|
||||
|
|
|
|||
|
|
@ -164,7 +164,7 @@ $ make translate
|
|||
|
||||
If you use translations in gettext mode, reload your web server.
|
||||
|
||||
Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install [yarn](https://yarnpkg.com/lang/en/docs/install/):
|
||||
Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install [yarn](https://classic.yarnpkg.com/en/docs/install/):
|
||||
|
||||
```bash
|
||||
$ make build_frontend
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
# Usage
|
||||
|
||||
## Features
|
||||
|
||||
For any item posted to Shaarli (called a _Shaare_), you can customize the following aspects:
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -1,70 +0,0 @@
|
|||
## Introduction
|
||||
### PGP and GPG
|
||||
[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/)
|
||||
- [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.
|
||||
|
||||
-- Phil Pennock (author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/)
|
||||
|
||||
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),
|
||||
|
||||
|
||||
## Generate a GPG key
|
||||
- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)
|
||||
- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)
|
||||
|
||||
### gpg - provide identity information
|
||||
```bash
|
||||
$ gpg --gen-key
|
||||
|
||||
gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
|
||||
Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
|
||||
|
||||
GnuPG needs to construct a user ID to identify your key.
|
||||
|
||||
Real name: Marvin the Paranoid Android
|
||||
Email address: marvin@h2g2.net
|
||||
You selected this USER-ID:
|
||||
"Marvin the Paranoid Android <marvin@h2g2.net>"
|
||||
|
||||
Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
|
||||
We need to generate a lot of random bytes. It is a good idea to perform
|
||||
some other action (type on the keyboard, move the mouse, utilize the
|
||||
disks) during the prime generation; this gives the random number
|
||||
generator a better chance to gain enough entropy.
|
||||
```
|
||||
|
||||
### gpg - entropy interlude
|
||||
At this point, you will:
|
||||
- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
|
||||
- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step _may take some time_
|
||||
|
||||
### gpg - key creation confirmation
|
||||
```bash
|
||||
gpg: key A9D53A3E marked as ultimately trusted
|
||||
public and secret key created and signed.
|
||||
|
||||
gpg: checking the trustdb
|
||||
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
|
||||
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
|
||||
pub rsa2048/A9D53A3E 2015-07-31
|
||||
Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
|
||||
uid [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>
|
||||
sub rsa2048/8C0EACF1 2015-07-31
|
||||
```
|
||||
|
||||
### gpg - submit your public key to a PGP server (Optional)
|
||||
``` bash
|
||||
$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
|
||||
gpg: sending key A9D53A3E to hkp server pgp.mit.edu
|
||||
```
|
||||
|
||||
## Create and push a GPG-signed tag
|
||||
|
||||
See [Release Shaarli](Release-Shaarli.md).
|
||||
|
|
@ -1,819 +0,0 @@
|
|||
# Plugin system
|
||||
|
||||
## Developer API
|
||||
|
||||
### What can I do with plugins?
|
||||
|
||||
The plugin system lets you:
|
||||
|
||||
- insert content into specific places across templates.
|
||||
- alter data before templates rendering.
|
||||
- alter data before saving new links.
|
||||
|
||||
|
||||
### How can I create a plugin for Shaarli?
|
||||
|
||||
First, chose a plugin name, such as `demo_plugin`.
|
||||
|
||||
Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.meta file and a <plugin_name>.php file in that folder.
|
||||
|
||||
You should have the following tree view:
|
||||
|
||||
```
|
||||
| index.php
|
||||
| plugins/
|
||||
|---| demo_plugin/
|
||||
| |---| demo_plugin.meta
|
||||
| |---| demo_plugin.php
|
||||
```
|
||||
|
||||
### Plugin initialization
|
||||
|
||||
At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function in the <plugin_name>.php to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
|
||||
|
||||
<plugin_name>_init($conf)
|
||||
|
||||
This function can be used to create initial data, load default settings, etc. But also to set *plugin errors*. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
|
||||
|
||||
The plugin system also looks for a `description` variable in the <plugin_name>.meta file, to be displayed in the plugin administration page.
|
||||
|
||||
description="The plugin does this and that."
|
||||
|
||||
### Understanding hooks
|
||||
|
||||
A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
|
||||
|
||||
These functions need to be named with this pattern:
|
||||
|
||||
```
|
||||
hook_<plugin_name>_<hook_name>($data, $conf)
|
||||
```
|
||||
|
||||
Parameters:
|
||||
|
||||
- data: see [$data section](https://shaarli.readthedocs.io/en/master/Plugin-System/#plugins-data)
|
||||
- conf: the `ConfigManager` instance.
|
||||
|
||||
For example, if my plugin want to add data to the header, this function is needed:
|
||||
|
||||
hook_demo_plugin_render_header
|
||||
|
||||
If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
|
||||
|
||||
|
||||
### Plugin's data
|
||||
|
||||
#### Parameters
|
||||
|
||||
Every hook function has a `$data` parameter. Its content differs for each hooks.
|
||||
|
||||
**This parameter needs to be returned every time**, otherwise data is lost.
|
||||
|
||||
return $data;
|
||||
|
||||
#### Special data
|
||||
|
||||
Special additional data are passed to every hook through the
|
||||
`$data` parameter to give you access to additional context, and services.
|
||||
|
||||
Complete list:
|
||||
|
||||
* `_PAGE_` (string): if the current hook is used to render a template, its name is passed through this additional parameter.
|
||||
* `_LOGGEDIN_` (bool): whether the user is logged in or not.
|
||||
* `_BASE_PATH_` (string): if Shaarli instance is hosted under a subfolder, contains the subfolder path to `index.php` (e.g. `https://domain.tld/shaarli/` -> `/shaarli/`).
|
||||
* `_BOOKMARK_SERVICE_` (`BookmarkServiceInterface`): bookmark service instance, for advanced usage.
|
||||
|
||||
Example:
|
||||
|
||||
```php
|
||||
if ($data['_PAGE_'] === TemplatePage::LINKLIST && $data['LOGGEDIN'] === true) {
|
||||
// Do something for logged in users when the link list is rendered
|
||||
}
|
||||
```
|
||||
|
||||
#### Filling templates placeholder
|
||||
|
||||
Template placeholders are displayed in template in specific places.
|
||||
|
||||
RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
|
||||
|
||||
For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
|
||||
|
||||
```php
|
||||
$data['top_placeholder'][] = 'My content';
|
||||
# OR
|
||||
array_push($data['top_placeholder'], 'My', 'content');
|
||||
|
||||
return $data;
|
||||
```
|
||||
|
||||
|
||||
#### Data manipulation
|
||||
|
||||
When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
|
||||
|
||||
The data contained by this array can be altered before template rendering.
|
||||
|
||||
For example, in linklist, it is possible to alter every title:
|
||||
|
||||
```php
|
||||
// mind the reference if you want $data to be altered
|
||||
foreach ($data['links'] as &$value) {
|
||||
// String reverse every title.
|
||||
$value['title'] = strrev($value['title']);
|
||||
}
|
||||
|
||||
return $data;
|
||||
```
|
||||
|
||||
### Metadata
|
||||
|
||||
Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
|
||||
|
||||
Each file contain two keys:
|
||||
|
||||
- `description`: plugin description
|
||||
- `parameters`: user parameter names, separated by a `;`.
|
||||
- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
|
||||
|
||||
> 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 <plugin_name>_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/<plugin name>/`.
|
||||
- `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 <shaarli_url>/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.
|
||||
This means that you can *never* use absolute paths (eg `/plugins/mything/file.png`).
|
||||
|
||||
If a file needs to be included in server end, use simple relative path:
|
||||
`PluginManager::$PLUGINS_PATH . '/mything/template.html'`.
|
||||
|
||||
If it needs to be included in front end side (e.g. an image),
|
||||
the relative path must be prefixed with special data:
|
||||
|
||||
* if it's a link that will need to be processed by Shaarli, use `_BASE_PATH_`:
|
||||
for e.g. `$data['_BASE_PATH_'] . '/admin/tools`.
|
||||
* if you want to include an asset, you need to add the root URL (base path without `/index.php`, for people using Shaarli without URL rewriting), then use `_ROOT_PATH_`:
|
||||
for e.g
|
||||
`$['_ROOT_PATH_'] . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`.
|
||||
|
||||
Note that special placeholders for CSS and JS files (respectively `css_files` and `js_files`) are already prefixed
|
||||
with the root path in template files.
|
||||
|
||||
### It's not working!
|
||||
|
||||
Use `demo_plugin` as a functional example. It covers most of the plugin system features.
|
||||
|
||||
If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
|
||||
|
||||
|
||||
### Hooks
|
||||
|
||||
| Hooks | Description |
|
||||
| ------------- |:-------------:|
|
||||
| [render_header](#render_header) | Allow plugin to add content in page headers. |
|
||||
| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
|
||||
| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
|
||||
| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |
|
||||
| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
|
||||
| [render_tools](#render_tools) | Allow to add content at the end of the page. |
|
||||
| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
|
||||
| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
|
||||
| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
|
||||
| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |
|
||||
| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
|
||||
| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
|
||||
| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
|
||||
| [save_plugin_parameters](#save_plugin_parameters) | Allow to manipulate plugin parameters before they're saved. |
|
||||
| [filter_search_entry](#filter_search_entry) | Add custom filters to Shaarli search engine |
|
||||
|
||||
|
||||
#### render_header
|
||||
|
||||
Triggered on every page - allows plugins to add content in page headers.
|
||||
|
||||
|
||||
##### Data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `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.
|
||||
|
||||
|
||||
|
||||
|
||||
#### render_includes
|
||||
|
||||
Triggered on every page - allows plugins to include their own CSS files.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `css_files`: called after loading default CSS.
|
||||
|
||||
> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
|
||||
|
||||
|
||||
#### render_footer
|
||||
|
||||
Triggered on every page.
|
||||
|
||||
Allow plugin to add content in page footer and include their own JS files.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `text`: called after the end of the footer text.
|
||||
- `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`.
|
||||
|
||||
|
||||
#### render_linklist
|
||||
|
||||
Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
|
||||
|
||||
It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data, including links.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `action_plugin`: next to the button "private only" at the top and bottom of the page.
|
||||
|
||||
|
||||
|
||||
- `link_plugin`: for every link, between permalink and link URL.
|
||||
|
||||
|
||||
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
|
||||
|
||||
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
|
||||
|
||||
|
||||
#### render_editlink
|
||||
|
||||
Triggered when the link edition form is displayed.
|
||||
|
||||
Allow to add fields in the form, or display elements.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### 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.
|
||||
|
||||
|
||||
|
||||
|
||||
#### render_tools
|
||||
|
||||
Triggered when the "tools" page is displayed.
|
||||
|
||||
Allow to add content at the end of the page.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### 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.
|
||||
|
||||
|
||||
|
||||
|
||||
#### render_picwall
|
||||
|
||||
Triggered when picwall is displayed.
|
||||
|
||||
Allow to add content at the top and bottom of the page.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
|
||||
|
||||
|
||||
#### render_tagcloud
|
||||
|
||||
Triggered when tagcloud is displayed.
|
||||
|
||||
Allow to add content at the top and bottom of the page.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
For each tag, the following placeholder can be used:
|
||||
|
||||
- `tag_plugin`: after each tag
|
||||
|
||||
|
||||
|
||||
|
||||
#### render_taglist
|
||||
|
||||
Triggered when taglist is displayed - allows to add content at the top and bottom of the page.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
For each tag, the following placeholder can be used:
|
||||
|
||||
- `tag_plugin`: after each tag
|
||||
|
||||
#### render_daily
|
||||
|
||||
Triggered when tagcloud is displayed.
|
||||
|
||||
Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
|
||||
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data, including links.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `link_plugin`: used at bottom of each link.
|
||||
|
||||
|
||||
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
|
||||
#### render_feed
|
||||
|
||||
Triggered when the ATOM or RSS feed is displayed.
|
||||
|
||||
Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing:
|
||||
|
||||
- All templates data, including links.
|
||||
- [Special data](#special-data)
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
|
||||
|
||||
List of placeholders:
|
||||
|
||||
- `feed_plugins_header`: used as a header tag in the feed.
|
||||
|
||||
For each links:
|
||||
|
||||
- `feed_plugins`: additional tag for every link entry.
|
||||
|
||||
|
||||
#### save_link
|
||||
|
||||
Triggered when a link is save (new link or edit).
|
||||
|
||||
Allow to alter the link being saved in the datastore.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing the link being saved:
|
||||
|
||||
- id
|
||||
- title
|
||||
- url
|
||||
- shorturl
|
||||
- description
|
||||
- private
|
||||
- tags
|
||||
- created
|
||||
- updated
|
||||
|
||||
Also [special data](#special-data).
|
||||
|
||||
|
||||
#### delete_link
|
||||
|
||||
Triggered when a link is deleted.
|
||||
|
||||
Allow to execute any action before the link is actually removed from the datastore
|
||||
|
||||
##### data
|
||||
|
||||
`$data` is an array containing the link being deleted:
|
||||
|
||||
- id
|
||||
- title
|
||||
- url
|
||||
- shorturl
|
||||
- description
|
||||
- private
|
||||
- tags
|
||||
- created
|
||||
- updated
|
||||
|
||||
Also [special data](#special-data).
|
||||
|
||||
#### save_plugin_parameters
|
||||
|
||||
Triggered when the plugin parameters are saved from the plugin administration page.
|
||||
|
||||
Plugins can perform an action every times their settings are updated.
|
||||
For example it is used to update the CSS file of the `default_colors` plugins.
|
||||
|
||||
##### data
|
||||
|
||||
`$data` input contains the `$_POST` array.
|
||||
|
||||
So if the plugin has a parameter called `MYPLUGIN_PARAMETER`,
|
||||
the array will contain an entry with `MYPLUGIN_PARAMETER` as a key.
|
||||
|
||||
Also [special data](#special-data).
|
||||
|
||||
#### filter_search_entry
|
||||
|
||||
Triggered for *every* bookmark when Shaarli's BookmarkService method `search()` is used.
|
||||
Any custom filter can be added to filter out bookmarks from search results.
|
||||
|
||||
The hook **must** return either:
|
||||
- `true` to keep bookmark entry in search result set
|
||||
- `false` to discard bookmark entry in result set
|
||||
|
||||
> Note: custom filters are called *before* default filters are applied.
|
||||
|
||||
##### Parameters
|
||||
|
||||
- `Shaarli\Bookmark\Bookmark` object: entry to evaluate
|
||||
- $context `array`: additional information provided depending on what search is currently used,
|
||||
the user request, etc.
|
||||
|
||||
## Guide for template designers
|
||||
|
||||
### Plugin administration
|
||||
|
||||
Your theme must include a plugin administration page: `pluginsadmin.html`.
|
||||
|
||||
> Note: repo's template link needs to be added when the PR is merged.
|
||||
|
||||
Use the default one as an example.
|
||||
|
||||
Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
|
||||
|
||||
- you're using a table.
|
||||
- you call orderUp() and orderUp() onclick on arrows.
|
||||
- you add data-line and data-order to your rows.
|
||||
|
||||
Otherwise, you can use your own JS as long as this field is send by the form:
|
||||
|
||||
<input type="hidden" name="order_{$key}" value="{$counter}">
|
||||
|
||||
### Placeholder system
|
||||
|
||||
In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
|
||||
|
||||
It's a RainTPL loop like this:
|
||||
|
||||
{loop="$plugin_variable"}
|
||||
{$value}
|
||||
{/loop}
|
||||
|
||||
You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
|
||||
|
||||
### List of placeholders
|
||||
|
||||
**page.header.html**
|
||||
|
||||
At the end of the menu:
|
||||
|
||||
{loop="$plugins_header.buttons_toolbar"}
|
||||
{$value}
|
||||
{/loop}
|
||||
|
||||
At the end of file, before clearing floating blocks:
|
||||
|
||||
{if="!empty($plugin_errors) && $is_logged_in"}
|
||||
<ul class="errors">
|
||||
{loop="plugin_errors"}
|
||||
<li>{$value}</li>
|
||||
{/loop}
|
||||
</ul>
|
||||
{/if}
|
||||
|
||||
**includes.html**
|
||||
|
||||
At the end of the file:
|
||||
|
||||
```html
|
||||
{loop="$plugins_includes.css_files"}
|
||||
<link type="text/css" rel="stylesheet" href="{$value}#"/>
|
||||
{/loop}
|
||||
```
|
||||
|
||||
**page.footer.html**
|
||||
|
||||
At the end of your footer notes:
|
||||
|
||||
```html
|
||||
{loop="$plugins_footer.text"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
At the end of file:
|
||||
|
||||
```html
|
||||
{loop="$plugins_footer.js_files"}
|
||||
<script src="{$value}#"></script>
|
||||
{/loop}
|
||||
```
|
||||
|
||||
**linklist.html**
|
||||
|
||||
After search fields:
|
||||
|
||||
```html
|
||||
{loop="$plugins_header.fields_toolbar"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
Before displaying the link list (after paging):
|
||||
|
||||
```html
|
||||
{loop="$plugin_start_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
For every links (icons):
|
||||
|
||||
```html
|
||||
{loop="$value.link_plugin"}
|
||||
<span>{$value}</span>
|
||||
{/loop}
|
||||
```
|
||||
|
||||
Before end paging:
|
||||
|
||||
```html
|
||||
{loop="$plugin_end_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
**linklist.paging.html**
|
||||
|
||||
After the "private only" icon:
|
||||
|
||||
```html
|
||||
{loop="$action_plugin"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
**editlink.html**
|
||||
|
||||
After tags field:
|
||||
|
||||
```html
|
||||
{loop="$edit_link_plugin"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
**tools.html**
|
||||
|
||||
After the last tool:
|
||||
|
||||
```html
|
||||
{loop="$tools_plugin"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
**picwall.html**
|
||||
|
||||
Top:
|
||||
|
||||
```html
|
||||
<div id="plugin_zone_start_picwall" class="plugin_zone">
|
||||
{loop="$plugin_start_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
Bottom:
|
||||
|
||||
```html
|
||||
<div id="plugin_zone_end_picwall" class="plugin_zone">
|
||||
{loop="$plugin_end_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
**tagcloud.html**
|
||||
|
||||
Top:
|
||||
|
||||
```html
|
||||
<div id="plugin_zone_start_tagcloud" class="plugin_zone">
|
||||
{loop="$plugin_start_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
Bottom:
|
||||
|
||||
```html
|
||||
<div id="plugin_zone_end_tagcloud" class="plugin_zone">
|
||||
{loop="$plugin_end_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
**daily.html**
|
||||
|
||||
Top:
|
||||
|
||||
```html
|
||||
<div id="plugin_zone_start_picwall" class="plugin_zone">
|
||||
{loop="$plugin_start_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
After every link:
|
||||
|
||||
```html
|
||||
<div class="dailyEntryFooter">
|
||||
{loop="$link.link_plugin"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
Bottom:
|
||||
|
||||
```html
|
||||
<div id="plugin_zone_end_picwall" class="plugin_zone">
|
||||
{loop="$plugin_end_zone"}
|
||||
{$value}
|
||||
{/loop}
|
||||
</div>
|
||||
```
|
||||
|
||||
**feed.atom.xml** and **feed.rss.xml**:
|
||||
|
||||
In headers tags section:
|
||||
```xml
|
||||
{loop="$feed_plugins_header"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
||||
After each entry:
|
||||
```xml
|
||||
{loop="$value.feed_plugins"}
|
||||
{$value}
|
||||
{/loop}
|
||||
```
|
||||
|
|
@ -1,154 +0,0 @@
|
|||
# Release Shaarli
|
||||
|
||||
## Requirements
|
||||
|
||||
This guide assumes that you have:
|
||||
|
||||
- a GPG key matching your GitHub authentication credentials/email (the email address identified by the GPG key is the same as the one in your `~/.gitconfig`)
|
||||
- a GitHub fork of Shaarli
|
||||
- a local clone of your Shaarli fork, with the following remotes:
|
||||
- `origin` pointing to your GitHub fork
|
||||
- `upstream` pointing to the main Shaarli repository
|
||||
- maintainer permissions on the main Shaarli repository, to:
|
||||
- push the signed tag
|
||||
- create a new release
|
||||
- [Composer](https://getcomposer.org/) needs to be installed
|
||||
- The [venv](https://docs.python.org/3/library/venv.html) Python 3 module needs to be installed for HTML documentation generation.
|
||||
- Make sure you have GNU `tar` installed (not BSD `tar`). On macOS, you can install it with `brew install gnu-tar`.
|
||||
|
||||
## 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.
|
||||
|
||||
`CHANGELOG.md` should contain the same information as the release note draft for the upcoming version. Update it to:
|
||||
|
||||
- add new entries (additions, fixes, etc.)
|
||||
- mark the current version as released by setting its date and link
|
||||
- add a new section for the future unreleased version
|
||||
|
||||
```bash
|
||||
## [v0.x.y](https://github.com/shaarli/Shaarli/releases/tag/v0.x.y) - UNRELEASES
|
||||
|
||||
### Added
|
||||
|
||||
### Changed
|
||||
|
||||
### Fixed
|
||||
|
||||
### Removed
|
||||
|
||||
### Deprecated
|
||||
|
||||
### Security
|
||||
|
||||
```
|
||||
|
||||
|
||||
## Update the list of Git contributors
|
||||
|
||||
```bash
|
||||
$ make generate_authors
|
||||
$ git commit -s -m "Update AUTHORS"
|
||||
```
|
||||
|
||||
## Create and merge a Pull Request
|
||||
|
||||
Create a Pull Request to marge changes from your remote, into `master` in the community Shaarli repository, and have it merged.
|
||||
|
||||
|
||||
## Create the release branch and update shaarli_version.php
|
||||
|
||||
```bash
|
||||
# fetch latest changes from master to your local copy
|
||||
git checkout master
|
||||
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
|
||||
$ git add shaarli_version
|
||||
$ git commit -s -m "Bump Shaarli version to v0.x.0"
|
||||
$ git push upstream v0.x
|
||||
```
|
||||
|
||||
## 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/)
|
||||
|
||||
```bash
|
||||
# update your local copy
|
||||
git checkout v0.5
|
||||
git pull upstream v0.5
|
||||
|
||||
# create a signed tag
|
||||
git tag -s -m "Release v0.5.0" v0.5.0
|
||||
|
||||
# push the tag to upstream
|
||||
git push --tags upstream
|
||||
```
|
||||
|
||||
Here is how to verify a signed tag. [`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli. Let's have a look at its signature!
|
||||
|
||||
```bash
|
||||
# update the list of available tags
|
||||
git fetch upstream
|
||||
|
||||
# get the SHA1 reference of the tag
|
||||
git show-ref tags/v0.5.0
|
||||
# gives: f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
|
||||
|
||||
# verify the tag signature information
|
||||
git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
|
||||
# gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
|
||||
# gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate]
|
||||
```
|
||||
|
||||
## Publish the GitHub release
|
||||
|
||||
- In the `master` banch, update version badges in `README.md` to point to the newly released Shaarli version
|
||||
- Update the previously drafted [release](https://github.com/shaarli/Shaarli/releases) (notes, tag) and publish it
|
||||
- Profit!
|
||||
|
||||
|
||||
## Generate full release zip archives
|
||||
|
||||
Release archives will contain Shaarli code plus all required third-party libraries. They are useful for users who:
|
||||
|
||||
- have no SSH access, no possibility to install PHP packages/server extensions, no possibility to run scripts (shared hosting)
|
||||
- do not want to install build/dev dependencies on their server
|
||||
|
||||
`git checkout` the appropriate branch, then:
|
||||
|
||||
```bash
|
||||
# checkout the appropriate branch
|
||||
git checkout 0.x.y
|
||||
# generate zip archives
|
||||
make release_archive
|
||||
```
|
||||
|
||||
This will create `shaarli-v0.x.y-full.tar`, `shaarli-v0.x.y-full.zip`. These archives need to be manually uploaded on the previously created GitHub [release](https://github.com/shaarli/Shaarli/releases).
|
||||
|
||||
|
||||
### Update the `release` branch
|
||||
|
||||
```bash
|
||||
# checkout the 'release' branch
|
||||
git checkout release
|
||||
# merge changes from your newly published release branch
|
||||
git merge v0.x.y
|
||||
# fix eventual conflicts with git mergetool...
|
||||
# run tests
|
||||
make test
|
||||
# push the latest branch
|
||||
git push upstream release
|
||||
```
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
# Theming
|
||||
|
||||
## Foreword
|
||||
|
||||
There are two ways of customizing how Shaarli looks:
|
||||
|
||||
1. by using a custom CSS to override Shaarli's CSS
|
||||
2. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
|
||||
|
||||
## Custom CSS
|
||||
|
||||
Shaarli's appearance can be modified by adding CSS rules to:
|
||||
|
||||
- Shaarli < `v0.9.0`: `inc/user.css`
|
||||
- Shaarli >= `v0.9.0`: `data/user.css`
|
||||
|
||||
This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.
|
||||
|
||||
**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli.
|
||||
|
||||
## Themes
|
||||
|
||||
Installation:
|
||||
|
||||
- find a theme you'd like to install
|
||||
- copy or clone the theme folder under `tpl/<a_sweet_theme>`
|
||||
- enable the theme:
|
||||
- Shaarli < `v0.9.0`: edit `data/config.json.php` and set the value of `raintpl_tpl` to the new theme name:
|
||||
`"raintpl_tpl": "tpl\/my-template\/"`
|
||||
- Shaarli >= `v0.9.0`: select the theme through the _Tools_ page
|
||||
|
||||
## Community CSS & themes
|
||||
|
||||
### 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
|
||||
|
||||
- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme 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
|
||||
- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
|
||||
- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
|
||||
- [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
|
||||
- [xfnw/shaarli-default-dark](https://github.com/xfnw/shaarli-default-dark) - The default theme but nice and dark for your eyeballs
|
||||
|
||||
### Shaarli forks
|
||||
|
||||
- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
|
||||
- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
|
||||
|
||||
## Example installation: AlbinoMouse theme
|
||||
|
||||
With the following configuration:
|
||||
|
||||
- Apache 2 / PHP 5.6
|
||||
- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
|
||||
- `http` is the name of the Apache user
|
||||
|
||||
```bash
|
||||
$ cd ~/public_html
|
||||
|
||||
# clone repositories
|
||||
$ git clone https://github.com/shaarli/Shaarli.git shaarli
|
||||
$ pushd shaarli/tpl
|
||||
$ git clone https://github.com/alexisju/albinomouse-template.git
|
||||
$ popd
|
||||
|
||||
# set access rights for Apache
|
||||
$ chgrp -R http shaarli
|
||||
$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
|
||||
```
|
||||
|
||||
Get config written:
|
||||
- go to the freshly installed site
|
||||
- fill the install form
|
||||
- log in to Shaarli
|
||||
|
||||
Edit Shaarli's [configuration](../Shaarli-configuration.md):
|
||||
```bash
|
||||
# the file should be owned by Apache, thus not writeable => sudo
|
||||
$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
|
||||
```
|
||||
|
|
@ -1,157 +0,0 @@
|
|||
## Translations
|
||||
|
||||
Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
|
||||
since `>= v0.9.2`.
|
||||
|
||||
Note that only the `default` theme supports translations.
|
||||
|
||||
### Contributing
|
||||
|
||||
We encourage the community to contribute to Shaarli translations, either by improving existing translations or submitting a new language.
|
||||
|
||||
Contributing to the translation does not require software development knowledge.
|
||||
|
||||
Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`) is not stored on the repository, and is generated during the release process.
|
||||
|
||||
|
||||
### How to
|
||||
|
||||
Install [Poedit](https://poedit.net/) (used to extract strings to translate from the PHP source code, and generate `.po` files).
|
||||
|
||||
Due to the usage of a template engine, it's important to generate PHP cache files to extract every translatable string. You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07) (recommended) or visit every template page in your browser to generate cache files, while logged in. Here is a list :
|
||||
|
||||
```
|
||||
http://<replace_domain>/
|
||||
http://<replace_domain>/login
|
||||
http://<replace_domain>/daily
|
||||
http://<replace_domain>/tags/cloud
|
||||
http://<replace_domain>/tags/list
|
||||
http://<replace_domain>/picture-wall
|
||||
http://<replace_domain>/?nonope
|
||||
http://<replace_domain>/admin/add-shaare
|
||||
http://<replace_domain>/admin/password
|
||||
http://<replace_domain>/admin/tags
|
||||
http://<replace_domain>/admin/configure
|
||||
http://<replace_domain>/admin/tools
|
||||
http://<replace_domain>/admin/shaare
|
||||
http://<replace_domain>/admin/export
|
||||
http://<replace_domain>/admin/import
|
||||
http://<replace_domain>/admin/plugins
|
||||
```
|
||||
|
||||
|
||||
#### Improve existing translations
|
||||
|
||||
- In Poedit, click on "Edit a Translation
|
||||
- Open `inc/languages/<lang>/LC_MESSAGES/shaarli.po` under Shaarli's directory
|
||||
- The existing list of translatable strings should load
|
||||
- Click on the "Update" button.
|
||||
- Start editing translations.
|
||||
|
||||
|
||||
|
||||
Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
|
||||
|
||||
|
||||
#### Add a new language
|
||||
|
||||
- In Poedit select "Create New Translation"
|
||||
- Open `inc/languages/<lang>/LC_MESSAGES/shaarli.po` under Shaarli's directory
|
||||
- Select the language you want to create.
|
||||
- Click on `File > Save as...`, save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po` (`<new language>` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) format in lowercase - e.g. `de` for German)
|
||||
- Click on the "Update" button
|
||||
- Start editing translations.
|
||||
|
||||
Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
|
||||
|
||||
|
||||
### Theme translations
|
||||
|
||||
[Theme](Theming.md) translation extensions are loaded automatically if they're present.
|
||||
|
||||
As a theme developer, all you have to do is to add the `.po` and `.mo` compiled file like this:
|
||||
|
||||
```
|
||||
tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.po
|
||||
tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.mo
|
||||
```
|
||||
|
||||
Where `<lang>` is the ISO 3166-1 alpha-2 language code.
|
||||
|
||||
Read the following section "Extend Shaarli's translation" to learn how to generate those files.
|
||||
|
||||
|
||||
### Extend Shaarli's translation
|
||||
|
||||
If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
|
||||
but you won't be able to able to override Shaarli's translation.
|
||||
|
||||
However, you can add your own translation domain which extends the main translation list.
|
||||
|
||||
> Note that you can find a live example of translation extension in the `demo_plugin`.
|
||||
|
||||
First, create your translation files tree directory:
|
||||
|
||||
```
|
||||
<your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
|
||||
```
|
||||
|
||||
Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be
|
||||
`my_theme.po`.
|
||||
|
||||
Users have to register your extension in their configuration with the parameter
|
||||
`translation.extensions.<domain>: <translation files path>`.
|
||||
|
||||
Example:
|
||||
|
||||
```php
|
||||
if (! $conf->exists('translation.extensions.my_theme')) {
|
||||
$conf->set('translation.extensions.my_theme', '<your_module>/languages/');
|
||||
$conf->write(true);
|
||||
}
|
||||
```
|
||||
|
||||
> Note that the page needs to be reloaded after the registration.
|
||||
|
||||
It is then recommended to create a custom translation function which will call the `t()` function with your domain.
|
||||
For example :
|
||||
|
||||
```php
|
||||
function my_theme_t($text, $nText = '', $nb = 1)
|
||||
{
|
||||
return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain.
|
||||
}
|
||||
```
|
||||
|
||||
All strings which can be translated should be processed through your function:
|
||||
|
||||
```php
|
||||
my_theme_t('Comment');
|
||||
my_theme_t('Comment', 'Comments', 2);
|
||||
```
|
||||
|
||||
Or in templates:
|
||||
|
||||
```php
|
||||
{'Comment'|my_theme_t}
|
||||
{function="my_theme_t('Comment', 'Comments', 2)"}
|
||||
```
|
||||
|
||||
> Note than in template, you need to visit your page at least once to generate a cache file.
|
||||
|
||||
When you're done, open Poedit and load translation strings from sources:
|
||||
|
||||
1. `File > New`
|
||||
2. Choose your language
|
||||
3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`.
|
||||
4. Go to `Catalog > Properties...`
|
||||
5. Fill the `Translation Properties` tab
|
||||
6. Add your source path in the `Sources Paths` tab
|
||||
7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines:
|
||||
|
||||
```
|
||||
my_theme_t
|
||||
my_theme_t:1,2
|
||||
```
|
||||
|
||||
Click on the "Update" button and you're free to start your translations!
|
||||
|
|
@ -1,135 +0,0 @@
|
|||
# Unit tests
|
||||
|
||||
Shaarli uses the [PHPUnit](https://phpunit.de/) test framework; it can be installed with [Composer](../Installation.md#from-sources), which is a dependency management tool.
|
||||
|
||||
## Install composer
|
||||
|
||||
You can either use:
|
||||
|
||||
- a system-wide version, e.g. installed through your distro's package manager
|
||||
- a local version, downloadable [here](https://getcomposer.org/download/).
|
||||
|
||||
```bash
|
||||
# for Debian-based distros
|
||||
sudo apt install composer
|
||||
```
|
||||
|
||||
|
||||
## Install Shaarli dev dependencies
|
||||
|
||||
After installing [required PHP extensions](../Server-configuration.md#php), install development dependencies:
|
||||
|
||||
```bash
|
||||
$ cd /path/to/shaarli
|
||||
$ make composer_dependencies_dev
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
# for Debian-based distros:
|
||||
sudo apt install php-xdebug
|
||||
|
||||
# for ArchLinux:
|
||||
pacman -S xdebug
|
||||
|
||||
# then add the following line to /etc/php/php.ini
|
||||
zend_extension=xdebug.so
|
||||
```
|
||||
|
||||
## Run unit tests
|
||||
|
||||
Ensure tests pass successfully:
|
||||
|
||||
```bash
|
||||
make test
|
||||
# ...
|
||||
# OK (36 tests, 65 assertions)
|
||||
```
|
||||
|
||||
In case of failure the test suite will point you to actual errors and output a summary:
|
||||
|
||||
```bash
|
||||
make test
|
||||
# ...
|
||||
# FAILURES!
|
||||
# Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
|
||||
```
|
||||
|
||||
By default, PHPUnit will run all suitable tests found under the `tests` directory. Each test has 3 possible outcomes:
|
||||
|
||||
- `.` - success
|
||||
- `F` - failure: the test was run but its results are invalid
|
||||
- the code does not behave as expected
|
||||
- dependencies to external elements: globals, session, cache...
|
||||
- `E` - error: something went wrong and the tested code has crashed
|
||||
- typos in the code, or in the test code
|
||||
- dependencies to missing external elements
|
||||
|
||||
If Xdebug has been installed and activated, two coverage reports will be generated:
|
||||
|
||||
- a summary in the console
|
||||
- a detailed HTML report with metrics for tested code
|
||||
- to open it in a web browser: `firefox coverage/index.html &`
|
||||
|
||||
|
||||
### 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:
|
||||
|
||||
```php
|
||||
/**
|
||||
* Netscape bookmark import
|
||||
* @group WIP
|
||||
*/
|
||||
class BookmarkImportTest extends PHPUnit_Framework_TestCase
|
||||
{
|
||||
[...]
|
||||
}
|
||||
```
|
||||
|
||||
To run all tests annotated with `@group WIP`:
|
||||
```bash
|
||||
$ vendor/bin/phpunit --group WIP tests/
|
||||
```
|
||||
|
||||
## Running tests inside Docker containers
|
||||
|
||||
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:
|
||||
|
||||
- [`alpine316`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/alpine36/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)
|
||||
- [`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)
|
||||
|
||||
Each image provides:
|
||||
- a base Linux OS
|
||||
- Shaarli PHP dependencies (OS packages)
|
||||
- test PHP dependencies (OS packages)
|
||||
- Composer
|
||||
- Tests that run inside the container using a standard Linux user account (running tests as `root` would bypass permission checks and may hide issues)
|
||||
|
||||
Build a test image:
|
||||
|
||||
```bash
|
||||
# build the Debian 9 Docker image
|
||||
cd /path/to/shaarli/tests/docker/debian9
|
||||
docker build -t shaarli-test:debian9 .
|
||||
```
|
||||
|
||||
Run unit tests in a container:
|
||||
|
||||
```bash
|
||||
cd /path/to/shaarli
|
||||
# install/update 3rd-party test dependencies
|
||||
composer install --prefer-dist
|
||||
# run tests using the freshly built image
|
||||
docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
|
||||
# run the full test campaign
|
||||
docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
|
||||
```
|
||||
|
|
@ -1,63 +0,0 @@
|
|||
# Versioning
|
||||
|
||||
If you're maintaining a 3rd party tool for Shaarli (theme, plugin, etc.), It's important to understand how Shaarli branches work ensure your tool stays compatible.
|
||||
|
||||
|
||||
## `master` branch
|
||||
|
||||
The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
|
||||
|
||||
Remarks:
|
||||
|
||||
- This branch shouldn't be used for production as it isn't necessary stable.
|
||||
- 3rd party aren't required to be compatible with the latest changes.
|
||||
- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
|
||||
|
||||
|
||||
## `v0.x` branch
|
||||
|
||||
The `v0.x` branch points to the latest `v0.x.y` release.
|
||||
|
||||
If a major bug affects the original `v0.x.0` release, we may [backport](https://en.wikipedia.org/wiki/Backporting) a fix for this bug from master, to the `v0.x` branch, and create a new bugfix release (eg. `v0.x.1`) from this branch.
|
||||
|
||||
This allows users of the original release to upgrade to the fixed version, without having to upgrade to a completely new minor/major release.
|
||||
|
||||
|
||||
## `latest` branch
|
||||
|
||||
This branch point the latest release. It recommended to use it to get the latest tested changes.
|
||||
|
||||
|
||||
## Releases
|
||||
|
||||
For every release, we manually generate a .zip file which contains all Shaarli dependencies, making Shaarli's installation only one step.
|
||||
|
||||
|
||||
## Advices on 3rd party git repos workflow
|
||||
|
||||
### Versioning
|
||||
|
||||
Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:
|
||||
|
||||
- use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
|
||||
- use your own versioning scheme, and state Shaarli compatibility in the release description.
|
||||
|
||||
Using this, any user will be able to pick the release matching his own Shaarli version.
|
||||
|
||||
### Major bugfix backport releases
|
||||
|
||||
To be able to support backported fixes, it recommended to use our workflow:
|
||||
|
||||
```bash
|
||||
# In master, fix the major bug
|
||||
git commit -m "Katastrophe"
|
||||
git push origin master
|
||||
# Get your commit hash
|
||||
git log --format="%H" -n 1
|
||||
# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
|
||||
git checkout -b katastrophe v0.8.2-1
|
||||
# Backport the fix commit to your brand new branch
|
||||
git cherry-pick <fix commit hash>
|
||||
git push origin katastrophe
|
||||
# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
|
||||
```
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Shaarli
|
||||
|
||||
<img src="images/icon.png" width="16px" height="16px"> The personal, minimalist, super fast, database-free, bookmarking service.
|
||||
_The personal, minimalist, super fast, database-free, bookmarking service._
|
||||
|
||||
Do you want to share the links you discover? Shaarli is a minimalist bookmark manager and link sharing service that you can install on your own server. It is designed to be personal (single-user), fast and handy.
|
||||
|
||||
|
|
@ -11,9 +11,26 @@ Visit the pages in the sidebar to find information on how to setup, use, configu
|
|||
* [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md)
|
||||
|
||||
|
||||
[](https://i.imgur.com/WWPfSj0.png) [](https://i.imgur.com/V09kAQt.png) [](https://i.imgur.com/TZzGHMs.png) [](https://i.imgur.com/sfJJ6NT.png) [](https://i.imgur.com/QsedIuJ.png) [](https://i.imgur.com/KdtF8Ll.png) [](https://i.imgur.com/27wYsbC.png) [](https://i.imgur.com/zGF4d6L.jpg)
|
||||
[](https://i.imgur.com/WWPfSj0.png) [](https://i.imgur.com/V09kAQt.png) [](https://i.imgur.com/TZzGHMs.png) [](https://i.imgur.com/sfJJ6NT.png) [](https://i.imgur.com/QsedIuJ.png) [](https://i.imgur.com/KdtF8Ll.png) [](https://i.imgur.com/zGF4d6L.jpg)
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
:hidden:
|
||||
|
||||
Server-configuration.md
|
||||
Installation.md
|
||||
Reverse-proxy.md
|
||||
Docker.md
|
||||
Shaarli-configuration.md
|
||||
Usage.md
|
||||
Backup-and-restore.md
|
||||
Upgrade-and-migration.md
|
||||
Community-and-related-software.md
|
||||
Plugins.md
|
||||
REST-API.md
|
||||
Troubleshooting.md
|
||||
dev/Development.md
|
||||
```
|
||||
|
||||
## Demo
|
||||
|
||||
|
|
@ -88,23 +105,18 @@ Shaarli can be used:
|
|||
|
||||
## 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!)
|
||||
|
||||
|
||||
### Contributing and getting help
|
||||
|
||||
Feedback is very appreciated! Feel free to propose solutions to existing problems, help us improve the documentation and translations, and submit pull requests :-)
|
||||
Feedback is very appreciated! Feel free to propose solutions to existing problems, help us improve the documentation and [translations](dev/Development.md#translations), and submit pull requests :-)
|
||||
|
||||
See [Support](Troubleshooting.md#support) to get in touch with the Shaarli community.
|
||||
|
||||
|
||||
### 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).
|
||||
|
|
|
|||
4
doc/requirements.txt
Normal file
4
doc/requirements.txt
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
sphinx==7.1.0
|
||||
furo==2023.7.26
|
||||
myst-parser
|
||||
sphinx-design
|
||||
43
mkdocs.yml
43
mkdocs.yml
|
|
@ -1,43 +0,0 @@
|
|||
site_name: Shaarli Documentation
|
||||
repo_url: https://github.com/shaarli/Shaarli
|
||||
edit_uri: edit/master/doc/md
|
||||
site_description: The personal, minimalist, super fast, database-free, bookmarking service
|
||||
theme:
|
||||
name: readthedocs
|
||||
custom_dir: doc/custom_theme/
|
||||
docs_dir: doc/md
|
||||
site_dir: doc/html
|
||||
# Disable strict mode until ReadTheDocs provides up-to-date MkDocs settings:
|
||||
# - https://github.com/shaarli/Shaarli/issues/1179
|
||||
# - https://github.com/rtfd/readthedocs.org/issues/4314
|
||||
# strict: true
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Setup:
|
||||
- Server configuration: Server-configuration.md
|
||||
- Installation: Installation.md
|
||||
- Docker: Docker.md
|
||||
- Reverse Proxy: Reverse-proxy.md
|
||||
- Backup and restore: Backup-and-restore.md
|
||||
- Shaarli configuration: Shaarli-configuration.md
|
||||
- Plugins: Plugins.md
|
||||
- Upgrade and migration: Upgrade-and-migration.md
|
||||
- Usage:
|
||||
- Usage: Usage.md
|
||||
- REST API: REST-API.md
|
||||
- Community and Related software: Community-and-related-software.md
|
||||
- Development:
|
||||
- Development: dev/Development.md
|
||||
- Versioning: dev/Versioning.md
|
||||
- GnuPG signature: dev/GnuPG-signature.md
|
||||
- Plugin System: dev/Plugin-system.md
|
||||
- Translations: dev/Translations.md
|
||||
- Release Shaarli: dev/Release-Shaarli.md
|
||||
- Theming: dev/Theming.md
|
||||
- Unit tests: dev/Unit-tests.md
|
||||
- Troubleshooting: Troubleshooting.md
|
||||
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: "#"
|
||||
Loading…
Reference in a new issue