From 91a21c272960889afd4eaa431a3d29b7785b6efc Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 16 May 2020 12:54:51 +0200 Subject: **General rewording, proof-reading, deduplication, shortening, reordering, simplification, cleanup/formatting/standardization** - standardize page names, rework documentation structure, update TOC - use same example paths everywhere - level 1 titles on all pages - fix broken links - .md suffix on all page links (works both from readthedocs and github repository views) **Server:** A full and concise installation guide with examples is a frequent request. The documentation should provide such a guide for basic installation needs, while explaining alternative/advanced configuration at the end. Links to reference guides and documentation should be used more frequently to avoid recommending an outdated or excessively complex configuration. - server: move most server-related info to server-configuration.md, cleanup/shorten - server: update list of php dependencies/libraries, link to composer.json - server: installation: support 3 install methods (from release zip, from sources, using docker) - server: installation: use rsync instead of mv as mv results will change depending of taget directory already existing or not - server: add example/basic usage of certbot - server, upgrade, installation: update file permissions setup, use sudo for upgrade operations in webserver document root - server: apache: add comments to configuration, fix and factorize file permissions setup, set cache-control header, deny access to dotfiles, add missing apache config steps, add http->https redirect example - server: nginx: refactor nginx configuration, add comments, DO log access to denied/protected files - server: add links to MDN for x-forwarded-* http headers explanation, cleanup/clarify robots.txt and crawlers section - server: bump file upload size limit to 100MB we have reports of bookmark exports weighing +40MB - i have a 13MB one here - server: simplify phpinfo documentation - server: move backup and restore information to dedicated page - docker: move all docker docs to Docker.md, simplify/ docker setup, add docker-compose.yml example, replace docker-101 with docker cheatsheet - troubleshooting: move all troubleshooting documentation to troubleshooting.md **Usage:** - index: add getting started section on index page - features/usage: move all usage-related documentation to usage.md, add links from the main feature list to corresponding usage docs, clarify/reword features list - shaarli configuration: add note about configuring from web interface **Removed:** - remove obsolete/orphan images - remove obsolete shaarchiver example - remove outdated "decode datastore content" snippet **Development:** - development: move development-related docs (static analysis, CI, unit tests, 3rd party libs, link structure/directory, guidelines, security....) to dev/ directory - development: Merge several pages to development.md - **Breaking change?:** remove mentions of 'stable' branch, switch to new branch/release model (master=latest commit, release=latest tag) - **Breaking change?:** refer to base sharing unit as "Shaare" everywhere (TODO: reflect changes in the code?) doc: update featues list/link to usage.md for details - development: directory structure: add note about required file permissions - .travis-ci.yml: add comments - .htaccess: add comment --- doc/md/Usage.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 doc/md/Usage.md (limited to 'doc/md/Usage.md') diff --git a/doc/md/Usage.md b/doc/md/Usage.md new file mode 100644 index 00000000..0a1b9719 --- /dev/null +++ b/doc/md/Usage.md @@ -0,0 +1,109 @@ +## Features + +For any item posted to Shaarli (called a _Shaare_), you can customize the following aspects: + +- URL to link to +- Title +- Free-text description +- Tags +- Public/private status + + +### Adding/editing Shaares + +While logged in to your Shaarli, you can add, edit or delete Shaares: + +- Using the **+Shaare** button: enter the URL you want to share, click `Add link`, fill in the details of your Shaare, and `Save` +- 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. +- Using [apps and browser addons](Community-and-related-software.md#mobile-apps) +- Using the [REST API](https://shaarli.github.io/api-documentation/) +- Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button. + + +### Tags + +Tags can be be used to organize and categorize your Shaares: + +- You can rename, merge and delete tags from the _Tools_ menu or the [tag cloud/list](#tag-cloud) +- Tags are auto-completed (from the list of existing tags) in all dialogs +- Tags can be combined with text in [search](#search) queries + + +### Public/private Shaares + +Additional filter buttons can be found at the top left of the Shaare list **only when logged in**: + +- **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) + + +### Permalinks + +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. + + +### Text-only (note) Shaares + +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. + + +### Search + +- **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. +- **Tags search:** `Filter by tags` allow only displaying Shaares tagged with one or multiple tags (use space to separate tags). +- **Hidden tags:** tags starting with a dot `.` (example `.secret`) are private. They can only be seen and searched when logged in. +- **Exclude text/tags:** Use the `-` operator before a word or tag to exclude Shaares matching this word from search results (`NOT` operator). +- **Untagged links:** Shaares without tags can be searched by clicking the `untagged` toggle button top left of the Shaares list (only when logged in). + + +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. + + +### Tag cloud + +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) + + +- **Tags list:** click on `Most used` or `Alphabetical` to display tags as a list. You can also edit/delete tags for this page. +- Click on any tag to search all Shaares matching this tag. +- **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. + + + +### RSS feeds + +RSS/ATOM feeds feeds are available (in ATOM with `/feed/atom` and RSS with `/feed/rss`) + +- **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. +- 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. +- Add the `&permalinks` parameter in feed URLs to point permalinks to the corresponding shaarly entry/link instead of the direct, Shaare URL attribute + +![](images/rss-filter-1.png) ![](images/rss-filter-2.png) + +```bash +# examples +https://shaarli.mydomain.org/feed/atom?permalinks +https://shaarli.mydomain.org/feed/atom?permalinks&nb=42 +https://shaarli.mydomain.org/feed/atom?permalinks&nb=all +https://shaarli.mydomain.org/feed/rss?searchtags=nature +https://shaarli.mydomain.org/links/picture-wall?searchterm=poney +``` + + +### Picture wall + +- The picture wall can be filtered by text or tags search in the same way as [RSS feeds](#rss-feeds) + + +### Import/export + +To **export Shaares as a HTML file**, under _Tools > Export_, choose: + +- `Export all` to export both public and private Shaares +- `Export public` to export public Shaares only +- `Export private` to export private Shaares only + +Restore by using the `Import` feature. + +- These exports contain the full data (URL, title, tags, date, description, public/private status of your Shaares) +- They can also be imported to your web browser bookmarks. + -- cgit v1.2.3 From 881bd96f151f9eefdac6264e432e573a657fc82b Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:09:14 +0200 Subject: doc: usage: active filters/clear search filters --- doc/md/Usage.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/md/Usage.md') diff --git a/doc/md/Usage.md b/doc/md/Usage.md index 0a1b9719..683b41c4 100644 --- a/doc/md/Usage.md +++ b/doc/md/Usage.md @@ -54,9 +54,10 @@ Shaarli can be used as a minimal blog, notepad, pastebin...: While adding or edi - **Exclude text/tags:** Use the `-` operator before a word or tag to exclude Shaares matching this word from search results (`NOT` operator). - **Untagged links:** Shaares without tags can be searched by clicking the `untagged` toggle button top left of the Shaares list (only when logged in). - 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. +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. + ### Tag cloud -- cgit v1.2.3 From 328c215a8ac28e8c6b542fad1120b26692c923c5 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Fri, 29 May 2020 22:24:44 +0200 Subject: doc: add note about importing browser bookmarks folder structure to shaarli tags ref. https://github.com/shaarli/Shaarli/issues/1449 --- doc/md/Usage.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/md/Usage.md') diff --git a/doc/md/Usage.md b/doc/md/Usage.md index 683b41c4..6dadde0a 100644 --- a/doc/md/Usage.md +++ b/doc/md/Usage.md @@ -108,3 +108,4 @@ Restore by using the `Import` feature. - These exports contain the full data (URL, title, tags, date, description, public/private status of your Shaares) - They can also be imported to your web browser bookmarks. +To **import a HTML bookmarks file** exported from your browser, just use the `Import` feature. For each "folder" in the bookmarks you imported, a new tag will be created (for example a bookmark in `Movies > Sci-fi` folder will be tagged `Movies` `Sci-fi`). -- cgit v1.2.3