[github/shaarli/Shaarli.git] / doc / md / Plugins.md

# Plugins

## Installation

For plugins shipped with Shaarli, no installation is required.

If you want to install a third party plugin, download it to the `plugins` directory in Shaarli's installation folder:

```bash
# example directory structure
| index.php
| plugins/
|---| custom_plugin/
|   |---| custom_plugin.php
|   |---| ...

```

Make sure your webserver can read and write the files in your plugin folder.


## Configuration

From Shaarli's administration page (`Tools` link), go to `Plugin administration`. Here you can enable and disable all plugins available, and configure them.

![administration screenshot](https://camo.githubusercontent.com/5da68e191969007492ca0fbeb25f3b2357b748cc/687474703a2f2f692e696d6775722e636f6d2f766837544643712e706e67)


## Order

In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.

This is important in case plugins depend on each other. Read plugins READMEs for more information.

**Use case**: The (non existent) plugin `shaares_footer` adds a footer to every shaare in Markdown syntax. It needs to be processed *before* (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.


## Configuration file

Enabled plugins are stored in your [Configuration file](Shaarli-configuration).

## Usage

### Official plugins

Usage of each plugin is documented in it's README file:

 * `addlink-toolbar`: Adds the addlink input on the Shaares list page
 * `archiveorg`: For each Shaare, add a link to the archived page on Archive.org
 * `default_colors`: Override default theme colors.
 * `isso`: Let visitor comment your shaares on permalinks with Isso.
 * [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.
 * `piwik`: A plugin that adds Piwik tracking code to Shaarli pages.
 * [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.
 * `pubsubhubbub`: Enable PubSubHubbub feed publishing
 * `qrcode`: For each Shaare, add a QRCode icon.
 * [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md):  For each Shaare, add a Wallabag icon to save it in your instance.


### Third party plugins

See [Community & related software](https://shaarli.readthedocs.io/en/master/Community-and-Related-software/)
Commit	Line	Data
91a21c27	1	# Plugins
5409ade2	2
91a21c27	3	## Installation
5409ade2	4
91a21c27	5	For plugins shipped with Shaarli, no installation is required.
5409ade2	6
91a21c27	7	If you want to install a third party plugin, download it to the `plugins` directory in Shaarli's installation folder:
5409ade2	8
91a21c27	9	```bash
91a21c27	10	# example directory structure
5409ade2 A	11	\| index.php
	12	\| plugins/
	13	\|---\| custom_plugin/
	14	\| \|---\| custom_plugin.php
	15	\| \|---\| ...
	16
	17	```
	18
91a21c27	19	Make sure your webserver can read and write the files in your plugin folder.
5409ade2	20
5409ade2	21
91a21c27	22	## Configuration
5409ade2	23
91a21c27	24	From Shaarli's administration page (`Tools` link), go to `Plugin administration`. Here you can enable and disable all plugins available, and configure them.
5409ade2	25
53ed6d7d	26	![administration screenshot](https://camo.githubusercontent.com/5da68e191969007492ca0fbeb25f3b2357b748cc/687474703a2f2f692e696d6775722e636f6d2f766837544643712e706e67)
5409ade2	27
91a21c27	28
91a21c27	29	## Order
5409ade2 A	30
	31	In the plugin administration page, you can move enabled plugins to the top or bottom of the list. The first plugins in the list will be processed first.
	32
91a21c27	33	This is important in case plugins depend on each other. Read plugins READMEs for more information.
5409ade2 A	34
	35	Use case: The (non existent) plugin `shaares_footer` adds a footer to every shaare in Markdown syntax. It needs to be processed before (higher in the list) the Markdown plugin. Otherwise its syntax won't be translated in HTML.
	36
5409ade2	37
91a21c27	38	## Configuration file
91a21c27	39
46e019a1	40	Enabled plugins are stored in your [Configuration file](Shaarli-configuration).
5409ade2	41
91a21c27	42	## Usage
	43
	44	### Official plugins
08dcd8ea	45
5409ade2 A	46	Usage of each plugin is documented in it's README file:
5409ade2 A	47
91a21c27	48	* `addlink-toolbar`: Adds the addlink input on the Shaares list page
91a21c27	49	* `archiveorg`: For each Shaare, add a link to the archived page on Archive.org
a8fb97a0 A	50	* `default_colors`: Override default theme colors.
a8fb97a0 A	51	* `isso`: Let visitor comment your shaares on permalinks with Isso.
53ed6d7d	52	* [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.
a8fb97a0	53	* `piwik`: A plugin that adds Piwik tracking code to Shaarli pages.
53ed6d7d	54	* [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.
a8fb97a0	55	* `pubsubhubbub`: Enable PubSubHubbub feed publishing
91a21c27	56	* `qrcode`: For each Shaare, add a QRCode icon.
91a21c27	57	* [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each Shaare, add a Wallabag icon to save it in your instance.
08dcd8ea A	58
08dcd8ea A	59
91a21c27	60	### Third party plugins
08dcd8ea	61
91a21c27	62	See [Community & related software](https://shaarli.readthedocs.io/en/master/Community-and-Related-software/)