doc/md/Usage.md

   1 ## Features
   2
   3 For any item posted to Shaarli (called a _Shaare_), you can customize the following aspects:
   4
   5 - URL to link to
   6 - Title
   7 - Free-text description
   8 - Tags
   9 - Public/private status
  10
  11
  12 ### Adding/editing Shaares
  13
  14 While logged in to your Shaarli, you can add, edit or delete Shaares:
  15
  16 - Using the **+Shaare** button: enter the URL you want to share, click `Add link`, fill in the details of your Shaare, and `Save`
  17 - Using the [Bookmarklet](https://en.wikipedia.org/wiki/Bookmarklet): drag the `✚Shaare link` button from the `Tools` page to your browser's bookmarks bar, click it to share the current page.
  18 - Using [apps and browser addons](Community-and-related-software.md#mobile-apps)
  19 - Using the [REST API](https://shaarli.github.io/api-documentation/)
  20 - Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button.
  21
  22
  23 ### Tags
  24
  25 Tags can be be used to organize and categorize your Shaares:
  26
  27 - You can rename, merge and delete tags from the _Tools_ menu or the [tag cloud/list](#tag-cloud)
  28 - Tags are auto-completed (from the list of existing tags) in all dialogs
  29 - Tags can be combined with text in [search](#search) queries
  30
  31
  32 ### Public/private Shaares
  33
  34 Additional filter buttons can be found at the top left of the Shaare list **only when logged in**:
  35
  36 - **Only show private Shaares:** Private shares can be searched by clicking the `only show private links` toggle button top left of the Shaares list (only when logged in)
  37
  38
  39 ### Permalinks
  40
  41 Permalinks are fixed, short links attached to each Shaare. Editing a Shaare will not change it's permalink, each permalink always points to the latest revision of a Shaare.
  42
  43
  44 ### Text-only (note) Shaares
  45
  46 Shaarli can be used as a minimal blog, notepad, pastebin...: While adding or editing a Shaare, 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 post from its permalink.
  47
  48
  49 ### Search
  50
  51 - **Plain text search:** Use `Search text` to search in all fields of all Shaares (Title, URL, Description...). Use double-quotes (example `"exact search"`) to search for the exact expression.
  52 - **Tags search:** `Filter by tags` allow only displaying Shaares tagged with one or multiple tags (use space to separate tags).
  53 - **Hidden tags:** tags starting with a dot `.` (example `.secret`) are private. They can only be seen and searched when logged in.
  54 - **Exclude text/tags:** Use the `-` operator before a word or tag to exclude Shaares matching this word from search results (`NOT` operator).
  55 - **Untagged links:** Shaares without tags can be searched by clicking the `untagged` toggle button top left of the Shaares list (only when logged in).
  56
  57 Both exclude patterns and exact searches can be combined with normal searches (example `"exact search" term otherterm -notthis "very exact" stuff -notagain`). Only AND (and NOT) search is currrently supported.
  58
  59 Active search terms are displayed on top of the link list. To remove terms/tags from the curent search, click the `x` next to any of them, or simply clear text/tag search fields.
  60
  61
  62 ### Tag cloud
  63
  64 The `Tag cloud` page diplays a "cloud" or list view of all tags in your Shaarli (most frequently used tags are displayed with a bigger font size)
  65
  66
  67 - **Tags list:** click on `Most used` or `Alphabetical` to display tags as a list. You can also edit/delete tags for this page.
  68 - Click on any tag to search all Shaares matching this tag.
  69 - **Filtering the tag cloud/list:** Click on the counter next to a tag to show other tags of Shaares with this tag. Repeat this any number of times to further filter the tag cloud. Click `List all links with those tags` to display Shaares matching your current tag filter set.
  70
  71
  72
  73 ### RSS feeds
  74
  75 RSS/ATOM feeds feeds are available (in ATOM with `/feed/atom` and RSS with `/feed/rss`)
  76
  77 - **Filtering RSS feeds:** RSS feeds and picture wall can also be restricted to only return items matching a text/tag search. For example, search for `photography` (text or tags) in Shaarli, then click the `RSS Feed` button. A feed with only matching results is displayed.
  78 - Add the `&nb` parameter in feed URLs to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything.
  79 - Add the `&permalinks` parameter in feed URLs to point permalinks to the corresponding shaarly entry/link instead of the direct, Shaare URL attribute
  80
  81 ![](images/rss-filter-1.png) ![](images/rss-filter-2.png)
  82
  83 ```bash
  84 # examples
  85 https://shaarli.mydomain.org/feed/atom?permalinks
  86 https://shaarli.mydomain.org/feed/atom?permalinks&nb=42
  87 https://shaarli.mydomain.org/feed/atom?permalinks&nb=all
  88 https://shaarli.mydomain.org/feed/rss?searchtags=nature
  89 https://shaarli.mydomain.org/links/picture-wall?searchterm=poney
  90 ```
  91
  92
  93 ### Picture wall
  94
  95 - The picture wall can be filtered by text or tags search in the same way as [RSS feeds](#rss-feeds)
  96
  97
  98 ### Import/export
  99
 100 To **export Shaares as a HTML file**, under _Tools > Export_, choose:
 101
 102 - `Export all` to export both public and private Shaares
 103 - `Export public` to export public Shaares only
 104 - `Export private` to export private Shaares only
 105
 106 Restore by using the `Import` feature.
 107
 108 - These exports contain the full data (URL, title, tags, date, description, public/private status of your Shaares)
 109 - They can also be imported to your web browser bookmarks.
 110