[github/shaarli/Shaarli.git] / doc / md / Sharing-content.md

Content posted to Shaarli is separated in items called _Shaares_. For each Shaare, 
you can customize the following aspects:

 * URL to link to
 * Title
 * Free-text description
 * Tags
 * Public/private status

--------------------------------------------------------------------------------

## Adding new Shaares

While logged in to your Shaarli, you can add new Shaares in several ways:

 * [+Shaare button]
 * [Bookmarklet]
 * [Firefox Share](#firefox-share)
 * Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps)
 * [REST API](https://shaarli.github.io/api-documentation/)

### +Shaare button

 * While logged in to your Shaarli, click the **`+Shaare`** button located in the toolbar.
 * Enter the URL of a link you want to share.
 * Click `Add link`
 * The `New Shaare` dialog appears, allowing you to fill in the details of your Shaare.
   * The Description, Title, and Tags will help you find your Shaare later using tags or full-text search.
   * You can also check the “Private” box so that the link is saved but only visible to you (the logged-in user).
 * Click `Save`.

<!-- TODO Add screenshot of add/edit link dialog -->

### Bookmarklet

The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special 
browser bookmark you can use to add new content to your Shaarli. This bookmarklet is 
compatible with Firefox, Opera, Chrome and Safari. To set it up:

 * Access the `Tools` page from the button in the toolbar.
 * Drag the **`✚Shaare link` button** to your browser's bookmarks bar.

Once this is done, you can shaare any URL you are visiting simply by clicking the 
bookmarklet in your browser! The same `New Shaare` dialog as above is displayed.

| Note | Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. 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)]\ |
|---------|---------|

| Note | 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. |
|---------|---------|

![](images/bookmarklet.png)


### Firefox Share

Before using Firefox Share, you must first add Shaarli as a sharing provider:

- Click the `Tools` button in the top bar
- Click the `✚Add to Firefox social` button and accept the activation.

Once this is done, you can share any URL you are visiting by clicking the Firefox 
_Share_ button [images/firefoxshare.png](images/firefoxshare.png)

| Note | Firefox Share is no longer available for Firefox 57 and later versions. |
|---------|---------|

| Note | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plaintext HTTP connections. |
|---------|---------|

--------------------------------------------------------------------------------

## Editing Shaares

Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button.

Editing a Shaare will not change it's permalink, each permalink always points to the 
latest revision of a Shaare.

--------------------------------------------------------------------------------

## Using shaarli as a blog, notepad, pastebin...

While adding or editing a link, leave the URL field blank to create a text-only 
("note") post. This allows you to post any kind of text content, such as blog 
articles, private or public notes, snippets... There is no character limit! You can 
access your Shaare from its permalink.
Commit	Line	Data
80786e15	1	Content posted to Shaarli is separated in items called _Shaares_. For each Shaare,
	2	you can customize the following aspects:
	3
	4	* URL to link to
	5	* Title
	6	* Free-text description
	7	* Tags
	8	* Public/private status
	9
	10	--------------------------------------------------------------------------------
	11
	12	## Adding new Shaares
	13
	14	While logged in to your Shaarli, you can add new Shaares in several ways:
	15
	16	* [+Shaare button]
	17	* [Bookmarklet]
	18	* [Firefox Share](#firefox-share)
	19	* Third-party [apps and browser addons](Community-\&-Related-software.md#mobile-apps)
2e47af89	20	* [REST API](https://shaarli.github.io/api-documentation/)
80786e15	21
	22	### +Shaare button
	23
	24	* While logged in to your Shaarli, click the `+Shaare` button located in the toolbar.
	25	* Enter the URL of a link you want to share.
	26	* Click `Add link`
	27	* The `New Shaare` dialog appears, allowing you to fill in the details of your Shaare.
	28	* The Description, Title, and Tags will help you find your Shaare later using tags or full-text search.
	29	* You can also check the “Private” box so that the link is saved but only visible to you (the logged-in user).
	30	* Click `Save`.
	31
	32	<!-- TODO Add screenshot of add/edit link dialog -->
	33
	34	### Bookmarklet
	35
	36	The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special
	37	browser bookmark you can use to add new content to your Shaarli. This bookmarklet is
	38	compatible with Firefox, Opera, Chrome and Safari. To set it up:
	39
	40	* Access the `Tools` page from the button in the toolbar.
	41	* Drag the `✚Shaare link` button to your browser's bookmarks bar.
	42
	43	Once this is done, you can shaare any URL you are visiting simply by clicking the
	44	bookmarklet in your browser! The same `New Shaare` dialog as above is displayed.
	45
	46	\| Note \| Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. 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)]\ \|
	47	\|---------\|---------\|
	48
	49	\| Note \| 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. \|
	50	\|---------\|---------\|
	51
	52	![](images/bookmarklet.png)
	53
	54
	55	### Firefox Share
	56
	57	Before using Firefox Share, you must first add Shaarli as a sharing provider:
	58
	59	- Click the `Tools` button in the top bar
	60	- Click the `✚Add to Firefox social` button and accept the activation.
	61
	62	Once this is done, you can share any URL you are visiting by clicking the Firefox
	63	_Share_ button [images/firefoxshare.png](images/firefoxshare.png)
	64
	65	\| Note \| Firefox Share is no longer available for Firefox 57 and later versions. \|
	66	\|---------\|---------\|
	67
	68	\| Note \| Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plaintext HTTP connections. \|
	69	\|---------\|---------\|
	70
	71	--------------------------------------------------------------------------------
	72
	73	## Editing Shaares
	74
bf7993dc	75	Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button.
80786e15	76
	77	Editing a Shaare will not change it's permalink, each permalink always points to the
	78	latest revision of a Shaare.
	79
	80	--------------------------------------------------------------------------------
	81
	82	## Using shaarli as a blog, notepad, pastebin...
	83
	84	While adding or editing a link, leave the URL field blank to create a text-only
	85	("note") post. This allows you to post any kind of text content, such as blog
	86	articles, private or public notes, snippets... There is no character limit! You can
	87	access your Shaare from its permalink.
	88